Models Builder Extension

Posted on July 19, 2019 in umbraco

One way to generate models for Umbraco with the Models Builder tool has long been to use the Visual Studio Custom Tool. This extension provides a Single File Generator which can be used just as any standard Visual Studio Custom Tool.

Meanwhile, Microsoft has introduced .NET Core and is slowly evolving the structure of its Visual Studio projects, and updating the tooling along the way. Let us say that the road is, sometimes, a bit unclear and hard to follow.

Using a single file generator to generate multiple files has traditionally been "the way" to do it, but it has also always been hackish, and as this issue and others made obvious. It is becoming harder and harder to support with the new "NET.Sdk" project types.

I am, therefore, sad to announce that the Custom Tool is now dead. But do not despair! It is superceeded by the Extension, which, essentially, provides exactly the same service, in a slightly different way.

Migrating

In order to migrate to the extension, first uninstall the Custom Tool extension, then install the Extension.

Then, the only difference is that models are not generated under a C# file anymore, but under a special placeholder. You probably don't need the root C# file anymore, unless it contained attributes to configure models. The next section will explain it all.

The configuration (in Tools | Options) remain the same.

Using the extension

Right-click on the folder containing your models, both the generated and non-generated partials. Select Add | New item....

Select Visual C#, Umbraco, and add a new Umbraco Models placeholder named, for instance, Models.mb. The name is of no importance, only the extension is.

Now, right-click on that new Models.mb file and select Build Models.

The extension connects to the running site, retrieves models, and adds them to the project, nicely nested under the models placeholder.

Configuring

By default, models are generated in a namespace derived from the root namespace of the project, and the folders structure. That, and various other aspects of models, can be configured via attributes.

Add a file Models.cs (or any other name, as long as it is a C# file) to the models folder, containing the following code (it does not need to contain a class definition!):

using Umbraco.ModelsBuilder;

[assembly:ModelsNamespace("MyOwnNamespace")]

That file will be parsed, and models will be generated in MyOwnNamespace.

Refer to the (kinda obsolete, soon to be updated) documentation for more attributes.

What's Next?

As mentioned above, the documentation is kinda obsolete. There are tons of things that can be configured, and noone is aware of it. Next effort will be to cleanup the documentation, and implement some long-requested features.

Stay tuned!