In this tutorial, you will learn how to use models builder within Umbraco v9. If you are new to Umbraco and have not come across models builder, you are in for a treat. Adding models generated by the models' builder into your development workflow will make it a lot easier for you to build a Umbraco website. If you want to learn to be a complete models builder BOSS, this is the tutorial for you🔥🔥🔥

What Is Models Builder?

Originally developed as a community package by Dave Woestenborghs. Models builder will allow you to work with C# objects based on the document types that content editors create inside of the CMS.

Known as model-based development, models builder will allow you to more quickly create websites within Umbraco. When enabled, the Umbraco models builder will automatically create C# classes (or in-memory objects) whenever a document type is either created or edited within the CMS. Note that I specifically mentioned models/objects and C# classes, you will have to read on to learn why 😉

Mobel Buliding Mode

Models builder was first included within the core Umbraco product in v7. When first released, Models builder came with five different model generation modes, PureLive, Dll, LiveDll, AppData and LiveAppData. As v9 is built-in ASP.NET 5 whereApp_Data is no more, this mode is now obsolete. In fact, within v9 the generation modes have had a complete revamp! Just be aware that if you are performing an upgrade to v9, the name of the modes has changed slightly which will cause you an upgrade issue 🤔

In v9, the modes have been simplified down to 3 options, InMemoryAuto, SourceCodeAuto and SourceCodeManual:

InMemoryAuto: InMemoryAuto is the default mode of operation for the models' builder. As the name implies, the InMemoryAuto mode generates the models virtually within memory. Whenever a content editor makes a change to a document type within the CMS, models are generated and compiled on the fly

The benefit of using InMemoryAuto mode is that the models can be accessed directly within a view without having to recompile or rebuild the website. The downside of InMemoryAuto mode is that you can not access these models within classes or Visual Studio during normal development.

In general, I do not recommend teams use the InMemoryAuto mode. If you want to use Visual Studio to create and manage the website code you will need to use one of the other modes. If you want to build a website completely inside of Umbraco using the Umbraco template editor, using InMemoryAuto is your only option to access models generated by the model builder within your view. For me, determining where you are planning on doing your development will determine the mode you need to use.

SourceCodeAuto and SourceCodeManual: SourceCodeAutoandSourceCodeManualwork very similarly. In both modes, C# classes are generated that can be used within Visual Studio. In both modes, after the models are generated, a developer will need to compile the solution before the updated models become available for use in code. The plug-in can be configured, however, by default, both modes will generate the models within~/Umbraco/models`.

The big difference between SourceCodeManual and SourceCodeAuto is when the models are generated:

  • SourceCodeAuto: C# classes are automatically generated whenever a content editor makes a change within the CMS.

  • SourceCodeManual: C# classes are only generated when a content editor clicks on the generate models button within the CMS. To access this button within the backend, navigate to the Settings section. You should see a tab labelled ModelsBuilder:

Generating Models Builder models

' What Umbraco Model Builder mode should I use?

My personal preference is to use model builder inSourceCodeManual mode. From my experience, the most efficient way to manage a Umbraco project is to agree for the development team to make all document type changes. Anytime a document type is need to be either created or updated, the change is always made on a local machine and then thoroughly tested before being released into production.

The need for updating, or creating a document type is always part of a larger set of changes. That larger change could involve updating controllers, view models, views, and hopefully unit tests. Using SourceCodeManual mode can help give teams more security because the development team will be responsible for implementing content modelling changes.

Using SourceCodeManual mode also means that whenever you need to compile the project you do not suddenly encounter unexpected surprises. For example, if you and the team use a shared database for local development, it can be very annoying when someone updates the CMS and your code suddenly breaks for no reason! Surprises and best left for your birthday!

Using Model Builder in SourceCodeManual mode is my personal preference, however, like all these subjective configurations, pick the approach that makes you happy.

Setting the model builder mode is done within appsettings.json. After installing Umbraco you should see this section with appsettings.json:

Umbraco âž¡ CMS âž¡ ModelsBuilder

The generation mode is configured within a property called ModelsMode. Asides from the ModelsMode, models builder can be further configured and tweaked using these properties:

ModelsNamespace: This property defines the namespace that will be used when the models are generated. ModelsNamespace is a non-mandatory property. Leaving it blank will mean the namespace will default to Umbraco.Cms.Web.Common.PublishedModels.

FlagOutOfDateModels: The FlagOutOfDateModels property is used to configure if the CMS should flag when the models become out-of-date and consequently need refreshing. This property is also not mandatory and will default to true if not explicitly set. I can not really think of a great use case to disable this feature, so I recommend ignoring it!

ModelsDirectory: This property defines the directory the models will be generated inside of. When setting this property, the important thing to remember is that the path needs to map to a virtual folder rather than a physical folder. In practical terms, this means that you will need to prefix any value you define with ~/

AcceptUnsafeModelsDirectory: When the model builder has been set to generate models using one of the source code modes, by default, it will generate all the models inside the current website directory, inside this folder:

~/Umbraco/models

Using the ModelsDirectory property, you can change this location. If you tried to change the location to a folder that lives outside the webroot, you will encounter an error. This is where the AcceptUnsafeModelsDirectory mode comes into play. When enabled, the builder will allow you to generate the classes anywhere within the solution folder.

Enabling this mode will allow the classes to be generated in the solution root, an additional class library, or anywhere that takes your fancy. As enabling this mode is considered a risk, it is disabled by default.

This covers the main ways of configuring the Umbraco model builder. I give you my blessing to call yourself a code generation wizard 🧙 As you have probably guessed, I'm a big fan of this plug-in. If you are building a project using Umbraco, I recommend that you use Visual Studio and you use model builder as the mechinism of how you interact with the CMS data. It will make your life easier. Happy Coding 🤘