Building Umbraco 4.5.2 From Source Code

These days I’ve been spending most of my time drilling into Umbraco – and one of the questions that I’ve been asked quite a few times over the last couple days is “How do I successfully get a working build going from the source code so that I can step through the core and experiment with the code.”  Given the number of times I’ve been asked that question over the last couple days – and the general lack of a concise walkthrough based on a quick search (I did find one article here, but it was written a while ago for VS 2008) – I figured I would just jot down my experience into a post.  This seems like it should be a pretty straightforward activity – and for the most part it is – but there are a few things that can surprise you if you don’t know they are there.

1. Download the Source (from the right branch)

As I’m sure you already know, the Umbraco project is hosted on CodePlex at http://umbraco.codeplex.com.  If you click on the source tab, you’ll see the instructions for connecting to the repository using either a TFS or SVN client.  I use Tortoise, so I connected it up to https://umbraco.svn.codeplex.com/svn.

The next step is to figure out what the proper branch is for getting the latest release (4.5.2 at the time of this post).  This part is a bit counterintuitive (as noted here).  Long story short, even though the version you want is 4.5.2, the branch you want is https://umbraco.svn.codeplex.com/svn/branches/4.1.0.  On my machine, the checkout looks like the following:

2. Export the Source (Optional)

I’ve marked this as optional, though I would recommend that you export the folder you checked out from the repository into a clean directory tree where you can hack away without your version control client tracking (and bothering you about) changes that you will not be committing anyway.  ‘Export’ is the SVN command to create a clean tree from a version controlled folder – not sure what the equivalent TFS command is. 

3. Prepare the Web site

I started by creating an IIS app pool for running Umbraco on .NET v2.0 (I also have one for Umbraco running on .NET v4.0, but the code you downloaded targets v2.0).  Whether you create a new app pool or use an existing one, you’ll need to make sure that you give it permissions to access the folder where your source code lives.  In my case, I’m going to grant access at the ‘exported’ folder as I’ll be stepping through multiple Umbraco sites targeting multiple branches.  You can grant file system permissions to an IIS app pool by scoping the app pool name with ‘iis apppool’ as described here.

I then create a new site and point it at the ‘presentation’ folder within my exported branch.

4. Create an Umbraco database

This works exactly the same as if you were setting up an Umbraco instance from the binaries so I’m not going to spend time going over it again.  Here’s some documentation on setting up a SQL Express database (though in my setup, I use a full local SQL Server instance).

5. Open the solution file, build it, and navigate to your site’s setup wizard

Open the ‘umbraco.sln’ solution file using Visual Studio 2010.  Immediately, you should be able to build the solution and navigate to the site where you’ll be greeted with the standard Umbraco installation wizard.  Go ahead and walk through those steps – at the end, Umbraco should be fully operational running on your compiled bits.

6. Create a custom web.config transformation

One thing that you’ll notice when the project is loaded is that in the ‘presentation’ project is that that there are a whole bunch of XSLT files that look like they have something to do with the web.config file.  In fact, they do, and it wasn’t completely obvious to me how it worked until I cracked open the project file and noticed the following:

<Target Name="AfterBuild">
  <Copy SourceFiles="web.STANDARD.config" DestinationFiles="web.config" />
  <Xslt RootTag="" Inputs="web.config" Output="Web.$(COMPUTERNAME).config" 
    Xsl="web.config.$(COMPUTERNAME).xslt" 
    Condition="Exists('web.config.$(COMPUTERNAME).xslt')" />
  <Copy Condition="Exists('web.$(COMPUTERNAME).config')" 
    SourceFiles="web.$(COMPUTERNAME).config" 
    DestinationFiles="web.config" SkipUnchangedFiles="true" />
</Target>

As you can see from the target, after the build completes, the web.STANDARD.config file will be copied over as web.config.  Then, if you have added an XSLT file that follows the naming convention ‘web.config.{YOUR COMPUTER NAME}.xslt’ that XSLT file will be run using the web.config file as input and ultimately, the output of that process will become the final web.config file.  And while there might be some alternate strategies now-a-days to achieve the same result, this provides a nice way to maintain different configuration settings for your different machines without the classic strategy of commenting and uncommenting. 

It’s more than just a convenience, however, to ensure that you create a transformation.  Because this is run after every build, if you don’t create a transformation, your web.config file that is now all nicely configured to point to your newly setup database will be overwritten with default information if you do a rebuild.  And I’m guessing that you don’t want to copy over your connection string and other related settings after every build.

So like I said, add an XSLT file following the aforementioned naming convention and create templates for each of the settings you care about for your machine.  My transformation file (named web.config.WS-HOWARD-DEV.xslt) looks like the following:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:msxsl="urn:schemas-microsoft-com:xslt" 
    exclude-result-prefixes="msxsl">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template 
    match="/configuration/appSettings/add[@key='umbracoDbDSN']/@value">
    <xsl:attribute name="value">
        server=svrname;database='db';user id=umbraco;password=***
    </xsl:attribute>
  </xsl:template>

  <xsl:template 
    match="/configuration/appSettings/add[@key='umbracoConfigurationStatus']/@value">
    <xsl:attribute name="value">4.5.2</xsl:attribute>
  </xsl:template>

  <xsl:template 
    match="/configuration/appSettings/add[@key='umbracoUseDirectoryUrls']/@value">
    <xsl:attribute name="value">true</xsl:attribute>
  </xsl:template>

  <!-- copy everything else -->
  <xsl:template match="@* | node()">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()"/>
    </xsl:copy>
  </xsl:template>
</xsl:stylesheet>

7. Debug away…

From this point, you should be able to attach the Visual Studio debugger to the w3wp.exe and step through to your heart’s content.  Enjoy!