Hello, how do you do? In this article, I will gonna show you how to integrate ASP.NET MVC 4 using Umbraco. Note that Umbraco does not provide a “pure” MVC application as the Umbraco UI comes with a fair amount of webforms baggage. That said, it plays nicely with an MVC 4 project in Visual Studio and provides a flexible view rendering engine that lets you build genuinely testable page templates.
Setting up the project
Umbraco is shipped as an ASP.NET website which you can use directly, though this is not ideal. It is a better idea to create a full MVC 4 project, manage the dependencies using the Umbraco NuGet package and drop the Umbraco files directly into the site. Use the following steps to set up Umbraco as an MVC 4 project in Visual Studio:
Firstly, start an empty MVC 4 project in Visual Studio – make sure it is an empty project as you will not need any of the baggage that comes with other project templates.
Add the NuGet Umbraco Cms Core Binaries package which will manage the various dependencies and references that Umbraco 6 requires for you.
Copy all the files from the Umbraco installation ZIP archive directly into your project in Visual Studio except the App_Code and Bin folders – you won’t need the binaries as they are managed by NuGet and the App_Code folder is not used in a web application project.
The default mode for Umbraco is to use web forms rendering. You will need to switch this to use MVC by changing the defaultRenderingEngine setting in the Umbraco configuration file UmbracoSettings.config as shown below:
<templates>
<useAspNetMasterPages>true</useAspNetMasterPages>
<defaultRenderingEngine>Mvc</defaultRenderingEngine>
</templates>
Now you’re good to go – run the Umbraco site to set up the database and once the admin console comes up you can create a first view.
Note that you may optionally wish to remove the App_Start directory and Global.asax.cs files from your Visual Studio project – they are not used in a default Umbraco application as global.asax inherits directly from the Umbraco.Web.UmbracoApplication class and does not execute this code.
Creating a view
You can create a basic view in the Umbraco UI. In the “Settings” section create a new Document Type – call it “Home” and ensure that “Create matching template” is checked. A new file will be created in your Views folder with the following mark-up:
@inherits Umbraco.Web.Mvc.UmbracoTemplatePage
@{
Layout = null;
}
If you create and publish a first page based on this content type it will become your site’s home page. This is all you do to start creating pages based on MVC as Umbraco uses a default routing process that delivers the page properties to the view. You can actually build basic content pages without having to worry about the plumbing around controllers and models – this only starts to become important if you want to put more logic in behind the scenes.
Creating a custom controller
The default rendering engine for Umbraco routes requests through RenderMvcController with an IPublishedContent object as the model view. This provides a pretty simple means of basic pages rigged up with managed content but you can extend this behavior by creating custom controllers. Umbraco refers to this technique of creating custom controllers as hijacking, though really it is just a matter of creating a controller where MVC would normally look.
To create a controller for our Home view we just create a controller called HomeController. To hook it up to Umbraco’s content API you will need to inherit from RenderMvcController and override the Index method as shown below:
public class HomeController : Umbraco.Web.Mvc.RenderMvcController
{
public override ActionResult Index(RenderModel model)
{
//Do some stuff here, then return the base method
return base.Index(model);
}
}
Creating controllers to handle forms and actions is a little more involved as you have to create what Umbraco calls a surface controller. This is a controller like any other but one that is derived from the Umbraco SurfaceController class. These controllers can be implemented as a normal part of your MVC project (“locally declared” in Umbraco-speak) or implemented as a plug-in for shipping as part of a package.
If you want to include your own custom MVC routes then you will have to override the OnApplicationStarted method. This can be done by creating your own custom global.asax file that inherits from Umbraco.Web.UmbracoApplication.
Creating a custom model
Once you have wired up a controller it’s pretty straightforward to create in your own model and pass it into the page. You will need to change the view so that it inherits the generic version of UmbracoViewPage with your custom model specified as the generic parameter. The example below shows the view adjusted for a new model called HomeModel.
@inherits Umbraco.Web.Mvc.UmbracoViewPage<UmbracoMvc4.Models.HomeModel>
@{
Layout = null;
}
The controller will still accept a RenderModel object but you can pass your custom model by using the CurrentTemplate method as shown below:
public override ActionResult Index(RenderModel model)
{
HomeModel customModel = new HomeModel();
return CurrentTemplate(customModel);
}
If you want to take advantage of the Umbraco view helpers then you can extend the RenderModel object by creating a constructor that initialises the base class as shown below. This will ensure that your derived model still exposes the page data and current culture properly.
public class HomeModel : RenderModel
{
public HomeModel(RenderModel model)
: base(model.Content, model.CurrentCulture)
{ }
}
Beyond the basics
Although it is not a “pure” MVC implementation you can still get Umbraco 6 to sit quite nicely within an MVC 4 web application just so long as you set it up carefully. Beyond the basics of models, views and controllers there is support for features such as partial views and child actions as well as scope for you to use dependency injection and your IoC container of choice. So long as you’re prepared to ignore the messy webforms back-end that lurks in the background Umbraco 6 can really feel like working with an MVC 4 application.