Getting Started With Umbraco

So by day I work a lot with Ektron and Sitecore. But lately I’ve been doing more on side projects with Umbraco, a free ASP.NET CMS. For one, it’s free, which is a price I can always afford. And also, it (by default) uses MVC instead of web forms, so it was a good way to get my feet wet.

I recently finished up the first part of a project for a friend using Umbraco, which involved doing a number of two-way forms, forms in modals, and using a few of the features of the CMS. In the process of doing this, I found a lot of information all over the place, some of it outdated to the latest version (7.2.1 as of this blog). So I wanted to consolidate those things somewhat and invite discussion on better ways to do things that maybe I missed.

So to start, we have to set up a project. If you go to the Umbraco website, they have a number of ways to get the CMS, including a direct download and Microsoft Webmatrix. These methods tend to lead to a web site project, and as anyone reading my Ektron blogs knows, I don’t like them. Fortunately, there’s a way to use web application projects. I’d tried this before, but it was throwing errors when I ran the site…as of 7.2.1, it’s working fine, so let’s go.

I’ll assume you’re using Visual Studio 2013 to start. Go to File -> New -> Project, then use “ASP.NET Web Application.” When you select the project template, choose the “Empty” template (all of the code and references you’ll need will come with Umbraco). Once the project is created, go to Tools -> Manage NuGet Packages -> Manage NuGet Packages for Solution, then search for “Umbraco Cms;” it should have the latest version. While you’re in there, you might want to grab some of the other “standard” items you’ll need for a website, like JQuery, Bootstrap, etc.

After this, go ahead and start the project up in debug mode so Umbraco can finish installing and add a few more parts. After the installation, Umbraco will ask you to fill out an account; I would suggest you use the “Customize” button to select the type of database you install to (otherwise you’ll get SQL CE and a file in your App_Data folder) and whether you want to use a template (one installs by default otherwise). When you’re done, here’s what will be in your project (showing all files with Bootstrap and JQuery installed):

As you can see, you have a group of folders that show some mix of web site project and web application project. You’ll also notice references to web forms items, like master pages and user controls, that are not needed if you’re using MVC (which is the default, but can be changed). Also, if you’ve used Umbraco before, you’ll notice the “umbraco” and “umbraco_client” folders (the heart of the CMS) aren’t included in the project, but don’t worry, when you do a build or publish they’ll be transferred, as will some of the “App_” folders. So let’s look at some cleanup I suggest you do.

Open the “css” folder, and you’ll see a “dummy.txt” file that NuGet left so that the folder would be created for you in the package. Copy this file to the “App_Code” folder. Umbraco still looks for this folder, even though this is a web application project, and will throw an error if it’s not there. The package publish will copy the folder over without it being in the project, but not if nothing’s in there. You’ll never need this again, so don’t include it (code put in there would just copy over, not compile).

Include the “App_Data” folder in your project. This folder is not in the package publish, but you’ll need it for at least the first publish to establish your database. If you want, you could leave it excluded and manually copy it over to your publish location, that’s up to you.

Delete the default.aspx file…you don’t need it.



Open your global.asax file. You’ll see a “codebehind” reference there that, if you have Resharper, you’ll notice is showing an error because there is not code-behind in the project. You can remove the reference safely.

In the web.config, add some key/value pairs in the appSettings to change where Umbraco is looking for some of the legacy content. You can’t just delete the “masterpages” and “usercontrols” folders, because Umbraco will throw errors looking for them. But, you can tell Umbraco to look elsewhere, and you do have other folders hanging around. Add these keys:

<add key=“umbracoCssDirectory” value=“~/Content/”/>

<add key=“umbracoMasterPagesPath” value=“~/Content/”/>

<add key=“umbracoUsercontrolsPath” value=“~/Content/”/>

<add key=“umbracoXsltPath” value=“~/Content/”/>



You’ll see I also changed the CSS and XSLT paths. The CSS path was because Bootstrap, when installed via NuGet, puts the CSS files in the “Content” folder (scripts go into the existing “scripts” folder). The XSLT path was because I’m not planning to use XSLT, so rather than keep that folder around, I’m pointing it to another spot so I can drop the folder. Delete the following folders: css, masterpages, usercontrols, xslt. If you didn’t reset one or more of those paths as noted above, don’t delete the folder.

You can turn off the “show all files” option and you’ll have a much cleaner looking project, as shown below.

That’s it. If you run this project again in debug mode, or set up a publish profile and push it somewhere (even locally for your local IIS to use), everything will work just fine. The next step will be to start working with the CMS to set up an application, and how to use standard MVC with Umbraco’s use of it to expand your capabilities.

Again, I’m still new to a lot of this when it comes to Umbraco and MVC, so if anyone has thoughts on how to do something better or more efficiently, please let me know in the comments or on Twitter!