How To Get Started With Umbraco ModelsBuilder

In this tutorial, you will learn why defining your Umbraco document types in the code will make your life a lot less stressful and then how to create an Umbraco document, using the built-in ModelsBuilder. 

Why Define My Document Types In Code?

One of the reasons why C# is such a popular language is because it's a compile-safe, strongly typed language.  As Umbraco is built on .NET to leverage as much power as possible from it, you want to define as much as possible in code.

A lot of people reading this might find the idea of creating your document types in code strange, however, trust me when I say this after you have 3-5 websites under your belt that have been built in a ground-up manner, you'll wonder how you ever lived without it. 

Using code to define your CMS pages and components is not a new concept.  Episerver has allowed this type of functionality for over 5 years.  Umbraco packages like uSitebuilder have provided this type of functionality within Umbraco since 2011 and now in 2018, Umbraco provides this functionality out of the box so you should be using it!

Defining your document types in C# code will make your life easier.  When your document types are represented as classes, firstly, you can use the Visual Studio compiler to flag any stupid typo you make.  Second, it makes future maintenance easier, as tools like Resharper can be used to refactor your code base and finally and most importantly, you can properly unit test your work.  Sounds good right, so let's crack on.

How To Enable Model Building?

To enable the model building within your web.config you will need to enable it.  Within your app settings section, find the entry called 'Umbraco.ModelsBuilder.ModelsMode' and make sure it is set to either PureLive, Dll, LiveDll, AppData or LiveAppData and make sure that 'Umbraco.ModelsBuilder.Enable' is set to true, like so:

<add key="Umbraco.ModelsBuilder.ModelsMode" value="PureLive" />
<add key="Umbraco.ModelsBuilder.Enable" value="true" />

To get a little more context about the different modes, I suggest you check out this Github repo.

After Model Building has been enabled, when you log into your Umbraco backend and go to the developer section, you should see a ModelsBuilder tab with extra information, like so:

What Mode Should I Use?

It all depends on your preference of which mode to use.  If you use Live Mode, models are generated in memory on application start and will dynamically change when a content editor creates/edits a model within Umbraco. You won't be able to use Intellisense in LiveMode.

On my projects, I tend to favor DLL mode.  In DLL mode, models are generated and compiled into an assembly called 'Umbraco.Web.PublishedContentModels.dll'  To generate the assembly you don't need to compile your solution with Visual Studio, instead you simply go to the Model Builder tab mentioned above and press the “Generate Models” button. One important thing to be aware of, when you click the generate models button, your website will reset, so you might not want to re-generate models in peak hours!

As your models are stored within an assembly, if you simply reference your model within your Visual Studio solution, you will get full c. After you have Intellisense, you can now make full use of C# strong-types languages, you can start to unit test your views and generally, your life will be super awesome!




submit to reddit

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

Back to top