Kontent.Ai.ModelGenerator.Core 10.3.0-beta-1

Kontent.ai model generator utility for .NET

This utility generates strongly-typed record-based models for:

• the Kontent.ai Delivery SDK for .NET (v19+) — default mode, for reading content
• the Kontent.ai Management SDK for .NET — opt-in mode (-m / --management), for CRUD workflows. Beta — targets Kontent.Ai.Management 9.0.0-beta-1.

What's New in Updated Delivery Models

The generated models use modern C# features and patterns:

• Records - Immutable record types with { get; init; } accessors
• Modern types - RichTextContent, Asset, TaxonomyTerm, IEmbeddedContent
• Partial records - Easily extendable without modifying generated code
• ContentTypeCodename attribute - For source-generated TypeProvider discovery
• ContentTypeCodename constant - Access the content type codename at compile time (usable in switch/case labels, attribute arguments, and other contexts that require a compile-time constant) without reflection

Installation & Usage

.NET Tool (Recommended)

The recommended way of obtaining this tool is installing it as a .NET Tool. You can install it as a global tool or per project as a local tool.

Global Tool

dotnet tool install -g Kontent.Ai.ModelGenerator

Delivery (default):

KontentModelGenerator --environmentId "<environmentId>" \
    [--namespace "<custom-namespace>"] \
    [--outputdir "<output-directory>"] \
    [--baseRecord "<base-record-name>"] \
    [--nullability strict|semantic]

Management (beta — see Management Models):

KontentModelGenerator --management \
    --environmentId "<environmentId>" \
    --apiKey "<management-api-key>" \
    [--namespace "<custom-namespace>"] \
    [--outputdir "<output-directory>"]

Local Tool

dotnet new tool-manifest
dotnet tool install Kontent.Ai.ModelGenerator

dotnet tool run KontentModelGenerator --environmentId "<environmentId>" \
    [--namespace "<custom-namespace>"] \
    [--outputdir "<output-directory>"] \
    [--baseRecord "<base-record-name>"] \
    [--nullability strict|semantic]

Standalone apps for Windows, Linux, macOS

Self-contained apps are an ideal choice for machines without any version of .NET installed.

Latest release: Download

<details> <summary>Building a self-contained binary for a specific platform</summary>

• Clone the repository
• Navigate to src/Kontent.Ai.ModelGenerator
• dotnet build -r <RID> to build (see the list of all RIDs)
• dotnet publish -c release -r <RID> to publish

</details>

Parameters

CLI Syntax

Short keys such as -n "MyModels" are interchangeable with the long keys --namespace "MyModels". Other possible syntax is -n=MyModels or --namespace=MyModels. Parameter values are case-insensitive. To see all aspects of the syntax, see the MS docs.

Config file

These parameters can also be set via the appSettings.json file located in the same directory as the executable file. Command-line parameters always take precedence.

Advanced configuration (Preview API, Secure API)

There are two ways of configuring advanced Delivery SDK options (such as secure API access, preview API access, and others):

1. Command-line arguments:

   --DeliveryOptions:UseSecureAccess true --DeliveryOptions:SecureAccessApiKey <SecuredApiKey>
   

2. appSettings.json - suitable for the standalone app release

Generated Model Example (Delivery)

For the Management-mode equivalent, jump to Management Models.

Generated file: Article.cs

// <auto-generated>
// This code was generated by Kontent.ai model generator tool
// (see https://github.com/kontent-ai/model-generator-net).
//
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
// To extend this record, create a separate partial record with the same name.
// </auto-generated>

#nullable enable

using System.Collections.Generic;
using System.Text.Json.Serialization;
using Kontent.Ai.Delivery.Abstractions;
using Kontent.Ai.Delivery.Attributes;
using Kontent.Ai.Delivery.ContentItems;
using Kontent.Ai.Delivery.ContentItems.RichText;
using Kontent.Ai.Delivery.SharedModels;

namespace KontentAiModels;

[ContentTypeCodename("article")]
public partial record Article
{
    public const string BodyCopyCodename = "body_copy";
    public const string CustomTrackingCodeCodename = "custom_tracking_code";
    public const string PersonasCodename = "personas";
    public const string PostDateCodename = "post_date";
    public const string RelatedArticlesCodename = "related_articles";
    public const string TeaserImageCodename = "teaser_image";
    public const string TitleCodename = "title";
    public const string UrlPatternCodename = "url_pattern";

    public const string ContentTypeCodename = "article";

    [JsonPropertyName("body_copy")]
    public RichTextContent? BodyCopy { get; init; }
    [JsonPropertyName("custom_tracking_code")]
    public string? CustomTrackingCode { get; init; }
    [JsonPropertyName("personas")]
    public IEnumerable<TaxonomyTerm>? Personas { get; init; }
    [JsonPropertyName("post_date")]
    public DateTimeContent? PostDate { get; init; }
    [JsonPropertyName("related_articles")]
    public IEnumerable<IEmbeddedContent>? RelatedArticles { get; init; }
    [JsonPropertyName("teaser_image")]
    public IEnumerable<Asset>? TeaserImage { get; init; }
    [JsonPropertyName("title")]
    public string? Title { get; init; }
    [JsonPropertyName("url_pattern")]
    public string? UrlPattern { get; init; }
}

Nullability mode

The generator supports two nullability strategies for element properties via the --nullability flag:

strict (default)

Every element property is generated as a nullable type — string?, RichTextContent?, IEnumerable<Asset>?, etc. This is the conservative default. It's also useful if you use the Delivery SDK's projection features (WithElements / WithoutElements) and want the type system to distinguish "not fetched" (null) from "fetched and empty" — projected-away elements surface as null at runtime.

public string? Title { get; init; }
public RichTextContent? BodyCopy { get; init; }
public IEnumerable<IEmbeddedContent>? RelatedArticles { get; init; }

semantic

Element properties match the runtime semantics of the Delivery API: empty text, rich text and collection elements always come back populated, so they're generated as non-nullable with sensible default initializers. Numbers, dates and custom elements can be genuinely unset, so they remain nullable.

public string Title { get; init; } = string.Empty;
public RichTextContent BodyCopy { get; init; } = RichTextContent.Empty;
public IEnumerable<IEmbeddedContent> RelatedArticles { get; init; } = [];
public double? Rating { get; init; }
public DateTimeContent? PostDate { get; init; }
public string? CustomTrackingCode { get; init; }

Customizing Generated Models

Since the generated models are partial records, you can extend them by creating your own partial record file:

Generated file: Article.cs (auto-generated)

namespace KontentAiModels;

[ContentTypeCodename("article")]
public partial record Article
{
    public const string TitleCodename = "title";
    // ... other constants and properties

    public const string ContentTypeCodename = "article";

    [JsonPropertyName("title")]
    public string? Title { get; init; }
}

Your custom file: Article.Custom.cs (your customizations)

namespace KontentAiModels;

public partial record Article
{
    // Add computed properties
    public string Slug => Title?.ToLowerInvariant().Replace(" ", "-") ?? string.Empty;

    // Add custom methods
    public bool IsPublished() => PostDate is { DateTime: var dt } && dt <= DateTime.Now;

    // Add validation
    public bool IsValid() => !string.IsNullOrEmpty(Title) && BodyCopy != null;
}

The generator creates the base model, and you maintain customizations in separate files that won't be overwritten.

Management Models

When you need to write content to Kontent.ai (create / update / delete / publish via the Management API), pass -m / --management to switch the generator from Delivery mode into Management mode. The emitter produces strongly-typed records you can construct with object-initializer syntax and pass to IManagementClient.

CLI

KontentModelGenerator --management \
    --environmentId "<environmentId>" \
    --apiKey "<management-api-key>" \
    [--namespace "<custom-namespace>"] \
    [--outputdir "<output-directory>"]

What's different from Delivery models

Generated model example

Generated file: Article.cs

// <auto-generated/>

#nullable enable

using System;
using System.Collections.Generic;
using Kontent.Ai.Management;
using Kontent.Ai.Management.Annotations;
using Kontent.Ai.Management.Models.Content;

namespace MyProject.Models;

[KontentType("article")]
public sealed partial record Article : IElementsModel
{
    [KontentElement("body", "7ed15846-...")]
    public RichTextValue? Body { get; init; }

    [KontentElement("category", "f6d310a3-...")]
    public IEnumerable<ArticleCategory>? Category { get; init; }

    [KontentElement("featured_image", "8d2c...")]
    public IEnumerable<AssetReference>? FeaturedImage { get; init; }

    [KontentElement("priority", "88ae3d9b-...")]
    public decimal? Priority { get; init; }

    [KontentElement("publish_at", "b12f0a44-...")]
    public DateTimeValue? PublishAt { get; init; }

    [KontentElement("rating_widget", "c93b71de-...")]
    public CustomValue? RatingWidget { get; init; }

    [KontentElement("related_teasers", "a3155ec4-...")]
    public IEnumerable<Reference>? RelatedTeasers { get; init; }

    [KontentElement("seo__meta_title", "09398b24-...")]
    public string? SeoMetaTitle { get; init; }

    [KontentElement("tags", "1314993e-...")]
    public IEnumerable<Reference>? Tags { get; init; }

    [KontentElement("title", "a47451eb-...")]
    public string? Title { get; init; }

    [KontentElement("url", "e5a8c0f1-...")]
    public UrlSlugValue? Url { get; init; }
}

public enum ArticleCategory
{
    [KontentEnumValue("news", "d65a2212-...")] News,
    [KontentEnumValue("release", "709b1208-...")] Release,
    [KontentEnumValue("blog", "ae79c5a6-...")] Blog,
}

Notes

• Models are environment-specific by virtue of their element IDs. Cloning an environment via data-ops produces logically identical content models with different element IDs — regenerate after cloning.
• Snippets are flattened. If your content type uses an seo snippet that contributes meta_title and meta_description, the generated record has SeoMetaTitle and SeoMetaDescription properties; the [KontentElement] attributes carry the seo__meta_title / seo__meta_description codenames the API expects.
• Content-model constraints are not on the model. Length, regex, allowed types, count limits, asset rules, and the like are enforced server-side by the Management API and surfaced via IManagementResult — the generated records carry element identity and value types only.

Need Legacy Delivery SDK or Extended Delivery Support?

Feedback & Contributing

Found a bug or have a feature request? Open an issue. Pull requests are welcome!

Wall of Fame

We would like to express our thanks to the following people who contributed and made the project possible:

• Drazen Janjicek - EXLRT
• Kashif Jamal Soofi
• Casey Brown

License

MIT