In this tutorial and video, you will learn what is meant by route hijacking when it comes to Umbraco CMS development. Route Hi-jacking is a Umbraco concept that you will need to understand if you want create nice clean code with a good separation of concerns using Umbraco CMS. Sound good, read on 🎠 🎡 🎪 🔥

What is Route Hi-jacking?

Route hijacking allows you to use custom MVC controllers when building websites powered by Umbraco CMS. Route hijacking is a way to hook into the MVC pipeline so you can run custom code and view logic before a Umbraco page is rendered. Whenever someone visits your site, on a Umbraco website you can just define a view file and Umbraoc will do the routing for you. Following this approach usually means you have to add lots of logic in your view. Code wase this is architecturally very bad practice. MVC is about the separation of concerns. Adding logic to your views does not give this nice separation. This is why when you build a site using Umbraco you should always create a controller for each document type you define. The request is sent through IIS, the application is first loaded via the global.ascx file. This then and into Umbraco. Umbraco will then get the URL and figure out what document type it will need in order to render the page.

Umbraco will add all this information into the MVC pipeline and the page is sent back through IIS and displayed in the visitor's browser. With route hijacking instead of Umbraco sending the data back to IIS directly, the visitor's request will be redirected to a custom C# controller that you will need to write yourself. In this custom controller, you can then write any logic to meet your business needs. The one aspect I'm going to gloss over in this tutorial is the Umbraco part. To make route hijacking work, you need to create a document type in Umbraco. The name of the document type is very important because your controller will need to have the same name as the document type in order for Umbraco to be able to find it.

Setting Up Route Hi-Jacking

As route-hi-jacking goes hand-in-hand with MVC, we will need to create three things, a controller, a view model and a view. Let look at each step:

Route hijacking allows you to use custom MVC controllers when rendering document types powered by Umbraco CMS. Route hijacking is a way to hook into the MVC pipeline so you can run custom code and view logic before a Umbraco page is rendered. Whenever someone visits your site, with a route hijacked controller defined for a document type, when someone tried to view a page of that type, the controller code will be called. It is possible to render views directly bypassing the need for controllers when working with Umbraco. A lot of online tutorials do this. In terms of software architecture, not using a controller is bad practice when rendering a page. The purpose of the MVC pattern is to create a clean separation of concerns. Controller and view models will allow you to create a less decouple architecture.

When building a Umbraco website things are different compared to a normal MVC site. A URL will map to a page within the Umbraco database. A URL does not simply map to a controller and an action like it would in a vanilla MVC website. This means you can not simply create a controller and decorate it with the vanilla MVC Controller type. As the routing is different if you used a normal MVC Controller when you tried to view a page a 404 error would be thrown.

With route hijacking, Umbraco will take care of the custom routing. When a page request occurs, Umbraco will route the request to a custom C# controller that you will need to write yourself. In this custom controller, you can then write any logic to meet your business needs. To make route hijacking work, you need to create a document type in Umbraco. The name of the document type is very important because your controller will need to have the same name as the document type in order for Umbraco to be able to find it. I will not show you how to create a document type within the CMS in this tutorial, see my Umbraco playlist on my YouTube channel if you want to learn how.

Setting Up Route Hi-Jacking

As route hi-jacking goes hand-in-hand with MVC, we will need to create three things to get going, a controller, a view model and a view. Let us look at each step:

Model: Your model/view model will contain any data required by the view. In this simple example, I'm going to have a single method that when called will output the text 'Hello World'.

If you want your model to contain some key Umbraco properties, you can make your model inherit from RenderModel, pass in a type of IPublishedContent via the constructor and pass it down to the base type. YOu will see how to create a view model on Line14 in the controller code below!

View: In MVC the view is the file where we add HTML. The controller will pass the view model down into the view. Notice on Line 2, I define the exact type to bind the correct type fo the view. Any property that you define in the view model will be available to use in the view:

Controller: The last bit of code we need to write is the custom controller. The controller is the part that hooks everything together. In my example, I'm making a controller for a document-type I created within Umbraco called CustomModel, obviously, this is a bad naming convention for production! In the real world, I might have document-types called Homepage, Blog , orContent. The document-type alias needs to match the controller name. If a document type was called BlogPosts then the controller would be namedBlogPostsController`. Not using the right naming will result in the routing to fail, causing a 4040 error to be thrown!

Just a recap of the code, the name of the controllers needs to map to your Umbraco document types name. For basic pages, the controller will need to inherit from RenderMvcController. This is a special Umbraco controller type. Umbraco also ships with another controller (not covered here). All controllers will need a default Index action method to work as expected. In Index, you will then need to create a new instance of the view model. Remember we need to pass the IPublishedContent into the view model? This is done using the Content property! With the view model created, it is then passed into the view!. Also remember, the class name has to end with the word Controller. This is an ASP.NET MVC thing 😄🌈.

It's called route hijacking as you change the way the routing work by calling a custom controller. Umbraco does the hard routing part for you. All you need to do is inherit from the correct controller and the route-hijacking should work like magic. My example is very plain and simple, however, it can be extended fairly easily to give you a lot of power when it comes to architecting your web pages. Happy Coding 🤘