Planning your Episerver project

You’re going to start working on a brand new Episerver project! Your solution is a brand new slate where you can add your best code ever and you just received the design specs and requirements!


Now you need to sit down and get an idea how to build your solution. But where should you start?

In this blog post I’m trying to give some hints of how I use to plan building an Episerver website. Since the sales, concept and requirement phases can be very different from company to company (and sometimes even project to project) I will try to keep to a very fundamental level.

First of all I’m asking myself the following questions:

What do I want do to?

Get an idea of what the solution should solve and which functions that is needed.

The answer to this could be “a website” – but what should it contain? News articles where the user can list and filter based on categories and date? Product presentation where you can rate each product? Logged on functionality with profile presentation?

Sometimes the requirements from earlier phases in the project already have this but I’ve seen lots of requirements which are still on a concept level rather than a functional spec.

Try to summarize a map of functions from an abstract perspective and leave out the details for now.

My example throughout this post have

  • Customer profiles.
  • Product presentation.
  • Authenticate to edit their profile.
  • A customer can also rate news. In the future maybe even products so let’s keep that function isolated.


Using the SOLID principles, this could maybe become the start of your architectural design of functionality in the project as you want to separate the functions.

What areas are Content logic vs Business logic?

When I say Content Logic I refer to things you can do within your CMS’ API such as listing, filtering and reading content based on what is created by the editor while Business Logic would be connected to other data and functionality from systems or databases than your CMS.

Looking at the defined functions from the image above, I define what I can do in Episerver in terms of data structure, and what comes from other systems.

Example how to define: Your page displays a list of links but you don’t know where they are stored:

  • Should the editor just add links using the Link Item Collection, Content Area or the XHTML property in Episerver?
  • Should the list automatically be fetched from the content in Episerver (for example children to a specific page)?
  • Should the list be fetched from an external service such as Delicious, Pocket or similar?

The first options would be Content Logic while the second one is Business Logic.

Based on the functions in the image above and what I know so far I can start marking which sections are Content or Business.

business vs content.png

Also remember to start focus on the areas that are critical for the project, the other things can usually be decided later on (especially if you’re working agile).

From this I would start with the content logic to see how to structure these.

Content – because it’s a website!

What is the content structure?

When I have decided which areas comes from the CMS, I would try to define what parts I would need to create in Episerver based on the design specs and requirements.

Example how to define: The “normal page” and “news article page” are visually identical, except that the “news article page” also have images.

  • Should I create two separate page types?
  • Should I only create only one page type, but be able to add the image list as a block?
  • Should I only create one page type, as the normal page might also be able to have an image list?


How the editor would work with the content has a large role in my decisions as well as how it can be generalized and reused to minimize the headache for the developers in the future.

I try to make pages as generic as possible. To have many very similar content types will in the end become hard to maintain since they could have the same functionality.

Having a modular approach is quite nice for that, although it can get quite messy for the editor if there are hundreds of block types to choose from.

Another trick is to find a structure where you restrict enough for the editor, while still letting the editor be able to be creative and have freedom with their content. This is a very hard thing to find!

My suggestion is to have a simple data structure and look at how to simplify the editor experience using EditorDescriptors and maybe even Dojo. Sometimes you can even use the Edit mode to make a better Editor experience than the Properties mode.

So based on the “News” section in the image above I would structure the implementation like this.

content logic.png

Where the normal “Data Layer” in a three tier is the Episerver API. In the Content Logic I build functionality to filter and sort the content and the presentation is the usual Views and frontend resources.

Content – How should everything be rendered?

To start with, try to keep the rendering of your website as a normal “.net website” as much possible using Episerver as the data container.

I would recommend that you use the EPiServer:Property web control (WebForms) or PropertyFor HTML extension method (MVC) when rendering properties and content.
You’ll get tons of nice features with RenderSettings, Tags, Display Options, Display Channels and just to name a few.

When it comes to tweaking your rendering, the Alloy project has quite a lot of examples, however they are no documentation on why, how or exactly to use these and which code is related to which functionality. Don’t refer too much to Alloy templates as it would be overkill for a normal content website.

Business Logic – because I have lots of complex things to build!

Here is a nice part about building an Episerver website – basically it’s like building a normal .NET website where you’ll get a great API for your content (and an interface for your editors to work with that content).

For the other logic you can add tools like Entity Framework, IoC containers, external web services or other stuff you like to play with! Mostly I recommend using a 3 tier approach where you separate data from logic.

Once I have figured out the functionality that does not directly concern content, I look at how I can fit the presentation in Episerver.

There are three common approaches to present external data:

  • Import all data as content using a scheduled job or similar.
  • Create a content type for your data, but use keys in the context (QueryStrings or Routing) to identify which data item to display.
  • Use a Content Repository which is a built in tool in Episerver that handles content structure, routing, access rights and so on for programmatically.

Normally I would go for importing the data or using a Content Repository.

Based on the “Products” section in the image above, I would structure the implementation something like this.


Where I read and save from my own database or external sources in the Data Layer, creating business logic that handles the Data Layer in “Business Logic” and glue this together with Episerver in the Content Logic.

On top of that I would have the presentation layer as usual with Views and frontend resources.

There is one thing you should keep in mind though!

Don’t make your solution too dependent on external systems – have a fallback plan


When your website loose connection to an external service that provides information make sure that it does not go down.

For example store the information locally so that it can be used when the connection is lost, or display a sign that tells the visitor that all areas of the website are not working at the moment.

Unfortunately I don’t have a silver bullet solution on how to present your data, but as long as you don’t start throwing lots of 500 (specially not on the start page) and that reading the external data does not make the website slow.

Logic finished – now what?

Normally I work in agile projects (based on how we can work with the client), at least we split most of our project into iterations or sprints.


Most of the time, the customer wants to be up and running with the content work as soon as possible, so in the first iterations I try to plan the most common content types that they will work with.

Creating an MVP

In the example above I would have Henric Kniberg’s example of creating a MVP (minimum viable product) and start working with the basics that are less automated.

  • News
    The editor can create news articles but the listing would either be a very basic one or even be created manually by the editor.
    Automatic listing with filters would be created in a later sprint.
  • Products
    Say that I decided to go for the “import all products as pages” approach.
    I would prioritize building the product pages so that the editors can create some examples that they give feedback to.
    I would create the product import in a later sprint.
  • Profiles
    I will create the content types necessary, but after the first sprint the customers needs to contact support to change these.
    Authentication would come later, and then I can look at letting the customer update their profiles.

Ok I admit that this is a very simple priority! Pushing more complex sections such as product import and authentication to later sprints means there is a risk that they won’t make it to launch.

But this is a rough plan based on that the only priority for the customer is to start working with content.

However I want you to keep in mind that take small steps instead of building the entire project at the same time.


So! Thank you for following me through this article. These are some major thoughts I have on how to plan an Episerver project.

So a short recap

  • An Episerver website is simply a .NET solution where you get an API to fetch content (and an interface for the editor to work with the content).
  • Build your system integrations separately and integrate them using the Episerver API.
    • Make sure that your site does not crash because your integrations can’t integrate.
  • Start of simple and add the more complex parts later.

If you don’t agree of want to add to my list, please add a comment below.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: