In this tutorial, you will learn why defining your Umbraco document types in code will make your life a lot less stressful. After we have covered some software theory I will show you how you can generate a Umbraco document type in code, using the built-in ModelsBuilder. 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, in order to leverage as much power as possible from the language, you will want to work with your Umbraco document types using C# models.
A lot of people reading this might find the idea of creating your document types in code strange, however, after you get used to working this way, 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. The Umbraco community have been building packages like uSitebuilder to try and allow this type of functionality within Umbraco since 2011. Now in 2018, Umbraco finally provides this type of 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 accidental typos that you may make. Second, it makes future maintenance easier, as tools like Resharper can be used to refactor your codebase 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, you will need to enable it within your web.config. Within your appsettings section, find the entry called Umbraco.ModelsBuilder.ModelsModeand make sure it is set to either PureLive, Dll, LiveDll, AppData or LiveAppData and make sure that the setting called Umbraco.ModelsBuilder.Enable is set to true, like so:
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 you navigate to the developer section, you should see a ModelsBuilder tab with extra information that looks like this:
What ModelsBuilder 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, or, edits a model within Umbraco. You won't be able to use Intellisense in LiveMode.
On my projects, I tend to favour DLL mode. In DLL mode, models are generated and compiled into an assembly called Umbraco.Web.PublishedContentModels.dll. To update the classes contained in 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 your production site in peak trading hours!
As your models are stored within an assembly, if you simply reference your model within your Visual Studio solution, you will get full access to all the contained classes. You will also have Intellisense. With intellisense, you can now make full use of C#, you can start to unit test your controllers easily and in general, your life will be super awesome! The aim of this post is to give you an introduction to models builder. If you want a more in-depth deep dive into this subject then check out the other posts in this series below. Happy Coding 🤘
