UsingTheModelsBuilder

The models builder can be used in different modes:

• Live models
• AppCode models
• AppData models
• Visual Studio

Live models

Requires that the Site Integration package is installed, either via NuGet or as an Umbraco package, and that Live models are enabled (see configuration, below).

With Live models, models are generated and compiled on the fly, in memory, at runtime. You cannot see the code of the models, and they are available in views exclusively. This is for people who exclusively use the Umbraco back-end, and probably do not write controllers anyway. Whenever a content type is modified, models are re-generated without restarting Umbraco (in the same way .cshtml views are recompiled).

AppCode models

Requires that the Site Integration package is installed, either via NuGet or as an Umbraco package, and that App_Code models are enabled (see configuration, below).

With App_Code models, models must be explicitely generated via the Zbu.ModelsBuilder dashboard in the developer back-end section. When models generation is triggered, model files are created in the ~/App_Data/Models folder. Then, a ~/App_Code/build.models file is created or touched, in order to cause Umbraco to compile the model files. Each time models are generated, Umbraco restarts. Whenever a content type is modified, models must be manually generated. If there are some filename.cs files in ~/App_Data/Models, the models builder will parse them for instructions (see ??? below).

AppData models

Requires that the Site Integration package is installed, either via NuGet or as an Umbraco package, and that App_Data models are enabled (see configuration, below).

With App_Data models, everything works as with App_Code models, but the ~/App_Code/build.models file is never generated. This means that models are never compiled. You need to explicitely copy those files to App_Code, or to your Visual Studio solution, for them to get compiled. This is the way to "just generate models".

Visual Studio

Requires that the Site Integration package is installed, either via NuGet or as an Umbraco package, and that the API is enabled (see configuration, below). Requires that the Visual Studio Extension is installed.

Then you need to:

• Go to Tools | Options | Zbu | ModelsBuilder Options and configure the url to your website (eg http://www.example.com), and a logon and password for an Umbraco user that has permission to access the developer section.
• Create a folder in your solution -- pick your own name. Within that folder, create a CSharp file -- again, pick your own name. The file can contain code, or just be empty. Edit the properties of the file and set the Custom tool value to ZbuModelsBuilder. Save the file, or right-click and Run Custom Tool. New files should appear underneath the file. If there are some filename.cs files in the models folder, the models builder will parse them for instructions (see ??? below).

Instruction for models

Document the attributes:

• IgnoreContentType
• IgnorePropertyType
• ImplementContentType
• ImplementPropertyType
• ModelsNamespace
• ModelsBaseClass
• ModelsUsing
• RenameContentType
• RenamePropertyType

Site Integration Configuration

When running in a website, the models builder supports the following application settings, in the appSettings section of the web.config file:

• EnablePublishedContentModelsFactory - can be true (default) or false, indicates whether the default models factory should be enabled.
• EnableApi - can be true (default) or false, indicates whether the API for Visual Studio should be enabled. If you do not use the Visual Studio extension, you may want to disable the API for extra security.
• EnableLiveModels - can be true or false (default), indicates that "live" models should be activated (see above).
• EnableAppCodeModels - can be true or false (default), indicates that "App_Code" models should be activated (see above).
• EnableAppDataModels - can be true or false (default), indicates that "App_Data" models should be activated (see above).
• ModelsNamespace - (string), specifies the generated models namespace.

Note that EnableLiveModels, EnableAppCodeModels and EnableAppDataModels are exclusive. Only one should be true at a time, else an exception will be thrown.