How to create a real MVC app using umbraco


I have revisited this post, please read this one as well!

Last week my coworkers and I, where discussing how to build a real mvc app using Umbraco. The starting point was quite simple, we started by simply dissecting each element in an umbraco site to be able to see the greater picture.

This is what we came up with:

  • Umbraco is a Content Management System, not a Content Delivery/Presentation System.
  • MVC is a framework to deliver/present content/data.
  • Models should contain all information needed by the view, and not contain any logic
  • A view should only present the model. It should not do more than that.
  • A controller should create and package a model with the data needed by the consumer. (In most cases, the view).

So with this in mind, we looked at how we used to do umbraco sites, both pre-MVC and with MVC, and we saw that we where actually not doing anything by the book. All of our views contained a mix of presentation (markup) and data access logic. In my line of work, we often come across working with “frontenders”. These are developers working solely with markup and client side scripting, and most knows nothing about .NET, C# or even the Umbraco API.

There are many ways to help these poor frontenders, as this excellent post, The right amount of separation of concerns in Umbraco Razor?, describes, we can help a lot by separating our logic from our presentation without making a big deal out of it. The only problem I see is that it still makes the frontenders able to mess with our code. In my point of view, the frontenders don’t need to know where the data comes from, or how it gets there. When the open a view, the only thing they should see is markup and a minimum amount of server side code, and this is what MVC allows us to give to the frontenders. It also allows us to be the developers and not think about any of the views. We only serve a model to our frontenders, so they can use it to create an awesome site, without thinking much about C#, API’s or whatever.


So lets get started with our umbraco MVC app. First off, we need to setup our solution with anything we need:

Open Visual Studio, and create an empty MVC application, yes it must be empty. Then install umbraco cms using nuget.

Open the /config/umbracosettings.config and change the following line:




And run the application (F5), install umbraco and log in to the backoffice.

For this example we will create two doc types:


This one should NOT have a template! This doc type contains shared properties for all child doc types.

Create one property:

Shared value property

Shared value property

That’s it.


This should have a template, and be a child of MasterDocType! Further more, this doc type should be allowed at root-level.

Create a couple of properties:

Frontpage properties

Properties to go on the frontpage


Now create a node in the content section, call it whatever and add some values to our properties.


Now we have our doctypes setup, and we have added some content and all is good. But now it’s time to create our models. If you have not already done so, now would be a good time to stop the Visual Studio debugging session (Shift+F5).


I always suffix all my models with “Model”. This way, I can always distinguish my models from my entities or other classes.

Umbraco makes a great effort to tell you to make all your models derive from Umbraco.Web.Models.RenderModel. This is a BAD idea. By inheriting from RenderModel, we add logic to our model, and allows our views to access the umbraco engine, and we will have to add constructors to all of our models.

So I will not inherit from RenderModel, I will just create a simple model like so:

public class MasterModel
    public string SharedValue { get; set; }

Simple, and quite readable. No logic, only a single property with a getter and a setter. Nothin’ more, nothin’ less.


Again this is also quite simple:

public class FrontPageModel : MasterModel
    public string Title { get; set; }
    public IHtmlString BodyText { get; set; }

There are a couple of things to note here. First, I inherit from my MasterModel, just as I inherit my FrontPage-doctype from my MasterDocType. Secondly, my BodyText is of type IHtmlString. This is because I know, that the BodyText-property is a string containing HTML, and I would not like to clutter my views with unnecessary code like Html.Raw().


To simplify our controllers, we should create a couple of helper methods, to help us map from umbraco content to our models. In this example we need two mappers, I’ve created a folder for them called Mappers.

The general idea, is that instead of returning IPublishedContent, to our view, and thus adding logic to our view, we only return the values needed. So for instance you will list all child nodes, your model would look like this:

public IEnumerable<MyModel> Children { get; set; }

Instead of

public IEnumerable<IPublishedContent> Children { get; set; }

Thus giving the frontender an opportunity to know exactly what he is working with at the moment.


This mapper, has only one purpose, to set the shared values of all derived models.
Looks something like this:

public static class MasterMapper
    public static void Map(IPublishedContent content, MasterModel model)
        model.SharedValue = content.GetPropertyValue<string>("sharedValue");

This mapper is for mapping all content that is of the doctype, FrontPage.
It could look like this:

public static class FrontPageMapper
    public static FrontPageModel Map(this IPublishedContent content)
        if (!content.IsDocumentType("FrontPage"))
            throw new ArgumentException("Wrong doctype passed, must be FrontPage");

        var model = new FrontPageModel()
            Title = content.GetPropertyValue<string>("title"),
            BodyText = new HtmlString(content.GetPropertyValue<string>("bodyText"))

        MasterMapper.Map(content, model);

        return model;

Please note, I start by checking if we are trying to map the right doctype, if not, let the developer know he’s an idiot.
Second, note I finish up by calling my MasterMapper to set my shared value.

This mapper allows me to return the same data, each time I want to get a frontpage.


Now for the fun part: Creating our controllers.

As this is an umbraco application after all, we still need to oblige to the rules of naming, meaning that our controllers must be name exactly after our doctypes.


All our controllers, must run in UmbracoContext, because of the fact that we need to be able to access umbraco content, simple as that. Therefore all controllers must inherit from Umbraco.Web.Mvc.RenderMvcController. No problems here.

So we create a doctype for our MasterDocType:

public class MasterDocTypeController : Umbraco.Web.Mvc.RenderMvcController

In this example, I don’t need any logic in here, but I like to have this controller, just in case.


Now you probably think, this controller has all the exciting code, all the code that makes any of the above code seem unnecessary, you are wrong.

In this example, a very simple one, I know, I have not much code here:

public class FrontPageController : MasterDocTypeController
    public ActionResult FrontPage(RenderModel renderModel)
        var model = renderModel.Content.Map();
        return View(model);

What I do here, is simply mapping my content, to my model, and returning it to the view. If I wanted to list any child nodes, it would look like so:

public class FrontPageController : MasterDocTypeController
    public ActionResult FrontPage(RenderModel renderModel)
        var model = renderModel.Content.Map();
        model.Children = renderModel.Content.Children.Where(c => c.IsDocumentType("SomeDocType")).Select(c => SomeDocTypeMapper.Map(c));
        return View(model);

This way, all my childnodes, are of the right type, and does not contain any logic.


The final part of this post, will be Views.

Again, Umbraco goes a long way to tell us how to build our views, but as I stated earlier, Umbraco is NOT a Content Delivery/Presentation System. So it should stay out of our views.

Umbraco wants us to make all of our views inherit from either Umbraco.Web.Mvc.UmbracoViewPage<> or Umbraco.Web.Mvc.UmbracoTemplatePage. By doing so, we are actually adding logic to our views, and therefore making it much harder for frontenders to build the view. So instead we want to just specify the type of our model, the view is build around. This is done by writing @model NameOfTheModelType.

To get started with our MVC-views, we have to do some ground work first:


As any web app, we must have a generic master layout file, that sets up all markup used by all views. I prefer naming this view _Layout.cshtml, put it in /Views/Shared/.

This layout file would, in this example look like this:

@model UmbracoMVC.Models.MasterModel
    Layout = null;

<!DOCTYPE html>

    <meta name="viewport" content="width=device-width" />
        <hr />

Note the first line of this view, it states that this view, is build around the MasterModel. We also specify that this view has no layout.


If you have ever made an MVC app, you’ll know that any view, that is not a partial view, will find its master-layout using the _viewstart.cshtml-file. So we will have to add this to the views folder.

    Layout = "/Views/Shared/_Layout.cshtml";

It specifies, that if no other Layout is specified, then any view, should use the /Views/Shared/_Layout.cshtml-view.


This view, is used to deliver the actual contents of our frontpage. As with the controllers, we are bound by the rules of umbraco, and all views must be located in the Views-folder. It’s quite simple:

@model UmbracoMVC.Models.FrontPageModel
    ViewBag.Title = Model.Title;

As you can see, there is a bare minimum amount of logic, only markup and property getters. Nothing more, nothing less.


This is a rather long post, and I haven’t covered nearly much on how to build a real MVC app, using umbraco, but I hope it gives an idea what can be done.

This approach, might take a bit more coding, but when we have done this a couple of times, and made a couple of frameworks with reusable code, then we can really get things done, and fast. We no longer have to battle with logic in our views, we don’t have all the string literals floating around our code, to identify properties. We have successfully separated views from Umbraco, and thus made our views cleaner and our controller logic simpler.

I hope this post, will spark a debate on how to develop MVC apps for umbraco in the future. Please share, and comment.

Thanks for reading.

20 Responses to How to create a real MVC app using umbraco


    I’ve been playing around with your approach and I like it. I thought perhaps though it might be a good idea to make the Map() method more generic.

    Here’s an example gist of what I have done.

  2. Good to hear 🙂

    I have thought about doing a generic version of the mapper myself, but it is not at simple as one might think.

    A viewmodel may contain more than just simple property values from the node, it might contain nodes, media, content from RichText editors, numbers, bools, custom datatypes and so on.

    To be able to handle those, generically, we need a way to identify these special properties. My thought would be by adding attributes to the models, Allowing the mapper to choose which mapping method should be used.

    I have yet to build a PoC on that. Might be a separate blog post.


    Yeah, I’ve only done some light testing so far as it’s POC.

    RichText editors, numbers, bools are fine as they map to standard types. Convert() will sortt that. Custom datatypes though will as you say need more work, I’m using uSitebuilder which maps custom types somehow using attributes so I will look into that.

  4. RichText-editor is pitfall.

    Its a string, but it will be html-encoded if not passed through @Html.Raw().

    I recommend, typing the model-property with IHtmlString, on then for each richtext editor, create a new HtmlString().

    Then you don’t need the Html.Raw() in your view.

    A rich text editor, is essentially an Html-string.


    Is the defaultRenderingEngine setting in umbracoSettings.config case-sensitive, and should be “Mvc” ? Excellent article by the way, wish I had come across this sooner!

    • hi, and thanks,

      I don’t think it’s case sensitive, I haven’t seen anything to suggest that.

      And yes, it should be mvc.


    Thanks for this. I have just started using Umbraco and recently build my first commercial site using it, but I was becoming unhappy with the amount of code I was putting inside views. This is a much better way of doing things.

    • Hi,

      Glad you could use it. If you have any questions, please feel free to ask them.


    My RenderModel Class has no Map() function … neither does source control :

    Am I missing something?

  9. Hi,

    In this blog-post, Map() is an extension method, Take a look at the FrontPageMapper-example above.

    But, before you do too much work,please take a look at my revisit:

    There, I have killed off the mapper-extension methods and made my solution a bit more MVC’ish. And I have a fully functional example project.


    Sorry I havent slept … IPublishedContent has no Map() interface method.. hmm


    Yikes I dont know how to delete or reply in this thing!! Sorry, thanks ill read

  12. Of course it has no Map() method. I am Building that as an extension method.

  13. Just saw, your latest post. Think I need to update my comment system 🙂


    Hi, Thanks for sharing a great knowledge with us.

    Build MasterModel that way is what we know as: Side Effecting Functions that are Code Smells”.

    Is there any other way to create a MasterModel without side-effecting?



    I’m not familiar with that term, but a quick search suggested that the models themselves are not “side effecting”.

    However, the controller inheritance in this post is. I would highly recommend looking at my revisited post, where I have changed this a bit, and I’m about to write a third one describing in detail how to avoid cluttering models or the need to manipulate models after releasing them from the controller.

    In short, we have stopped using inherited models, and are now building clean, flat, models. We then have a single master controller setting a “Global” model, containing SEO and other global stuff, and pass that model to the view, using the ViewBag.

    This way we have a clean model, with only the properties necessary for a particular view. And a Global model, hidden in the view bag, for menus, SEO and so on.

    Hope this helps.


    Hi Nick,

    Thanks for this structure. It’s a great start, even for experienced developers it is hard to find a good code class structure for Umbraco. Very helpfull.



    I used your example and it’s grate.
    I have a problem related to properties of type Grid. In this moment I have @CurrentPage.GetGridHtml(“content”, “fanoe”) but if I use your’s approach i don’t have access in view to CurrentPage.

    Any suggestions?
    Thank you!

  18. Hi Lazau,

    As you have noticed, you cannot access CurrentPage from the view.

    However, you can access CurrentPage.GetGridHtml from the controller.

    From here, you can set a property on your model, to the returned value.


leave your comment