What Is An Umbraco Surface Controller?

I’ve talked previously about route hijacking, Umbraco’s way of letting you use MVC within an Umbraco website.  In today’s guide, we’ll take the process one step further and talk about Surface controllers  and discuss what they are, when you would use one and why they are useful for you when you are building Umbraco MVC websites.

What is a surface controller?

When we work with plain old MVC, controllers are defined by creating a class and inheriting from ‘Controller’.  A surface controller is an Umbraco specific controller, that inherits from the normal MVC controller so it can do everything a normal MVC controller can do, as well as providing other useful Umbraco related things.

These Umbraco related things are essential if you want to use forms within your pages.  So, if you have a standard web page that renders some basic text, then you can use a normal MVC controller, or, more likely the RenderMvcController.

If you need a page that needs interaction, like a log-in for a contact us page etc..  then you will have to use a surface controller as the type your controller class inherits from.  Put as simply as possible, if you need to process some form of user input on your page, use a surface controller.

As mentioned the surface controller knows about Umbraco, the current page and Umbraco related pipeline data that a normal ASP.NET MVC controller wouldn’t.

Like, my route hijacking tutorial when you work with Umbraco and MVC you’ll be creating views, models, and controllers.

To create a surface controller, if you have an existing ‘Controllers’ folder create a new class.  Your controller’s name needs to always end in SurfaceController.cs.  This class will also need to inherit from SurfaceController in order for Umbraco to hook up it up with everything it will need.

using Umbraco.Web.Mvc.SurfaceController;
public class LoginPageSurfaceController : Umbraco.Web.Mvc.SurfaceController
public ActionResult Index()
return PartialView("LoginPage", new LoginPageViewModel());
public ActionResult SubmitForm(LoginPage ViewModelmodel)
// Do stuff

The code above is pretty straightforward.  I’ve defined two actions, one to render the page and one to deal with the log-in pages submission.  It’s the surface controllers job that will allow the form submission bit to work.  In the example above, for brevity, I’ve missed out a lot of code.  If you want to create a log-in page, then I suggest you read, How To Create a Log-in Page With Umbraco 7 which will fill in all the gaps.

If you tried to post back to a controller without it inheriting from the Surface Controller, Umbraco wouldn’t know which controller to call.  Writing Umbraco MVC, as you can see is very similar to normal ASP.NET MVC.

Surface Controllers Take Away

If you need to get information back from your users, whether it be a form, a log-in page etc.. you will need to use a surface controller in order for the postback to call the correct controller. As you can see from the code above, except for a few differences like the name you have to call your controller and the type you inherit from, the code looks pretty much the same as a standard MVC controller. This is because Umbraco isn’t rewriting the rule book, instead it’s working with the framework and adding hooks in at certain points.

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

More Posts

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *