In this tutorial, you will learn the differences between normal vanilla MVC page requests and Episerver page requests. I have heard untold conversations between developers blaming Episerver for doing something strange. After a little delving, in most cases, the strange thing makes perfect sense when you understand the framework. In this tutorial, you will learn the difference between the two in order to become an Episerver ninja 🐱‍👤. If you want to master this great CMS, read on 🔥🔥🔥

Before we get started, I recommend that you learn how MVC works before you start building a site using Episerver CMS. WIthout this knowledge, you are making life harder for yourself than it needs to be. If you want a recommendation for a good MVC book, I would recommend reading, Professional ASP.NET MVC 5 as it's a great introductory to MVC.

An MVC Page Request

An Episerver websites is built on top of the ASP.NET framework. This means fundamentally Episerver runs the same as any other .NET MVC website. Underneath everything, the CLR still processes your code. IIS is still processing requests the same way. A browser will read and render your sites HTML, CSS, and Javascript the same way.

What Episerver provides is a framework that sits within this mesh of technologies. Technically, things start to get interesting when we look at the Global.asax file in an Episerver CMS. If you have a peek inside, you should see that your website is inheriting from Episerver.Global. Your Global.asax file will look like this:

This is the first sign that your Episerver site works slightly differently compared to a normal vanilla MVC site. Within Episerver.Global a lot of code exists that when bootstrapped will define the rules required to run the CMS. One of the biggest differences within these scripts is the default routing rule. In Episerver, it changes this rule and uses a custom one.

In a normal MVC site, a user types in a URL. If the segments within the Url matches a controller and action then execution will be passed to that controller. Any business logic will be run and eventually a view that contains all the HTML will be rendered. When you work within the CMS, all your pages live within a database. The Url structure of your website does not directly map to a controller or an action. This is why the default routing rule in an Episerver CMS powered website is very different. As a piece of software, Episerver needs to bridge the gap between how MVC works and how to render the virtual pages that get created in the database.

In order to achieve this, Episerver hooks into the global.ascx file and adds in their own stuff. This 'stuff' will involve things like defining a custom routing handler that will grab the URL request and then make a look-up in the database to see if any virtual pages might match the request. If a virtual page exists, then Episerver needs to instantiate that page and return it back to the user.

This overview is quite simplistic as under the hood Episerver does a lot of other things, however, conceptually this is one of the main concepts you need to grasp when you work with a CMS. We need a different way to do the routing because the web pages live in a database, however, we still need the flexibility to build our websites like we would any normal MVC website. We still need a way to add our own business rules and logic, we still need to be able to decide what view and layout.

Within a CMS, we still need a way to hijack into a page request and ensure a controller is called. We can not create controllers based on the URL, so we need to use a different approach. In a CMS, we create controllers based on the page type. When a match in the CMS is made, Episerver will try to load a controller based on the page type. It will then pass the page data into that controller.

In order to create an Episerver page type controller, we move away from the standard MVC Controller and instead use PageController<T>()

The Episerver Page Controller

When you look at a controller in any Episerver website, you will see it inherits from PageController<T>(). Where T is the page type you want to hijack. On a normal page request the Episerver routing intercepts the request, gets all the data that the content editors have added and then returns this data within the CurrentPage object:

In the snippet above, we have a standard MVC controller that will process any incoming requests for any page in the Episerver database that has been created as a ContentPage.  This is defined by the PageController bit. The ContentPage is a custom class that we have defined in code. A basic implementation of the content page could look like this:

In this example, the ContentPage controllers Index() method will get triggered when someone requests a page created using the Content page type. MVC will look for a controller that is set to deal with the ContentPage type. If it finds one, it triggers that controller. The currentPage parameter in the Index() method will be populated automatically with CMS data. The handler will auto type the object from the default PageData type to the type defined as T

The Index() method will be called by default. Episerver will populate the currentPage parameter in Index()method. From this point, the process works exactly the same as any other MVC site. in Index() you call your business layer, create a view model and call a view. You can now build any page you need. Happy Coding 🤘