Strongly typed models with Models Builder in Umbraco

What Models Builder does

Models Builder turns each document type into a C# class. Instead of @Model.Value<string>("title") you write @Model.Title, and your editor autocompletes every property. Typos become compile errors instead of blank pages.

The four modes

• InMemoryAuto (the default in development): models are generated in memory whenever you change a document type. Your views compile at runtime. Nothing to commit. Needs the Umbraco.Cms.DevelopmentMode.Backoffice package, which new projects include.
• SourceCodeAuto: models are written as .cs files to your project whenever a document type changes. You can use them in your own C# code too.
• SourceCodeManual: files are written only when you click Generate models. Best for teams and production builds.
• Nothing: Models Builder is switched off. Use this in production when the models are already compiled into your site.

Step 1: Pick a mode

For most real projects, use SourceCodeManual in development and Nothing in production:

{
  "Umbraco": {
    "CMS": {
      "ModelsBuilder": {
        "ModelsMode": "SourceCodeManual",
        "ModelsDirectory": "~/Models/Generated"
      }
    }
  }
}

{
  "Umbraco": {
    "CMS": {
      "ModelsBuilder": { "ModelsMode": "Nothing" },
      "Runtime": { "Mode": "Production" }
    }
  }
}

Step 2: Generate the models

Go to Settings › Models Builder and click Generate models. You'll get one partial class per document type, for example ContentPage.generated.cs, in the folder you chose. Commit these files.

Step 3: Use them in a template

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.ContentPage>
@using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;
<h1>@Model.Title</h1>
@Model.BodyText
@if (Model.HeroImage is { } image)
{
    <img src="@image.GetCropUrl(width: 1200)" alt="@image.Value("altText")">
}

Compositions become C# interfaces, so a partial view can accept any page that has your SEO fields, for example UmbracoViewPage<ISeo>.

Step 4: Compile views for production

With SourceCodeManual or Nothing, precompile your Razor views so production doesn't need the runtime compiler. In your .csproj, remove these lines from the project template, or set them to true:

<PropertyGroup>
  <RazorCompileOnBuild>true</RazorCompileOnBuild>
  <RazorCompileOnPublish>true</RazorCompileOnPublish>
</PropertyGroup>

Extending a model

Generated classes are partial, so you can add your own properties in a separate file that Models Builder never overwrites:

namespace Umbraco.Cms.Web.Common.PublishedModels;

public partial class ContentPage
{
    public string DisplayTitle => string.IsNullOrWhiteSpace(Title) ? Name : Title!;
}