Refactoring the ModelsBuilder TextWriter to use Interfaces and DI for more flexibility in how we build our models

[kasparboelkjeldsen]

After getting PR #16919 merged, I humbly request the ability to "shoot myself in the foot" with the ModelsBuilder.

TL;DR: After the above merge, you can now essentially replace the ModelsBuilder by replacing the implementation of IModelsGenerator.

That is a good start, but I think we could use more tools for customizing the ModelsBuilder according to our needs.

Today, the short version of how the ModelsBuilder generates code models is a class called TextBuilder that exposes two "Generate" methods. Call those with a StringBuilder and a collection of types, and you get models out.

However, it is not very flexible, and I think we should split it into multiple levels of classes backed by interfaces that are registered for dependency injection. This would allow us to replace or decorate the ModelsBuilder as needed.

I have made a working implementation that passes all tests but is otherwise very much a proof of concept. The branch is visible here.

I haven't created a pull request yet because I'd love to have a conversation about this first.

Everything is built on top of existing code with significant refactoring of where things live but, to my knowledge, retains 100% feature parity with how the contrib branch works today.

In short: TextBuilder.cs, which currently inherits from Builder.cs, is split into four interfaces, detailing the levels of complexity you can use with the ModelsBuilder.

1. IBuilderBase

public interface IBuilderBase
{
    IEnumerable<TypeModel> GetModelsToGenerate();
    string GetModelsNamespace();
    bool IsAmbiguousSymbol(string symbol, string match);
    string GetModelsBaseClassName(TypeModel type);
    void Prepare(IEnumerable<TypeModel> types);
    IList<string> Using { get; set; }
}

Instead of having TextBuilder inherit from Builder, we rename Builder to BuilderBase. It serves as a common foundation for base functionality in the ModelsBuilder (e.g., determining models, namespaces, usings, etc.).

Then we simplify TextBuilder.cs significantly with the following interface:

2. ITextBuilder

public interface ITextBuilder
{
    void Generate(StringBuilder sb, TypeModel typeModel);
    void Generate(StringBuilder sb, IEnumerable<TypeModel> typeModels);
}

This interface is ideal for scenarios where you want to generate your own code or perform simple replacements in the generated code through a decorator without getting into deeper complexities.

3. ITextBuilderActions

You can see it "in action" in the Generate methods:

public void Generate(StringBuilder sb, TypeModel typeModel)
{
    _textBuilderActions.WriteHeader(sb);
    _textBuilderActions.WriteUsing(sb, _builderBase.Using);
    _textBuilderActions.WriteNamespace(sb, _builderBase.GetModelsNamespace());
    _textBuilderActions.WriteContentType(sb, typeModel, false);
    _textBuilderActions.WriteContentTypeProperties(sb, typeModel);
    _textBuilderActions.WriteCloseClass(sb);
}

The interface:

public interface ITextBuilderActions
{
    void WriteHeader(StringBuilder sb);
    void WriteAssemblyAttributesMarker(StringBuilder sb);
    void WriteUsing(StringBuilder sb, IEnumerable<string> typeUsing);
    void WriteNamespace(StringBuilder sb, string modelNamespace);
    void WriteContentType(StringBuilder sb, TypeModel type, bool lineBreak);
    void WriteContentTypeProperties(StringBuilder sb, TypeModel type);
    void WriteCloseClass(StringBuilder sb);
}

This abstraction separates the actual generation of text/code for models, allowing for easier customization or decoration. For instance, you could change the header text or insert custom code at the end of the class without delving into the more detailed aspects of code generation.

4. ITextBuilderSubActions

Finally, the TextBuilderAction implementation injects the ITextBuilderSubActions interface, which provides fine control over model building:

public interface ITextBuilderSubActions
{
    string XmlCommentString(string input);
    void WriteInterfaceProperty(StringBuilder sb, PropertyModel property);
    void WriteGeneratedCodeAttribute(StringBuilder sb, string tabs);
    void WriteMaybeNullAttribute(StringBuilder sb, string tabs, bool isReturn = false);
    void WriteMixinProperty(StringBuilder sb, PropertyModel property, string mixinClrName);
    void WriteProperty(StringBuilder sb, TypeModel type, PropertyModel property, string? mixinClrName = null);
    void WriteClrType(StringBuilder sb, Type type);
    void WriteNonGenericClrType(StringBuilder sb, string s);
    void WriteClrType(StringBuilder sb, string type);
}

Anyone else tired of having a git change on every single model whenever you update Umbraco because it writes the version into the attribute? Now, you can decorate or change that by replacing the implementation of WriteGeneratedCodeAttribute.

So far, this only represents hours, not days, of work because I wanted to ensure it was working and passing tests before proposing such a significant change. But here it is.

With this implementation, or something like it, it would be trivial to create small Umbraco packages that do interesting things like removing the Umbraco version, adding custom "using" lines, or adding extension methods to every generated model.

Thoughts?

[skttl]

Anyone else tired of having a git change on every single model whenever you update Umbraco because it writes the version into the attribute? Now, you can decorate or change that by replacing the implementation of WriteGeneratedCodeAttribute.

Me too. I created a VersionlessModelsGenerator inheriting from the default ModelsGenerator and added that with builder.Services.AddSingleton<IModelsGenerator, VersionlessModelsGenerator>();.

What it does? It simply runs base.GenerateModels();, and then strips all version info from the generated files using a regex :)

Would love a more flexible approach for modelsbuilder, eg. also to be able to export consts of property aliases. There was a lot of interesting feature requests in the old Modelsbuilder repo too.

[bergmania]

More abstractions sounds good with me :)

The current implementation was a simple copy/paste of the old external package, and then afterwards updated with the required changes due to .NET.
We do not plan to make changes to the area in the short term, so all community contributions are welcomed :)

Ultimately, we would like it to be completely extendable, so things like the enums are just strings, so packages can bring their own modes too. Furthermore, we would like all runtime-compilation of Umbraco to be separated from the rest of the codebase, including the InMemoryAuto mode.