Using Umbraco's Models Builder
Strongly typed models is something that was missing in a standard Umbraco installation. Members of the Umbraco community used Stéphane’s Models Builder, Umbraco liked this package so they decided to include it in the Umbraco core.
How do we enable it?The Models Builder is automatically included when installing Umbraco 7.4 but must be enabled in order to generate the models. The web.config contains two keys which enable you to use the Models Builder and set a mode which basically means in what way the models are generated.
Set the key ‘Umbraco.ModelsBuilder.Enable’ to true and the ‘Umbraco.ModelsBuilder.ModelsMode’ to a mode. The next chapter describes the modes you can choose from.
Which modes can we use?There are a few modes for the generation of the models:
- Dll / LiveDll
- AppData / LiveAppData
- API models
Mode: PureLivWhen the PureLive mode is used, the models are generated and compiled on the fly. This means the models can only be used in views and not in controllers and other server-side logic because the models will only be generated when the application is running. This also means you won’t be able to use IntelliSense in your views.
Mode: DllIn Dll mode the models are generated in ~/App_Data/Models and compiled to a DLL in the bin folder. This means the models can be used in views, controllers and other server-side logic. This also means IntelliSense is available!
Mode: AppDataIn this mode the models are generated in ~/App_Data/Models but not compiled. It is up to you what to do next. You can – for example - copy the generated files to App_Code or a logic project in your Visual Studio solution.
In API mode, the Models Builder will not generate models, instead an API will be generated which can be used to get the models. An additional NuGet package named ‘Umbraco.ModelsBuilder.Api’ is needed for this mode to work, which also needs to be enabled in the configuration.
Always run the website in debug mode, otherwise the API will not be provided. Set the debug attribute to true in the web.config.
This blog will not go into detail for this mode because the usage is different from the other modes. If you want to read more about using the Api mode, please check: https://github.com/zpqrtbnk/Zbu.ModelsBuilder/wiki/Builder-Modes.
Mode: LiveDll / LiveAppData
The modes Dll and AppData also have a ‘live’ mode, which means the models are automatically generated when the content or document type changes. In non-live modes this needs to be done manually from the Models Builder Dashboard in Umbraco.
The Models Builder Dashboard
The Models Builder Dashboard is found in the Developer section of Umbraco. The dashboard will show which mode is used, what the namespace is, etc. The main purpose of the dashboard is the ‘Generate models’ button to generate your models when you are not using a live-mode.
Figure 1: Models Builder Dashboard
What will change in my views?
Imagine the following properties in a DocumentType:
Figure 2: Properties in our DocumentType
Using Umbraco’s helper methods like GetPropertyValue, something like this is needed to show the values of the properties on our page:
When using dynamic objects, the view will look like this:
When using the Models Builder in e.g. Dll Mode, the view will look like:
The model ‘UmbHomePage’ is set at the top of the view. The properties of the DocumentType can be used in the view. Remember, views will not be compiled, so errors made in your view will still result in rendering issues when viewing your Umbraco-site. Using IntelliSense will result in less errors of course.
Why should I use strongly typed models?
Using dynamics or Umbraco’s helper methods can result in runtime errors, when strongly typed models are used the compiler will give errors when a property does not exist or when performing invalid casts. Using strongly typed models will result in compile-time errors in e.g. your server-side logic when you make an error.
ConclusionAt Suneco, we will use the Models Builder in Dll or AppData mode. The choice between Dll or AppData depends on the project. In small projects we will probably use Dll, in larger projects with separate logic libraries we will use the AppData mode.
Our projects contain a lot of business logic and we want our views to be as clean as possible. Of course, this is not related to Models Builder but it sure helps to keep your views clean. When the views are clean, a front-end developer can also work with the views. A front-end developer will understand @Model.AboutText better than Umbraco methods like GetPropertyValue<string>, which will make it possible in our projects to let backend and front-end developers work in the same environment.
For more information about Umbraco’s Models Builder see: https://github.com/zpqrtbnk/Zbu.ModelsBuilder/wiki/Umbraco.ModelsBuilder.
Onze technische blogs zijn in het Engels. Dit doen wij omdat wij menen dat technische kennis van Sitecore en Sitefinity grensoverschrijdend moet zijn. Wij leren veel van buitenlandse developers, wij delen onze kennis ook graag met hen. Mochten er in de code fouten zitten of punten ter verbetering, dan gaan we graag het gesprek aan.