The Models builder is a tool that can generate a complete set of strongly-typed published content models for Umbraco. Models are available in both controllers and views.

• Introduction

• Configuration

• Builder Modes

• Understand and Extend Models

• Using Interfaces

• Tips and Tricks

The following configuration option can be set in the application settings (in the appsettings.json file):

• Umbraco.CMS.ModelsBuilder.ModelsMode determines how Models Builder generates models. Valid values are:

  • Nothing: Do not generate models.

  • InMemoryAuto(default): Generate models in a dynamic in-memory assembly.

  • SourceCodeManual: Generate models in ~/umbraco/models (but do not compile them) whenever the user clicks the "Generate models" button on the Models Builder dashboard in the Settings section.

  • SourceCodeAuto: Generate models in ~/umbraco/models (but do not compile them) anytime a content type changes.

• Umbraco.CMS.ModelsBuilder.ModelsNamespace (string, default is Umbraco.Cms.Web.Common.PublishedModels) specifies the generated models' namespace.

• Umbraco.CMS.ModelsBuilder.FlagOutOfDateModels (bool, default is true) indicates whether out-of-date models (i.e. after a content type or data type has been modified) should be flagged.

• Umbraco.CMS.ModelsBuilder.ModelsDirectory (string, default is ~/umbraco/models) indicates where to generate models and manage all files. Has to be a virtual directory (starting with ~/) below the website root (see also: AcceptUnsafeModelsDirectory below).

• Umbraco.CMS.ModelsBuilder.AcceptUnsafeModelsDirectory (bool, default is false) indicates that the directory indicated in ModelsDirectory is allowed to be outside the website root (e.g. ~/../../some/place). Due to this being a potential security risk, it is not allowed by default.

• Umbraco.CMS.ModelsBuilder.DebugLevel (int, default is zero) indicates the debug level. Set to greater than zero to enable detailed logging. For internal / development use.

Example Configuration

The example below shows an example configuration using the SourceCodeManual mode.

Models Builder Dashboard

Models Builder ships with a dashboard in the Settings section of Umbraco's backoffice. The dashboard does three things:

• Details on how Models Builder is configured

• Provides a way to generate models (in SourceCodeManual mode only)

• Reports the last error (if any) that would have prevented models from being properly generated

Models Builder is a tool that can generate a complete set of strongly-typed published content models for Umbraco. By default, a slimmed down version of Models Builder is embedded with the main Umbraco distribution.

Models can be used anywhere that content is retrieved from the content cache, i.e. in MVC views, controllers, etc. In other words, when using the Models Builder, the content cache does not return IPublishedContent objects anymore, but strongly typed models, implementing IPublishedContent.

For each content, media and member type in the Umbraco setup, the generator creates a *.generated.cs file, corresponding to the type. For instance, a document type with a textstring property named Title, and a rich text editor named BodyText will look like this:

Now since this is an automatically generated file, it's a bit messy, the important part is that it has all the properties defined and strongly typed:

And:

Umbraco's content cache returns these objects natively: No need to map, convert or anything; the following code runs:

Models Builder respects the content types' inheritance tree, i.e. models inherit from each other if required, and mixins (content type compositions) are represented by interfaces.

Models Builder is a "code-after*_" solution. It only generates code from content types that already exist in Umbraco. It is not a "code-first" solution - code-first is a much more complex question.

Installing

The Models Builder is by default embedded in Umbraco. If you need more complex features than what is provided, you still need to add the full package. However, as of right now the package is not updated to be able to handle NetCore or Umbraco V9.

Documentation

At the core of the strongly typed models "experience" is the IPublishedModelFactory interface. This interface is part of the Umbraco core codebase. It is responsible for mapping the internal IPublishedContent implementations returned by the content cache, to strongly typed models. There is a default factory shipped with Umbraco and it is possible to replace this by custom implementations. When using the default factory, models do not necessarily need to be generated by Models Builder.

Models Builder can be used in different modes:

• InMemory models

• SourceCode models

The mode is indicated by the Umbraco:CMS:ModelsBuilder:ModelsMode key in the configuration (appsettings.json files).

In memory

Corresponds to the InMemoryAuto setting value.

With InMemory models, models are generated and compiled on the fly, in memory, at runtime. They are available in views exclusively.

This is for a setup that exclusively uses the Umbraco backoffice, and do not use custom code such as controllers. Whenever a content type is modified, models are updated without restarting Umbraco (in the same way .cshtml views are recompiled).

Generation can fail for various reasons, in which case Umbraco will run without models (and front-end views fail to render). Umbraco's log file should contain all details about what prevented the generation, but it is probably faster to check the Models Builder dashboard, which should report the last error that was encountered, if any.

Models Builder maintains some files in ~/umbraco/Data/TEMP/InMemoryAuto:

• models.generated.cs contains the generated models code

• all.generated.cs contains the compiled code (models merged with non-generated files)

• models.hash contains a hash code of the content types

• all.dll.path contains the path to the compiled DLL file containing all the models

• Compiled/generated.cs{GUID}.dll the dll containing all the generated models

• models.err contains the last generation error information, if any

The models.hash file is used when Umbraco restarts, to figure out whether models have changed and need to be re-generated. Otherwise, the local models.generated.cs file is reused.

SourceCode Models

Corresponds to the SourceCodeManual and SourceCodeAuto setting values.

With SourceCode models, models are generated in the ~/umbraco/models directory, and that is all. It is then up to you to decide how to compile the models (e.g. by including them in a Visual Studio solution).

Generation can fail for various reasons, in which case no models are generated. Umbraco's log file should contain all details about what prevented the generation, but it is probably faster to check the Models Builder dashboard, which should report the last error that was encountered, if any.

The modelsbuilder works much in the same way whether using SourceCodeManual or SourceCodeAuto. The only real difference between the two are that with SourceCodeManual you must manually trigger the generation of the models from the models builder dashboard, whereas with SourceCodeAuto the models are automatically generated whenever content types change.

API models and Dll Models

These modes are not available in the embedded version of Models Builder. See the full version of ModelsBuilder.

It's possible with Razor to define functions for rendering HTML, we can leverage our strongly typed models when doing this, and even provide overloads for different types of models, that will automatically called for different models using dynamic

@functions
{
  // Declare how to render a news item
  void RenderContent(NewsItem item)
  {
    <div>News! @item.Title</div>
  }

  // Declare how to render a product
  void RenderContent(Product item)
  {
    <div>Product! @product.Name cheap at @product.Price</div>
  }
}

@{
  RenderContent((dynamic) Model);
}

Now, it's not recommended to create a single template and doing all the rendering via razor function, but it can be quite nifty for rendering search results, and so on.

A thing that's important to note here is that RenderContent is called from a codeblock, and not as @RenderContent((dynamic) Model); the reason for this is that if you try to use the latter, razor will expect for the function to return something for it to render.

By casting the strongly-typed to a dynamic when calling the RenderContent method, you tell C# to do late runtime binding and pick the proper RenderContent implementation depending on the actual CLR type of the content object. Using dynamic here is OK and will not pollute the rest of the code.

Models are generated as partial classes. In its most basic form, a model for content type TextPage ends up in a TextPage.generated.cs file and looks like:

/// <summary>TextPage</summary>
[PublishedModel("textPage")]
public partial class TextPage : PublishedContentModel
{
  // helpers
  public new const string ModelTypeAlias = "textPage";

  public new const PublishedItemType ModelItemType = PublishedItemType.Content;

  public new static IPublishedContentType GetModelContentType(IPublishedSnapshotAccessor publishedSnapshotAccessor)
    => PublishedModelUtility.GetModelContentType(publishedSnapshotAccessor, ModelItemType, ModelTypeAlias);

  public static IPublishedPropertyType GetModelPropertyType<TValue>(IPublishedSnapshotAccessor publishedSnapshotAccessor, Expression<Func<TextPage, TValue>> selector)
    => PublishedModelUtility.GetModelPropertyType(GetModelContentType(publishedSnapshotAccessor), selector);

  private IPublishedValueFallback _publishedValueFallback;

  // ctor
  public TextPage(IPublishedContent content, IPublishedValueFallback publishedValueFallback)
    : base(content, publishedValueFallback)
  {
    _publishedValueFallback = publishedValueFallback;
  }

  // properties

  ///<summary>
  /// Header
  ///</summary>
  [ImplementPropertyType("header")]
  public virtual string Header => this.Value<string>(_publishedValueFallback, "header");
}

What is important is the Header property. The rest is (a) a constructor and (b) some static helpers to get the PublishedContentType and the PublishedPropertyType objects:

var contentType = TextPage.GetModelContentType(); // is a PublishedContentType
var propertyType = TextPage.GetModelPropertyType(x => x.Header); // is a PublishedPropertyType

Composition and Inheritance

Content type composition consists in having content types "inherit" properties from other content types. Contrary to C#, where a class can only inherit from one other class, Umbraco content types can be composed of several other content types.

The TextPage content type could be composed of the MetaInfo content type (and thus inherit properties Author and Keywords) and of the PageInfo content type (and thus inherit properties Title and MainImage).

Each content type that is involved in a composition is generated both as a class and as an interface, and so the MetaInfo content type would be generated as (some code has been removed and altered for simplicity's sake):

// The composition interface
public partial interface IMetaInfo : IPublishedContent
{
  public string Author { get; }
  public IEnumerable<string> Keywords { get; }
}

// The composition class
public partial class MetaInfo : PublishedContentModel
{
  // the "static mixin getter" for the property
  public static string GetAuthor(IMetaInfo that)
  {
    return that.GetPropertyValue<string>("author");
  }

  public string Author { get { return MetaInfo.GetAuthor(this, _publishedValueFallback); } }
}

And the TextPage model would be generated as (some code has been removed and altered for simplicity's sake):

public partial class TextPage : PublishedContentModel, IMetaInfo
{
  // get the property value from the "static mixin getter"
  public string Author { get { return MetaInfo.GetAuthor(this, _publishedValueFallback); } }
}

A content type parent is a tree-related concept: In the Umbraco backoffice, a content type appears underneath its parent, if any. By convention, a content type is always composed of its parent and therefore inherits its properties. However, the parent content type is treated differently, and the child content type directly inherits (as in C# inheritance) from the parent class.

Therefore, assuming that the AboutPage content type is a direct child of TextPage, it would be generated as:

// Note: Inherits from TextPage
public partial class AboutPage : TextPage
{
  ...
}

Extending

Because a model is generated as a partial class, it is possible to extend it. That could be by adding a property, by dropping the following code in a TextPage.cs file:

public partial class TextPage
{
    public string WrappedHeader => $"[{Header}]";
}

Models builder does not take a custom partial class into account when generating the models. This means that if a custom partial class, inherits from a base class, tries to provide a constructor with the same signature, or implements a generated property, it will cause compilation errors.

Furthermore a generated model will always be instantiated with its default constructor, so if an overloading constructor is created it will never be used.

For more complex partial classes, you'll have to use the full version of the Models Builder.

Best Practices

Extending models should be used to add stateless, local features to models, and not to transform content models into view models or manage trees of content.

Example of good practice

A customer has "posts" that has two "release date" properties. One is a true date picker property and is used to specify an actual date and to order the posts. The other is a string that is used to specify dates such as "Summer 2015" or "Q1 2016". Alongside the title of the post, the customer wants to display the text date, if present, else the actual date. If none of those are present, the Umbraco update date should be used. Keep in mind that each view can contain code to deal with the situation, but it is much more efficient to extend the Post model:

    public partial class Post
    {
        public string DisplayDate
        {
            get
            {
                if(!TextDate.IsNullOrWhiteSpace())
                {
                    return TextDate;
                }

                if (ActualDate != default)
                {
                    return ActualDate.ToString();
                }

                return UpdateDate.ToString();
            }
        }
    }

And to simplify the view as:

<div class="title">
  <div class="title-text">@Model.Title</div>
  <div class="title-date">@Model.DisplayDate</div>
</div>

Example of bad practice

Because, by default, the content object is passed to views, one can be tempted to add view-related properties to the model. Some properties that do not belong to a content model would be:

• A HomePage property that would walk up the tree and return the "home page" content item

• A Menu property that would list the content items to display in a top menu

• Etc.

Generally speaking, anything that is tied to the current request, or that depends on more than the modeled content, is a bad idea. There are much cleaner solutions, such as using true view model classes that would be populated by a true controller and look like:

public class TextPageViewModel
{
  public TextPage Content; // The content model
  public HomePage HomePage; // The home page content model
  public IEnumerable<MenuItem> Menu; // The menu content models
}

One can also extend Umbraco's views to provide a special view helper that would give access to important elements of the website, so that views could contain code such as:

<a href="@MySite.HomePage.Url">@MySite.HomePage.Title</a>

Example of ugly practice

The scope and life-cycle of a model is not specified. In other words, you don't know whether the model exists only for you and for the context of the current request, or if it is cached by Umbraco and shared by all requests.

As a consequence, the following code has a major issue: the TextPage model "caches" an instance of the HomePageDocument model that will never be updated if the home page is re-published.

private HomePageDocument _homePage;
public HomePageDocument HomePage
{
    get
    {
        if (_homePage is null)
        {
            _homePage = this.AncestorOrSelf<HomePageDocument>(1);
        }
        return _homePage;
    }
}

As a rule of thumb, models should never, ever reference and cache other models.

When using compositions, Models Builder generates an interface for the composed model, which enables us to not have to switch back to using Value() for the composed properties.

A common use-case for this is if you have a separate composition for the "SEO properties" Page Title and Page Description.

You would usually use this composition on both your Home and Textpage document types. Since both Home and Textpage will implement the generated ISeoProperties interface, you will still be able to use the simpler models builder syntax (e.g. Model.PageTitle).

However, you won't be able to use the nice models builder syntax on any master template, since a master template needs to be bound to a generic IPublishedContent. So you'd have to resort to the ever-so-slightly clumsier Model.Value("pageTitle") syntax to render these properties. It is possible to solve this issue of master templating, by using partial views, to render the SEO specific properties.

Render with a partial

If you create a partial and change the first line to use the interface name for the model binding, you can use the nice Models Builder syntax when rendering the properties, like this:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ISeoProperties>
<title>@Model.PageTitle</title>
<meta name="description" content="@Model.PageDescription">

You can then render the partial from your Master Template with something like this (assuming the partial is named Metatags.cshtml):

<head>
    @Html.Partial("Metatags")
</head>
@RenderBody()

It's important to note though, that this master template will only work for content types that use the Seo Properties composition.