When Models Builder is enabled and users in UAT and Production environments have access to it, they are able to generate the models at any time, there is a high risk of breaking the website if properties in document types are updated. To prevent this from happening I decided to explain how to use and integrate the Umbraco.ModelsBuilder.API More about Builder modes can be found here.
Using API models will allow to generate the models in a dev environment only, and then compiled to a dll. It is a good practice to generate models outside the Umbraco project in a separate Class Library.
The following steps show how to use the API models in a vanilla Umbraco 8 installation.
Alternatively, run the following command in the Package manager console:
PM> Install-Package Umbraco.ModelsBuilder.Api<add key="Umbraco.ModelsBuilder.EnableApi" value="true" />
<add key="Umbraco.ModelsBuilder.Enable" value="true" />
<add key="Umbraco.ModelsBuilder.ModelsMode" value="Nothing" />In Visual Studio -> Tools -> Extensions and features -> Online and install ModelsBuilder Custom Tool
In Visual Studio -> Tools -> Options -> Umbraco type the back office login details
Create a new class library project where the Umbraco models are going to be generated. For this example the Class library name is called Umbraco.Web.PublishedModels.ContentModels
In the new class library create an empty class called builder.cs, then in its properties, reference the Custom Tool as UmbracoModelsBuilder.
Right click on the builder.cs class and choose Run Custom Tool. This will generate the models of the Umbraco application.
Models will show as children on the builder class
Last step is to add the class library to the project dependencies. In this way the compiled models can be accessible in the Umbraco application. This will copy the dll to the Umbraco’s bin directory Umbraco.Web.PublishedModels.ContentModels.dll
When we login to the Backoffice in dev environment. Go to Settings -> Models Builder. We notice models cannot be generated in this page but the API is enabled. Therefore we are able to generate the models in the class library.
On the contrary, in UAT and production environments the API is disabled and models cannot be generated.
Now, we have reduced the risk of breaking the website when users update document type properties.
Class library source code can be downloaded re-used in other Umbraco 8 projects. Make sure the Custom Tool is installed and configured in Visual studio.
Generated models have been left in source code for reference only. Delete the models and generate the ones for your project.