Kontent.Ai.ModelGenerator 8.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet tool install --global Kontent.Ai.ModelGenerator --version 8.1.0                
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local Kontent.Ai.ModelGenerator --version 8.1.0                
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Kontent.Ai.ModelGenerator&version=8.1.0                
nuke :add-package Kontent.Ai.ModelGenerator --version 8.1.0                

Kontent.ai model generator utility for .NET

Build & Test codecov Stack Overflow Discord

Packages Version Downloads Compatibility Documentation
Kontent.Ai.ModelGenerator NuGet NuGet net6.0 ๐Ÿ“– Docs

This utility generates strongly-typed (POCO) models based on content types in a Kontent.ai project. You can choose one of the following:

โš ๏ธ Please note that this tool uses Delivery SDK and Management SDK.

How to use for Delivery SDK

To fully understand all benefits of this approach, please read the documentation.

.NET Tool

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
  • KontentModelGenerator --projectid "<projectid>" [--namespace "<custom-namespace>"] [--outputdir "<output-directory>"] [--withtypeprovider <True|False>] [--structuredmodel <True|False>] [--filenamesuffix "<suffix>"]
Local Tool
  • dotnet new tool-manifest to initialize the tools manifest (if you haven't done that already)
  • dotnet tool install Kontent.Ai.ModelGenerator (to install the latest version
  • dotnet tool run KontentModelGenerator --projectid "<projectid>" [--namespace "<custom-namespace>"] [--outputdir "<output-directory>"] [--withtypeprovider <True|False>] [--structuredmodel <True|False>] [--filenamesuffix "<suffix>"]

Standalone apps for Windows ๐Ÿ—”, Linux ๐Ÿง, macOS ๐ŸŽ

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

Latest release: Download

  • KontentModelGenerator --projectid "<projectid>" [--namespace "<custom-namespace>"] [--outputdir "<output-directory>"] [--withtypeprovider <True|False>] [--structuredmodel <True|False>] [--filenamesuffix "<suffix>"]

To learn how to generate executables for your favorite target platform, follow the steps in the docs.

Delivery API parameters

Short key Long key Required Default value Description
-p --projectid True null A GUID that can be found in Kontent โ†’ API keys โ†’ Project ID
-n --namespace False KontentAiModels A name of the C# namespace
-o --outputdir False \. An output folder path
-g --generatepartials False true Generates partial classes for customization. Partial classes are the best practice for customization so the recommended value is true.
-t --withtypeprovider False true Indicates whether the CustomTypeProvider class should be generated (see Customizing the strong-type binding logic for more info)
-s --structuredmodel False false Generates IRichTextContent instead of string for rich-text elements. This enables utilizing structured rich-text rendering
-f --filenamesuffix False null Adds a suffix to generated filenames (e.g., News.cs becomes News.Generated.cs)
-b --baseclass False null If provided, a base class type will be created and all generated classes will derive from that base class via partial extender classes

CLI Syntax

Short keys such as -s true are interchangable with the long keys --structuredmodel true. Other possible syntax is -s=true or --structuredmodel=true. Parameter values are case-insensitive, so you can use both -s=true and -s=True. 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> (syntax)

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

Delivery API example output

using System;
using System.Collections.Generic;
using Kontent.Ai.Delivery.Abstractions;

namespace KontentAiModels
{
    public partial class CompleteContentType
    {
        public string Text { get; set; }
        public string RichText { get; set; }
        public decimal? Number { get; set; }
        public IEnumerable<MultipleChoiceOption> MultipleChoice { get; set; }
        public DateTime? DateTime { get; set; }
        public IEnumerable<Asset> Asset { get; set; }
        public IEnumerable<object> ModularContent { get; set; }
        public IEnumerable<object> Subpages { get; set; }
        public IEnumerable<TaxonomyTerm> Taxonomy { get; set; }
        public string UrlSlug { get; set; }
        public string CustomElement { get; set; }
        public ContentItemSystemAttributes System { get; set; }
    }
}

Customizing models - Handling content element constraints

Currently, the generator is built on top of the Delivery API which doesn't provide information about content element constraints such as "Allowed Content Types" or "Limit number of items". In case you want your models to be more specific, this is the best practice on how to extend them:

Model.Generated.cs

public partial class Home
{
    public IEnumerable<object> LinkedContentItems { get; set; }
}

Model.cs

public partial class Home
{
    // Allowed Content Types == "Article"
    public IEnumerable<Article> Articles => LinkedContentItems.OfType<Article>();

    // Allowed Content Types == "Article" && Limit number of items == 1
    public Article Article => LinkedContentItems.OfType<Article>().FirstOrDefault();
}

How to use for Management SDK

Usage

KontentModelGenerator.exe --projectid "<projectid>" --managementapi true --apikey "<apikey>" [--namespace "<custom-namespace>"] [--outputdir "<output-directory>"] [--filenamesuffix "<suffix>"]

Management API parameters

Short key Long key Required Default value Description
-p --projectid True null A GUID that can be found in Kontent โ†’ API keys โ†’ Project ID
-m --managementapi True false Indicates that models should be generated for Content Management SDK
-k --apikey True null A api key that can be found in Kontent โ†’ API keys โ†’ Management API
-n --namespace False KontentAiModels A name of the C# namespace
-o --outputdir False \. An output folder path
-f --filenamesuffix False null Adds a suffix to generated filenames (e.g., News.cs becomes News.Generated.cs)
-b --baseclass False null If provided, a base class type will be created and all generated classes will derive from that base class via partial extender classes

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.

Management API example output

JsonProperty's attribute value is being generated from element codename (not from the type) and KontentElementId attribute value is element's ID.

using Kontent.Ai.Management.Models.LanguageVariants.Elements;
using Kontent.Ai.Management.Modules.ModelBuilders;
using Newtonsoft.Json;

namespace KontentAiModels
{
    public partial class CompleteContentType
    {
        [JsonProperty("text")]
        [KontentElementId("487f9540-0120-49dc-afb2-ee9bccb0c1d7")]
        public TextElement Text { get; set; }
        [JsonProperty("rich_text")]
        [KontentElementId("4517b6da-ed36-48f2-9c8e-00cd6a4cb0ec")]
        public RichTextElement RichText { get; set; }
        [JsonProperty("number")]
        [KontentElementId("4ea37483-c6b1-4b8a-8452-6046f4140923")]
        public NumberElement Number { get; set; }
        [JsonProperty("multiple_choice")]
        [KontentElementId("8fc9a86f-d256-4786-a8f6-c8c90f6ca4e3")]
        public MultipleChoiceElement MultipleChoice { get; set; }
        [JsonProperty("date_time")]
        [KontentElementId("d46fa45c-a1be-4bc7-8b8e-ed3c5521f83c")]
        public DateTimeElement DateTime { get; set; }
        [JsonProperty("asset")]
        [KontentElementId("eb1d611d-b145-4ae3-b22e-ef3609572df0")]
        public AssetElement Asset { get; set; }
        [JsonProperty("modular_content")]
        [KontentElementId("9e520c61-6879-4e83-bcc6-ee6e3e8ce9b4")]
        public LinkedItemsElement ModularContent { get; set; }
        [JsonProperty("subpages")]
        [KontentElementId("fddd89e8-c370-4f9e-9b7d-9daa64d8a252")]
        public LinkedItemsElement Subpages { get; set; }
        [JsonProperty("taxonomy")]
        [KontentElementId("a684d81c-68a7-40e1-85f9-2d22a71bebff")]
        public TaxonomyElement Taxonomy { get; set; }
        [JsonProperty("url_slug")]
        [KontentElementId("1c724f49-b15f-42f5-aab4-4127aa5cf7be")]
        public UrlSlugElement UrlSlug { get; set; }
        [JsonProperty("custom_element")]
        [KontentElementId("cb3b9df0-20df-461c-a0f7-4abb44b83c95")]
        public CustomElement CustomElement { get; set; }
    }
}

โš ๏ธ Please note that Guidelines element is not supported, thus it will not be included in the generated model.

Feedback & Contributing

Check out the contributing page to see the best places to file issues, start discussions and begin contributing.

Wall of Fame

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

Would you like to become a hero too? Pick an issue and send us a pull request!

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last updated
8.4.0 4,564 12/12/2023
8.3.3 1,478 6/4/2023
8.3.2 349 5/18/2023
8.3.1 315 5/5/2023
8.3.0 379 4/20/2023
8.3.0-beta.6 118 4/13/2023
8.3.0-beta.3 98 2/16/2023
8.3.0-beta.2 92 2/16/2023
8.3.0-beta.1 101 2/16/2023
8.2.0 1,082 2/9/2023
8.1.1 1,038 1/5/2023
8.1.1-beta.4 109 10/27/2022
8.1.1-beta.3 103 10/27/2022
8.1.1-beta.2 112 10/27/2022
8.1.1-beta.1 108 10/27/2022
8.1.1-beta.0 111 10/27/2022
8.1.0 2,410 10/27/2022
8.0.0 1,427 8/4/2022
8.0.0-beta.3 138 8/2/2022
8.0.0-beta.2 123 8/1/2022