Surface Controller or Custom Controller in Umbraco 7?

Question

History

I'm a Web Forms developer with some .NET MVC experience, new to Umbraco and learning as I go.

So far I've been following the Umbraco documentation and videos to get set up which means all my controllers inherit from a "Controller Base" with common functions included, which in itself inherits from SurfaceController.

Recently however, I have noticed some bloggers and external reference material referencing RenderMvcController in the base class instead of SurfaceController - now the Umbraco documentation is unclear on the real differences between the two, nor which situations you should use them in.

The Question

Is there a clear and distinct difference between the imagined usage scenarios for a Surface Controller - inheriting from Umbraco.Web.Mvc.SurfaceController, and a Custom Controller - inheriting from Umbraco.Web.Mvc.RenderMvcController?

Thanks!

Salic

Answer 1

The documentation for the SurfaceController is here: http://our.umbraco.org/documentation/Reference/Templating/Mvc/surface-controllers

In a nutshell, the SurfaceController is used for helping to interact with views. So for example you could post a form to a surface controller. Or you could write a child action to a view with a SurfaceController

RenderMvcController is used purely for routing to published pages. So you could sub-class RenderMvcController in order to 'hijack' requests to published pages of a specific Document Type. See here http://our.umbraco.org/documentation/Reference/Templating/Mvc/custom-controllers.

Berrie

SurfaceController is also typically used to expose APIs that make use of Umbraco content. – Actinopod

Yes it can be but shouldn't be, since there is UmbracoApiController for this very purpose. The two main purposes of surface controllers are form interaction and child actions. – Berrie

Answer 2

To further clarify based on Digbyswift's answer:

SurfaceController = APIs or form targets (that then redirect)

RenderMvcController = custom logic to build a model or select a view for a content item (based on Document Type and, optionally, template)

Actinopod

Although you are right in that it can be used for APIs, I personally wouldn't recommend it. Umbraco provides the UmbracoApiController specifically for this purpose. This method has less overhead than using the SurfaceController. Also, Using surface controllers lumps all your API code in with MVC-specific form handling and child action code which I personally think isn't great. Separate routing can also then be defined for the API too. – Berrie

Good call @Digbyswift! – Actinopod