Setting up Umbraco 6 in Visual Studio 2012 for MVC development

The starter packs provided on the Umbraco 6 default installation are good, but in case you need to build a complete new UI design as per your clients requirements then its far easier to start with a blank slate rather than try to mend an existing design to suit your requirements. If you want to move further and start developing forms etc. then its best to setup Umbraco 6 as a Visual Studio project so that you can debug your code. Umbraco provides two kinds of rendering engines for your pages, it can work in traditional Web Forms (its default engine) as well as it can user Razor with MVC. I personally find the HTML generated by MVC to be much clean, and better suited for building responsive html5 based applications. In this short blog post I am detailing the steps required to setup Umbraco 6 in Visual Studio 2012 as well as configure it to use MVC rendering engine. This blog post seeks to serve as a starting point for various other Umbraco development post that I plan to write.

Setting up Visual Studio 2012 project

Fire up VS 2012 and start a new ASP.NET MVC 4 Web Application project give it a name and save it to your preferred location and click OK as shown in Figure 1 below.

Figure 1: Create new ASP.NET 4 MVC Web Application

Select the Basic MVC template so that we get the required MVC JavaScript's and configuration, the View engine will be the default Razor engine and click OK to create the project as shown in figure 2 below.

 
Figure 2: Select Basic MVC template

Now that the MVC project is set up we need to add the Umbraco Core nuget package to the project. Right click the project name in the Solution Explorer window and select Manage NuGet Packages from the context menu. Select the Online packages and search for Umbraco as shown in figure 3 below.

Figure 3: Search Umbraco NuGet package

As you can see from the above figure 3, two packages are displayed which are relevant to our project. Umbraco Cms core Binaries package just adds the Umbraco assemblies to the project but it does not add the other folders and files required to manage Umbraco, this is the package you need to Install by clicking Install in the above screen. The other package shown Umbraco CMS should be used if you plan to use Umbraco in Web Forms project, but if you import it in an MVC project it overwrites basic MVC configuration making the project unusable! I believe in future there would be MVC specific package as the popularity of MVC deployments grow. In our case click on Install for the Umbraco Cms Core Binaries package to install it from the internet along with its pre-requisite packages automatically. Once you have the package installed the optional but recommended step is to click on Updates and update all the packages listed so that you have the latest versions of all the packages to work against. This is very useful since if there are any bug fixes in the packages since the initial template was built those are downloaded into your project. Once all the packages are updated click on Close to close this dialog.

Now there is a manual step to get rest of the Umbraco files imported into your MVC project. Go to the Umbraco download website and download the latest recommended download file. An important point to check is if the version of the NuGet package you installed in VS matches the version of download which is available. At times when new releases are made, it takes a while for the new packages to be available on NuGet while they are available on CodePlex. So ensure that you have matching versions of NuGet package binaries and the project files. Once the file is downloaded, extract it to a temp folder. Open the extracted folder in Windows Explorer and select all folders except App_Code (since that folder is not required in MVC – its an empty folder) and copy it into your Visual Studio Project folder. Figure 4 shows the extracted Umbraco 6.0.3 folders

Figure 4: Extracted Umbraco folders

As you copy the Umbraco extracted folders into your VS project folder you will get a warning as shown in figure 5 to replace or skip duplicate named files. Click Replace the files in destination so that all Umbraco files are correctly copied into the project.

Figure 5: Replace files in VS project with Umbraco files

Switch to Visual Studio and in Solution Explorer window click on the Show All Files icon so that all files present in the project folder but not added to the project are displayed as shown in figure 6. Right-click on each of the greyed folders (except bin and obj folders) and select Include in Project to include the folder and files contained within it to our Visual Studio project.

Figure 6: Show All Files in Solution Explorer

Once you have included all the hidden folders and files in your project, the Visual Studio integration is completed. Now we proceed to the configuration steps.

One important point to note is that when you will be testing and building your application Visual Studio will be using IIS Express to run Umbraco. In my testing I have found that if you try to install Umbraco in IIS under the default website then it stops working! In case you need to configure Umbraco in IIS, then you will have to use IIS to create a new Web Site specially for Umbraco. Unlike as mentioned on the Umbrao Wiki pages I have not being able to get Umbraco 6.0 work under Default Website in IIS7.

Configuring Umbraco 6 to user MVC/Razor rendering engine

Umbraco has made it very easy to modify its settings and has split different configurations into separate config files placed in the config folder. In solution explorer, expand the config folder and open umbracoSettings.config file. This file has some important settings required for Umbraco engine to work correctly so its good to study this file to learn the kind of settings allowed. Go to line number 149 and change the defaultRenderingEngine setting to Mvc (please make sure you have the case correctly) as shown in listing 1 below.

<templates>
  <!-- If you want to switch to Mvc then do NOT change useAspNetMasterPages to false -->
  <!-- This (old!) setting is still used to control how macros are inserted into your pages -->
  <useAspNetMasterPages>true</useAspNetMasterPages>
  
  <!-- To switch the default rendering engine to MVC, change this value from WebForms to Mvc -->
  <!-- Do not set useAspNetMasterPages to false, it is not relevant to MVC usage -->
  <defaultRenderingEngine>Mvc</defaultRenderingEngine>
</templates>

Listing 1: Updated Rendering Engine in umbracoSettings.config

Save the config file and your Umbraco is set to use MVC, but if you stop just here the pages you create will still carry the *.aspx extension. You need to make one more config change to enable typical directory type URL’s, its called as Friendly URL’s in Umbraco lingo and you can find more information on configuring it here. I am assuming you have IIS7 onwards and the setting below are considering you are using IIS7 onwards. Open the web.config file from Solution Explorer and change line 45 to the following

 <add key="umbracoUseDirectoryUrls" value="true" />

Listing 2: Updated umbracoUseDirectoryUrls property in web.config

Move to line 194 and update the setting to as shown below.

<add name="UrlRewriteModule" type="UrlRewritingNet.Web.UrlRewriteModule, UrlRewritingNet.UrlRewriter" preCondition=""/>

Listing 3: Updated UrlRewriteModule setting in web.config file

Save the web.config file and now you are ready to get started with MVC development. You can build the project and hit F5 to run it. Your browser should load up the Umbraco Installation screen as shown in figure 7 below. Follow the on screen instructions get your application configured.

Figure 7: Umbraco Installation screen

Installation of Umbraco 6

The steps shown below are completely optional but still its good to know for those who are getting started with Umbraco development. In your browser click on the Let’s get started! button as shown in figure 7 above. On the next license screen click on Accept and Continue to move forward. Now you are shown the Database configuration screen. You can select the database of your choice, I like to use SQL CE 4 during testing and development since it lightweight and easier to move around since all you need to do is copy the folder and all settings get transferred over. Figure 8 shows the SQL CE 4 selected as the database. Click Install to install the appropriate selected database and move to the next step.

Figure 8: Umbraco Installation – Database configuration

After database installation is done you will see a confirmation message as shown in figure 9 below, click Continue to move ahead.

Figure 9: Database Installation completed

On the Create User screen provide the details to create the admin user. This user will have access to the Admin control panel of Umbraco and all details of the user can be changed at a later stage from within Umbraco. I create the user using temporary credentials, please make sure that you use your strong credentials. Click Create User to create the user and move ahead.
Name: Admin
Email: admin@systenics.com
Username: root
Password: @123test

Figure 10: Create user

Once the user is created you are given the option to select a start kit. Most of these pre-defined start kits are based on Web Forms, so we can’t user them. Also if you want to create your own site from scratch then its best to not use any of these start kits. Select No Thanks I do not wish to install a start kit image as shown in figure 11 below to setup Umbraco without using an existing starter kit. A confirmation prompt will open up asking you to confirm your select, click OK to proceed.

Figure 11: Do not Install a start kit

The above steps will finish configuration of Umbraco and you will be presented with a confirmation screen as seen in figure 12 below. This completes the configuration of a blank Umbraco 6 installation with MVC being used as the Rendering engine. But remember since we did not chose to use a Start Kit our site will be blank and it needs content defined before you can publish or deploy the site. Its out of the scope for this blog post to define how to configure your site, please consult the Umbraco Documentation for further advice. You could also optionally import Standard Website MVC package to get a basic MVC Website setup.

Figure 12: Umbraco Installation Completed

In this short blog I have tried to cover the essential steps required to configure Umbraco 6 to user MVC/Razor as the rendering engine. I plan to build on this configuration in my future blog posts.

Download Sample

Click here to download the sample for this blog.