Adding an MVC (or other .NET) application in Umbraco CMS 4.7

Adding an MVC Application to Umbraco caused me a lot of headaches, and since I couldn’t find an easy answer on Google (it took me hours to figure this out), I decided to post how I got a .NET MVC project to run in a subdirectory of my Umbraco Installation (v4.7).


–          Install Umbraco 4.7 using Web Platform Installer (WPI) or from the Umbraco Installation files (see my guide here to installing with WPI). WebMatrix takes a few shortcuts when it sets up Umbraco and you might run into a few issues.

–          Create a blank MVC 3 Application.

  • Open Visual Studio 2010
  • File–>New–>Project–>Installed Templates–>Web–>ASP.NET MVC 3 Web Application. Give it a name (I called it “UmbracoPOC”). If ASP.NET MVC 3 Web Application is not an option, you need to first download MVC 3 from Microsoft’s website here.
  • Select View Engine:Razor and leave HTML5 checked (or you can modify these to whatever you need, but since you’ll likely be using Razor for Umbraco (and Razor is awesome), you might want to keep consistent by using it here as well.
  • Publish it so it’s ready to be deployed to web.
    • Set the publish settings to “Release” instead of “Debug” by clicking Build–>Configuration Manager–>Active Solution Configuration–>Select Release.
    • In Solution Explorer, right click on your Project name (the second line down – not the Solution name) and click “Publish”.
    • For Publish Method, select “File System
    • Set your target location anywhere. I put mine on the Desktop\UmbracoPOC
    • Click Publish

–          Now you need to copy the MVC 3 Application to a subdirectory that you create within your Umbraco root folder. My Umbraco root installation was located at C:\inetpub\wwwroot\UmbracoDemo and my MVC Application was published to C:\Users\[Myname]\Desktop\UmbracoPOC so I copied the folder from my desktop into the UmbracoDemo folder.

–          Now, you need to modify IIS (or whatever web server your using) to treat the UmbracoPOC folder as its own sub site.

  • Open Internet Information Services (IIS) Manager.
  • Expand your computer and the “sites” folders.
  • Expand the Umbraco Web Site (in my case “UmbracoDemo”)
  • You should see the UmbracoPOC folder inside your Umbraco site. Right click on it and select “Convert to Application”.
  • Leave everything the same (including application pool – which should be by default set to your Umbraco Site’s Application pool) and click OK.
  • Close out of IIS Manager.

–          The last thing you need to do is modify the web.config of your Umbraco Installation so that Umbraco doesn’t try to route your MVC 3 site and cause issues.

  • Browse to your Umbraco Site’s root folder (My Umbraco root is “c:\inetpub\wwwroot\UmbracoDemo”) and open up “web.config” in Visual Studios 2010 or any other text editor.
  • Locate the section called “<system.web>” and encapsulate the entire thing with the following code:
<location path="." inheritInChildApplications="false">
  • So, it will look like this:
<location path="." inheritInChildApplications="false">
<customErrors mode="RemoteOnly" />
  • And you’ll have to do the same thing in two more places… around the “<system.webServer>” section and near the end of the document at the “<system.web.webPages.razor>” section.

–          Finally, you’ll have to add the folder containing your MVC 3 Application (in this case UmbracoPOC) to the reservedPaths section in the web.config file.

  • In the same file you have open from the last step, locate the following code:
<add key="umbracoReservedPaths" value="~/umbraco,~/install/" />
<add key="umbracoContentXML" value="~/App_Data/umbraco.config" />
  • And add the folder that contains your MVC 3 Application to the reservedPaths like this:
<add key="umbracoReservedPaths" value="~/umbraco,~/install/,~/UmbracoPOC/" />
<add key="umbracoContentXML" value="~/App_Data/umbraco.config" />
  • Save your web.config. Due to folder permissions, you may have to Save the web.config to another location, such as your desktop and manually copy the file into the Umbraco root folder and allow it to overwrite the old web.config.

–          And that’s it! Your MVC 3 Application should now be accessible. Open up a web browser and browse to your MVC 3 Application’s folder (ie. “localhost/UmbracoPOC”)!

About the Author: Scott McCown

I'm an IT Consultant for Pariveda Solutions, an IT consulting company based out of Dallas, TX (and might I add the best IT consultant company to work for). I enjoy honing my development and management skills so that I can better serve the needs of our customers.

10 Comments + Add Comment

  • I reached to the same solution also.

    I know that Mark’s solution http://memoryleak.me.uk/2009/04/umbraco-and-aspnet-mvc.html is high ranked on google search but this approach seemed very clean.

    Did you succeed to use the templates from umbraco in the mvc application?

  • Thanks for this it has saved me hours.

    I do have one issue however. I cannot access the admin part of umbraco using the /umbraco as i get a error stating:
    umbraco tried this to match it using this xpath query’/root/*/* [@urlName = “umbraco”] | /root/* [@urlName = “”]’)

    Do you have any thoughts on this?

  • Awesome. Exactly what I wanted. Every step is accurate

  • This article helped me a lot! Thanks!

  • Experimenting with trying to run a simple test Razor (WebPages2) site within Umbraco using the steps you suggested, but in the end I get a “this type of page is not served” error, suggesting it can’t serve .cshtml pages from within that app.

    I’m not super adept at figuring out why this Razor site won’t run; created the package of files from visual studio. Our regular site is nwcouncil.org, so I put this in nwcouncil.org\razorsite, and converted the folder to an app with IIS. But it still won’t get past the cshtml error.

    thanks for any assist

  • Thanks for the helpful article. I followed your article and got the Umbraco 6+ site up and running. When I try to access the localhost/UmbracoPOC, I am getting error like “cannot open the database….”. FYI, as of now my Umbraco database and UmbracoPOC database are different database which I am planning to merge later.

    Please advise what could be the issue.

  • 3.5 years later, with Ubraco 7.2.1 and MVC 4.5, this is still a viable alternative to route hijacking and retrofitting MVC controllers to play well with Umbraco!

    I needed a way to bring my custom controllers — that had no benefit from being integrated with the CMS — into my Umbraco site, and this was the perfect solution. Saved me a ton of time.

    Thanks, Scott!!!

  • Well, I think I spoke too soon. After following your instructions, my MVC app was working, but I found out later that the Umbraco backoffice was no longer functional. I removed the “location” tags that I had added to the web.config file and I can now edit Umbraco content again. Of course, I lost the MVC app again as a result.

    Guess I will have to look harder at route hijacking… :-/

  • @Tim :

    I ran into the same problem you did. To fix it, you have to delete the following section. Everything is in working order now !

  • I had the same problem and the location tags fixed it but broke Umbraco. After a quick Google of the error message I found this article which fixed the issue (Basically comment out the httpModules in the web.config).


    Thanks for the article – helped me out a lot!