Home

ZpqrtBnk Umbraco Models Builder
Copyright (C) Pilotine - ZpqrtBnk 2013-2014
Distributed under the MIT license

About

Intro

An experimental tool that can generate a complete set of strongly-typed published content models for Umbraco 6.2+ to be used in the MVC views. Either from the Umbraco UI, from the command line, or from Visual Studio.

What it does

For each content (and media) type in your Umbraco setup, it creates a *.generated.cs file, corresponding the content type, looking like:

namespace MyModels
{
  public partial class NewsItem : PublishedContentModel
  {
    public string Title { get { return this.GetPropertyValue<string>("title"); } }
    public IHtmlString BodyText { get { return this.GetPropertyValue<IHtmlString>("bodyText"); } }
  }
}

Which gives you strongly typed models that you can use in MVC views, because they are natively returned by the Umbraco content cache:

@inherits UmbracoViewPage<NewsItem>
@using MyModels
<h1>@Model.Title</h1>
@Model.BodyText

The models inheritance tree is respected, ie models inherit from each other if required. Mixins are represented by interfaces.

What it does not

This is a "code-after" approach ie it only generates code from models that already exist in Umbraco. It is not generating models based on code, that would be "code-first". You'd want to look at Lars-Erik Umbraco.CodeGen project, which glue together Kevin's uSync and models generation - or to the other code-first projects out there.

Usage

Website integration

This is for people not wanting to use Visual Studio. And it requires that the Umbraco website is running in FullTrust mode. Once you've built the project, you will find an Umbraco package in the pkg directory below the AspNet project, that you can install. Install that package, and there will be a new dashboard in the developer section.

Note that the user running the generator must have permission to access the developer section.

Then, when you go to that dashboard, you can click on a button to generate models. Models file go to ~/App_Data/Models, while a special build.models file goes to ~/App_Core. Removing ~/App_Core/build.models disables the models entirely. Note that generating the models imply touching build.models, which in turn imply restarting the app domain.

There are two AppSettings parameters that you can use to change the way it works:

• Zbu.ModelsBuilder.AspNet.BuildModels: if missing or not set to "true" then the models are generated but ~/App_Core/build.models is not, so the models are not compiled.
• Zbu.ModelsBuilder.ModelsNamespace: the namespace of the models (by default it is Umbraco.Web.PublishedContentModels).

Console application

Still work in progress.

Visual Studio extension

This is the preferred solution for people running Visual Studio. Install the Visual Studio extension. Then...
Go to Tools | Options | Zbu | Models Builder and set the url of your Umbraco website (where the API will be, eg http://umbraco.local/), and a valid username and password to connect to the API (the user must have access to the developer section). Create a Models folder containing a file named "BuildModels.cs" (or any other names) in your solution.
Set the "Custom Tool Namespace" for that file to "MyModels" or whatever you want or leave it blank
Set the "Custom Tool" for that file to "ZbuModelsBuilder"
Save the file...

And it will connect to your Umbraco instance, and generate, underneath that file, all the *.generated.cs files. You will then need to build and deploy your website as usual.

Customize

Because generated classes are partial, you can extend them with your own partial to implement whatever you want. The models generator generates properties but not accessors to children, so you have to do it with partials.

To use a different class name (default being derived from the alias):

using Zbu.ModelsBuilder;
namespace MyModels
{
  // alias is myModelType but class should be named MyModel
  [RenameContentType("myModelType")]
  public partial class MyModel
  {
  }
}

To exclude a type from the generation, just make sure that a file containing the following is present in the appropriate directory:

using Zbu.ModelsBuilder;
[assembly: IgnoreContentType("alias")]

To exclude a property from the generation, mark the type itself:

using Zbu.ModelsBuilder;
namespace MyModels
{
  [IgnorePropertyType("alias")]
  public partial class MyModel
  {
  }
}

Or use a different property name, two solutions. Either at the type class level:

using Zbu.ModelsBuilder;
namespace MyModels
{
  [RenamePropertyType("alias", "name")]
  public partial class MyModel
  {
  }
}

Or directly on the property:

using Zbu.ModelsBuilder;
namespace MyModels
{
  public partial class MyModel
  {
    [RenamePropertyType("alias")]
    public string MyProperty { get { return this.GetPropertyValue<string>("alias"); } }
  }
}

Models

The models have extra static properties and methods:

• GetModelContentType() returns the PublishedContentType.
• GetModelPropertyType(x => x.Valueint) returns the PublishedPropertyType for the specified property (useful to retrieve the preValues, etc).
• ModelItemType returns the content type item type (media, content...).
• ModelTypeAlias returns the content type alias.