In this tutorial, you will learn some handy tips on how to structure your Episerver powered CMS projects. I strongly recommend that at the beginning of every project you sit down and make a conscious decision on how you will structure your class libraries, folders and files. If you use the Alloy sample site as your websites base project, all the code is provided to you in the web solution. For smaller brochureware websites that will never grow too large, there is nothing really wrong with this approach. For large projects, there are a few downsides of simply adding all the code into the main website project 😔
My first tip is to resist the temptation to simply add all of your custom code files within the main web project. My justification for this tip is that you will not get a lot of re-use out of your code. If you build a lot of Episerver powered websites, being able to re-use your helper and utility methods within these different projects can be a massive time-saver. If you add all your code within the main web project, you will not get this benefit. This means that on the next project you will waste more time doing those boring set-up chores. Separating your code into one or more separate class libraries means it is easier to drop your libraries into future projects.
The second pain point that you will encounter with a single web project pattern, will be around your unit tests. It is standard development practice to create one unit test project per class library. I have found that when you mangle all your code into a single file project, you also need to mangle all your unit tests into a single library. When you mangle tests together, it is impossible to simply copy code and the unit tests into another project easily. It usually takes longer to unpick the tests compared to starting from scratch. So if we are not going to stick everything into the web project, what are we going to do?
In my projects, I tend to create a class library called
Project.Core. In this library, I add all my custom code, except any .NET framework start-up code. The reason why I leave things like
route.config within the main website project are future upgrades. For example, in the future, if you wanted to upgrade from .NET Framework to .NET Core, having all the MVC related files separated from your custom code will make life easier. I have proved this pattern is useful whenever I have needed to do a Sitecore upgrade 😔 . You can simply move the class library and its corresponding unit test library without having to waste time picking out code. My general advice is to put all your domain and model logic within this
The next question is what folders should you create within this
Core library? The types of folders that I would expect to see in this library would include
These folders will cover the majority of your custom code needs. You will need to decide where you want to put any initialization modules, structure map dependencies, and your custom route definitions. Should they live in the web project or your
Core library? I have used both approaches during my career, both work OK. I have never needed to copy any of these project-specific things in between projects, so do what makes you happy. If you are on the fence, leave them in the web project as this way slightly reduces the chances of you bumping into unit test project copying pains 😊
The Domain/Model/Shared Interface Approach
Having a single class library is great, however, for more complex sites you may want a more fine-grained abstraction. In complex projects, I tend to structure my code into three main class libraries,
Interfaces. First, we have the
Models project. In this project, I store things like,
View Models etc... In the domain library, I add the non-project specific code like,
Global project is where I add the non-project specific code, e.g. the bits I will copy in between different projects. Lastly, we have a third class library, the
Interface library. This library is needed to enforce a good separation of concerns within the project. Any
Interface used in the project is added here. The interface project is the contract on how the libraries can talk to each other. This approach might sound odd at first, however, it has some useful benefits. First, on most projects, I work with junior developers who are new to dependency injection. Having a rule that forces people to add interfaces in a class library, ensures they need to use dependency injection correctly within the solution 😊
I find that having a separate
Interfaces library makes code reviews much easier. I have a single rule to check and feedback on. Next, having a contract specific library can help eliminate any project circular reference issues. If you bump into some strange cyclic dependency issue later down the tracks, this will avoid you needing to refactor lots of code. Trust me, I've been there and got the T-Shirt 😔
In case you've never come across the cyclic dependency problem, let me explain. This issue occurs when one project relies on code found in another project in order to build, however, that project has a reference to the first project. When Visual Studio compiles, the compiler would get in an infinite loop. By moving all
interfaces into a shared library it breaks the cyclic chain 🔥🔥🔥
A valid objection to this pattern is complexity. Some developers believe that splitting up your project into additional libraries only creates extra overhead. My counter-arguments are time and effort. If you have more than one website being able to copy code quickly saves time. If you convert your
Global library into an internal Nuget package, you can also fix code once and get the benefits in all your projects. This can save you a lot of time in your future projects, as you don't have to copy and re-fix the same bugs over and over. The second benefit of having three libraries is that it forces the developer to write more flexible code. Using an
Interface project makes the code more flexible. It means you can use SOLID principles anywhere in your codebase. You are writing all your code so you can use the Open/Closed principle later if you need to. In this approach
Global only references the packages it needs.
Some food for thought if you want to use this approach, sometimes you may have to slightly compromise a bit on where you want to put code. You may end up with a file that you ideally would like to put in
Global, however, you get forced into adding it within
Models instead (due to references). One example are custom Episerver selection factories. You might want to make these global, however, they end up being project scoped as they usually need to reference a page or block type.
My personal preference for larger projects is to use this latter approach. I have used the
Core library pattern a lot over the years, successfully. If you have more than one website to build, the
Interface approach will result in more flexibility, as code can be more easily shared between projects and fewer unit tests need to be refactored to allow for this. The downside is that you may have to compromise on the placement of a few files.
What are your thoughts on this? How do you structure your project and which way do you prefer to implement the structure of your project? Happy Coding 🤘