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

Templating in Umbraco consists of 3 larger concepts, namely Templates (Views) and Partials (Partial Views).

• Templates are used for the HTML layout of your pages.

• Partials can be included in your templates for shared functionality across different page templates.

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).

Example

Working with MVC Views and Razor syntax in Umbraco

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.

Lots of examples of using various techniques to render data in a view

Rendering the raw value of a field from IPublishedContent

Rendering the converted value of a field from IPublishedContent

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 be 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);
}

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

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. You also tell it to pick the proper RenderContent implementation depending on the actual Common Language Runtime (CLR) type of the content object. Using dynamic here is OK and will not pollute the rest of the code.

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:

public virtual global::Umbraco.Cms.Core.Strings.IHtmlEncodedString BodyText => this.Value<global::Umbraco.Cms.Core.Strings.IHtmlEncodedString>(_publishedValueFallback, "bodyText");

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.

And once you are using strongly typed models, there are some that you can do.

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.

Check for more details.

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 is one way to generate models for the default, built-in factory. Models can be generated automatically or straight from the Settings section of the Umbraco backoffice, for more info see .

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 (for example 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

Creating an HTML form to submit data with MVC in Umbraco is possible in a few steps.

If you want to create a Form:

1. Using view models, views, controllers, and a handy HtmlHelper extension method called BeginUmbracoForm, see the article.

2. Using Umbraco Forms, see the article.

Working with MVC Views and Razor syntax in Umbraco

Properties available in Views

All Umbraco views inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.NameOfYourDocType> along with the using statement @using ContentModels = Umbraco.Cms.Web.Common.PublishedModels;. This exposes many properties that are available in razor. The properties on the Document Type can be accessed in a number of ways:

• @Model (of type Umbraco.Web.Mvc.ContentModel) -> the model for the view which contains the standard list of IPublishedContent properties but also gives you access to the typed current page (of type whatever type you have added in the angled brackets).

• @Umbraco (of type UmbracoHelper) -> contains many helpful methods, from rendering fields to retrieving content based on an Id and tons of other helpful methods.

• @Html (of type HtmlHelper) -> the same HtmlHelper you know and love from Microsoft but we've added a bunch of handy extension methods like @Html.BeginUmbracoForm

• @UmbracoContext (of type Umbraco.Cms.Web.Common.UmbracoContext)

Rendering a field in a strongly typed view

This is probably the most used method which renders the contents of a field using the alias of the content item.

If you're using the method from within a partial view then be aware that you will need to inherit the context so the method knows which type to get the desired value from. You'd do this at the top of partial view and so strongly typed properties can then be accessed in the partial view. For instance you can pass "HomePage" like this:

You will also need to pass the "Context" to the @Model.Value() method if you're looping over a selection like this where we pass the "item" variable.

Looping over a selection works in a similar way. If you have a property that contains, for instance, an IEnumberable collection, you can access the individual items using a foreach loop. Below illustrates how you might do that using "item" as a variable.

If you want to convert a type and it's possible, you can do that by typing a variable and assigning the value from your property to it. This could look like the example below.

In this example, we are looping through a list of items with the custom made type TeamMember assigned. This means we are able to access the strongly typed properties on the TeamMember item.

Accessing Member data

IMemberManager is the gateway to everything related to members when templating your site.

Models Builder

Models Builder allows you to use strongly typed models in your views. Properties created on your document types can be accessed with this syntax:

When Models Builder resolve your properties it will also try to use value converters to convert the values of your data into more convenient models. This allows you to access nested objects as strong types instead of having to rely on dynamics and risking having a lot of potential errors when working with these.

Umbraco’s Models Builder automatically generates strongly typed models for content types, allowing developers to work with Umbraco data in a structured and efficient manner. This article explains how models are generated, how composition and inheritance work, and best practices for extending models without causing issues.

Models Generation Process

Models Builder generates each content type as a partial class. For example, a content type named TextPage results in a TextPage.generated.cs file with a structure like this:

In the above code:

• The model includes a constructor and static helpers to fetch the content type (PublishedContentType) and property type (PublishedPropertyType).

• The most important part is the property definition (Header), which retrieves values from Umbraco.

You can use helper methods to access content and property types:

Composition and Inheritance

Composition

Umbraco content types can be composed of multiple other content types. Unlike traditional C# inheritance, Umbraco allows a content type to inherit properties from multiple sources.

For example, a TextPage might be composed of:

• MetaInfo content type (inherits Author and Keywords properties).

• PageInfo content type (inherits Title and MainImage properties).

Each content type in a composition is generated both as a class and as an interface. The MetaInfo content type would be generated as:

And the TextPage model would be generated as:

Inheritance

In addition to composition, earlier versions of Umbraco allowed content types to have a parent-child relationship. In the Umbraco backoffice, a content type appears underneath its parent.

This type of inheritance is treated differently since the content type is always composed of its parent. The child content type inherits directly (as in C# inheritance) from the parent class.

If AboutPage is a child of TextPage, its generated model would inherit directly from TextPage:

Extending Models

Since models are partial classes, developers can extend them by adding additional properties.

For Example:

Models Builder does not recognize custom partial classes during regeneration. If your custom class conflicts with the generated class (e.g., overriding a constructor), it will cause compilation errors.

Overloaded constructors will not be used because models are always instantiated using the default constructor.

For more complex customizations, use the full version of .

Custom Model Generation with IModelsGenerator

From Umbraco 11.4, you can implement the IModelsGenerator interface to customize how models are generated. This allows you to replace Umbraco’s default implementation using dependency injection:

The interface can be accessed via Infrastructure.ModelsBuilder.Building.ModelsGenerator.

Best Practices for Extending Models

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

Good practices

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:

Simplified view:

Bad practices

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 retrieves the "home page" content item.

• A Menu property that lists navigation items.

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:

One can also extend Umbraco's views to provide a special view helper that gives access to important elements of the website:

Ugly practices

The model's scope and lifecycle are unspecified. It may exist only for your request or be cached and shared across all requests.

The code has a major issue: the TextPage model caches a HomePageDocument model that will not update when the home page is re-published.

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

This section will describe how you can render content from other nodes besides the current page in your MVC Views

Querying for content and media by id

The easiest way to get some content by Id is to use the following syntax (where 1234 is the content id you'd like to query for):

You can also query for multiple content items using multiple ids:

This syntax will support an unlimited number of Ids passed to the method.

You can also retrieve content using the Guid Id. In the example "ca4249ed-2b23-4337-b522-63cabe5587d1" is the key of the content.

You can also pass a to retrieve the content.

The same query structures apply to media:

Traversing

All of these extension methods are available on Umbraco.Core.Models.IPublishedContent so you can have strongly typed access to all of them with intellisense for both content and media. The following methods return IEnumerable<IPublishedContent>

Additionally there are other methods that will return a single IPublishedContent

Complex querying (Where)

With the IPublishedContent model we support strongly typed LINQ queries out of the box so you will have intellisense for that.

Some examples

Where children are visible

Traverse for sitemap

Content sub menu

Complex query

With the strongly typed IPublishedContent you can do complex queries.

In the previous versions of MVC, we used Child Actions to build reusable components/widgets consisting of both Razor markup and backend logic. The backend logic was implemented as a controller action and marked with a [ChildActionOnly] attribute. Child Actions are no longer supported in ASP.NET Core MVC. Instead, we will use the View Component feature.

View Component Overview

View components replace the traditional Controller (SurfaceController)/Partial View relationship and instead offers a modular approach of separating your views in to several smaller units. View Components are self-contained objects that consistently render HTML from a Razor view.

View components are:

This section will show you how to use MVC Partial Views in Umbraco.

Partial views allow you to reuse components between your views (templates).

View Locations

The locations to store Partial Views when rendering in the Umbraco pipeline is:

The standard MVC partial view locations will also work:

The ~/Views/Render location is valid because the controller that performs the rendering in the Umbraco codebase is the: Umbraco.Cms.Web.Common.Controllers.RenderController

If however you are and specifying your own controller to do the execution, then your partial view location can also be:

Example

A quick example of a content item that has a template that renders out a partial view template for each of its child documents:

The MVC template markup for the document:

The partial view (located at: ~/Views/Partials/ChildItem.cshtml)

Strongly typed Partial Views

Normally you would create a partial view by using the @model MyModel syntax. However, inside of Umbraco you will probably want to have access to the handy properties available on your normal Umbraco views like the Umbraco helper: @Umbraco and the Umbraco context: @UmbracoContext. The good news is that this is possible. Instead of using the @model MyModel syntax, you need to inherit from the correct view class, so do this instead:

By inheriting from this view, you'll have instant access to those handy properties and have your view created with a strongly typed custom model.

Another case you might have is that you want your Partial View to be strongly typed with the same model type (IPublishedContent) as a normal template if you are passing around instances of IPublishedContent. To do this, have your partial view inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage (like your normal templates). When you render your partial, a neat trick is that you can pass it an instance of IPublishedContent. For example:

Caching

You don't normally need to cache the output of Partial views, like you don't normally need to cache the output of User Controls. However, there are times when this is necessary and so we provide caching output of partial views. This is done by using an HtmlHelper extension method:

The above will cache the output of your partial view for one hour when not running Umbraco in debug mode. Additionally, there are a few optional parameters you can specify to this method. Here is the full method signature:

So you can specify to cache by member and/or by page and also specify additional view data to your partial view. * However*, if your view data is dynamic (meaning it could change per page request) the cached output will still be returned. This same principle applies if the model you are passing in is dynamic. Please be aware of this: if you have a different model or viewData for any page request, the result will be the cached result of the first execution. If this is not desired you can generate your own cache key to differentiate cache instances using the contextualKeyBuilder parameter

To create multiple versions based on one or more viewData parameters you can do something like this:

Or using a custom helper function:

Or even based on a property on the Model (though if Model is the current page then cacheByPage should be used instead):

Regardless of the complexity here the contextualKeyBuilder function needs to return a single string value.

Caching is only enabled when your application has debug="false". When debug="true" caching is disabled. Also, the cache of all CachedPartials is emptied on Umbraco publish events.