microsoft / dtdl-model-generator

A library used for generating C# classes from DTDL interfaces.

DTDL Model Generator

This Digital Twin Definition Language (DTDL) Model Generator parses your DTDL json files and generates C# POCO classes to be used when interacting with the Azure Digital Twins SDK. This is made possible because all of the generated model classes inherit from the ADT-provided BasicDigitalTwin class.

Project Components

• Generator: This is the core aspect of this project (supports .Net 6 or higher) and is the package that's published to NuGet.
• Generator.TemplateProject: This is a template project that serves a couple purposes.
  1. It serves as a holding-ground for our custom, complementary classes that help connect the dots between certain aspects of the generated model classes.
  2. In the event a user of the generator doesn't have their own project destination to place the generated classes, this project serves as a template for the user to start from. Our generator will inject the correct Namespace and Assembly information into the template project based on options passed into the Generator.
• Generator.Tests: This is the test project that we use to test our generator.
• Generator.Tests.Generated: This project is produced when we run unit tests for our generator. Having this here also allows us to run unit tests against the generated models to ensure various functionality (like our custom equality implementations) are working as expected.

ModelGeneratorOptions

• Namespace: The namespace that will be injected into the generated model classes.
• JsonModelsDirectory: The directory that contains the DTDL json files that we'll be parsing.
• OutputDirectory: The directory that the generated model classes will be placed in.
• CopyrightHeader: The header comment that contains copyright information.

Prerequisites

The following are some prerequisites/assumptions to be considered:

For Developers

• .Net 6 must be installed, while building the model generator locally. Backward compatibility is not supported.
• The system should have Git installed as the model generator uses MinVer package which requires Git.

For Users

• The following classes have been copied at the location where model generator assembly is being executed:
  • DateOnlyConverter.cs
  • DurationConverter.cs
  • Extensions.cs
  • MapDateOnlyConverter.cs
  • MapDurationConverter.cs
  • ModelHelper.cs
  • Relationship.cs
  • RelationshipCollection.cs
  • RelationshipEqualityComparer.cs
  • SourceValueAttribute.cs
  • TwinEqualityComparer.cs
  • CloudToDeviceMethodOptions.cs
  • CommandHelper.cs
• The ModelGeneratorOptions property "CopyrightHeader" should have "// " prefix.

Limitations

Model Attributes

Content	DTDL v2	Model Generator
Telemetry	✅	❌
Property	✅	✅
Command	✅	✅
Relationship	✅	✅
Component	✅	❌

Schemas

Schemas	DTDL v2	Model Generator
Boolean	✅	✅
Date	✅	✅
DateTime	✅	✅
Double	✅	✅
Duration	✅	✅
Float	✅	✅
Integer	✅	✅
Long	✅	❌
String	✅	✅
Time	✅	✅
Array (Property)	❌	❌
Array (Telemetry)	✅	❌
Enum	✅	✅
Map	✅	✅
Object	✅	✅
Semantic Type (Property)	✅	✅
Semantic Type (Telemetry)	✅	❌

Usage

using Microsoft.DigitalWorkplace.DigitalTwins.Models.Generator;

//...
var currentDir = Directory.GetCurrentDirectory();
var jsonDir = Path.Combine(currentDir, "TestDtdlModels");
var options = new ModelGeneratorOptions
{
    OutputDirectory = Path.Combine(currentDir, "..", "..", "..", "..", "Generator.Tests.Generated"),
    Namespace = "Generator.Tests.Generated",
    JsonModelsDirectory = jsonDir
};

var generator = new ModelGenerator(options);
await generator.GenerateClassesAsync();

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit the Microsoft Contributor License Agreements page.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Security

For guidance on reporting security issues, please refer to the security section.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

dtdl-model-generator's Issues

[Feature]: Support duration primitive type

Is your feature request related to a problem? Please describe.

No.

Describe the feature

The model generator should be able to map the duration primitive type in DTDL to a C# type

Additional context, alternatives considered, etc.

No response

[Bug]: DTDL Command not supported

Describe the bug

Trying to generate from models using DTDL command I got an exeception

Which version of the tool was used?

latest

Options

No response

Steps To Reproduce

I got the error below

Unhandled exception. System.Exception: Unsupported content type: Command
   at Microsoft.DigitalWorkplace.DigitalTwins.Models.Generator.ClassEntity.CreateProperty(DTContentInfo content) in C:\code\dtdl-model-generator\src\Generator\Base\ClassEntity.cs:line 74
   at System.Linq.Enumerable.WhereSelectEnumerableIterator`2.MoveNext()
   at System.Collections.Generic.List`1.InsertRange(Int32 index, IEnumerable`1 collection)
   at System.Collections.Generic.List`1.AddRange(IEnumerable`1 collection)
   at Microsoft.DigitalWorkplace.DigitalTwins.Models.Generator.ModelEntity..ctor(DTInterfaceInfo interfaceInfo, ModelGeneratorOptions options) in C:\code\dtdl-model-generator\src\Generator\Entity\ModelEntity.cs:line 20
   at Microsoft.DigitalWorkplace.DigitalTwins.Models.Generator.ModelGenerator.<GenerateModels>b__10_0(DTInterfaceInfo m) in C:\code\dtdl-model-generator\src\Generator\ModelGenerator.cs:line 80
   at System.Linq.Enumerable.SelectEnumerableIterator`2.MoveNext()
   at Microsoft.DigitalWorkplace.DigitalTwins.Models.Generator.ModelGenerator.GenerateModels(IEnumerable`1 models) in C:\code\dtdl-model-generator\src\Generator\ModelGenerator.cs:line 81
   at Microsoft.DigitalWorkplace.DigitalTwins.Models.Generator.ModelGenerator.GenerateClassesAsync() in C:\code\dtdl-model-generator\src\Generator\ModelGenerator.cs:line 52

[Feature]: Support for Telemetry

Is your feature request related to a problem? Please describe.

No.

Describe the feature

The model generator should be able to generate C# equivalent POCO classes that can represent Telemetry

Additional context, alternatives considered, etc.

No response

[Bug]: Should generated models be usable with ADT Client?

Describe the bug

It seems that model validation will fail with JsonIgnore-fields.

Which version of the tool was used?

Latest ADT client and Model Generator

Options

No response

Steps To Reproduce

1. Generate a model with JsonIgnore fields that are not part of the ADT model schema or are different type (relationship instead of property)
2. Use the C# class to create a new twin with ADT client

ADT will report back with Model Valition Error which complains that specific field inside the class is either wrong type or not part of the model.

For Relationships, this can be circumvented by making Relationships into functions:

[JsonIgnore]
RelationshipCollection Rel_contains {get; set;} = new RelationshipCollection();

//Into

RelationshipCollection Rel_contains() {
  return new RelationshipCollection();
}

This requires a small change in the querybuilder where you need to call for the function, which isn't a big deal, but it kinda ins't the same thing. I am wondering if I am just doing something wrong.

[Feature]: Rework time schema support

Is your feature request related to a problem? Please describe.

No response

Describe the feature

DTDL properties with a date schema are generated as C# DateOnly properties, yet time schema properties generate C# objects.

Additional context, alternatives considered, etc.

In consideration of anyone that needs to use .NET Framework, support for TimeOnly should be guarded by #if NET6_0_OR_GREATER and backported to DateOnly as well.

[Bug]: Generator does not create csproj when one does not already exist

Describe the bug

A new csproj is not created when the OutputDirectory does not exist

Which version of the tool was used?

2fc93de

Options

Modified test/Generator.Tests/Models.UnitTests.cs InitializeAsync() to use Generator.Tests.Foo for output directory and namespace:

var outDir = PathHelper.GetCombinedFullPath(currentDir, "Generator.Tests.Foo", 4); // <--
var options = new ModelGeneratorOptions
{
    OutputDirectory = outDir,
    Namespace = "Generator.Tests.Foo", // <--
    JsonModelsDirectory = jsonDir,
    CopyrightHeader = "// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT License."
};

Steps To Reproduce

The readme states:

2. In the event a user of the generator doesn't have their own project destination to place the generated classes, this project serves as a template for the user to start from. Our generator will inject the correct Namespace and Assembly information into the template project based on options passed into the Generator.

Based on the above, I'd expect the following given the options listed above:

• Generator.Tests.Foo.csproj to be created in the Generator.Tests.Foo directory.
• The RootNamespace and AssemblyName properties have the same value: Generator.Tests.Foo.

[Bug]: README "Project Components" section is outdated

Describe the bug

README "Project Components" section does not reflect the current project structure

Which version of the tool was used?

No response

Options

No response

Steps To Reproduce

No response

Update to use beta/pre-release flow

Now that we have a solid stable release process, we need to incorporate a flow that allows us to release beta/pre-release packages.

Related to/blocked by: Support for pushing beta/pre-release packages

Increase code coverage to 100%

Due to the way our testing is currently done, we did not get the initial release to 100% code coverage.

The goal of this work would be to increase to 100% code coverage.

Some stuff needed to make this happen would be smaller/isolated model sets that would exercise specific aspects of the generation process. i.e. bad models that exercise areas where we throw specific errors. Most of the tests we have right now are happy/normal path scenarios.

[Feature]: Support for Component

Is your feature request related to a problem? Please describe.

No.

Describe the feature

The model generator should be able to generate C# equivalent POCO classes that can represent Components.

Additional context, alternatives considered, etc.

No response

[Bug]: The given key 'en' was not present in the dictionary

Describe the bug

When writing Enum values, lack of [en] Description is handled, but not lack of [en] DisplayName

Which version of the tool was used?

1.0.1

Options

var options = new ModelGeneratorOptions
{
    OutputDirectory = Path.Combine(currentDir, "..", "..", "..", "..", "GeneratedModels"),
    Namespace = "GeneratedModels",
    JsonModelsDirectory = jsonDir
};

Steps To Reproduce

With any model where an EnumValue element is defined, but where both Description and DisplayName are defined like this:
{ "name": "ProductionLine", "displayName": "Production Line", "enumValue": "Production Line" },
or like this:
{ "name": "ProductionLine", "displayName": "Production Line", "description": "A description", "enumValue": "Production Line" },

A KeyNotFoundException is thrown with description 'The given key 'en' was not present in the dictionary'

But if the EnumValue element is defined like this:
{ "name": "ProductionLine", "displayName": { "en": "Production Line" }, "description": { "en": "A description" }, "enumValue": "Production Line" },
no exception is thrown.

The issue is caused by the lack of boolean logic on for DisplayName in the WriteEnumAttributes method of the EnumPropEntity class

[Feature]: Support for date primitive type

Is your feature request related to a problem? Please describe.

No

Describe the feature

The model generator should be able to map the date primitive type in DTDL to a C# type

Additional context, alternatives considered, etc.

No response

Configure/Setup Dependabot

We should follow the GitHub docs on onboarding Dependabot to our repo.

[Bug]: Fix warnings in ModelHelper.cs - Null reference error possibility

Describe the bug

Fix warnings in ModelHelper.cs - Null reference error possibility

Which version of the tool was used?

No response

Options

No response

Steps To Reproduce

No response

[Feature]: Support for Command & CommandPayload

Is your feature request related to a problem? Please describe.

No.

Describe the feature

The model generator should be able to generate C# equivalent POCO classes that can represent Commands and Command Payloads

Additional context, alternatives considered, etc.

No response

[Bug]: Missing nullable annotations on equality operator methods

Describe the bug

The equality operators == and != are missing nullable annotations on their parameter types

Which version of the tool was used?

0.1.0

Options

N/A

Steps To Reproduce

1. Run the generator
2. Inspect generated classes
3. Note missing nullable annotations

[Docs]: Need to update README to be clearer about what is or is not supported and what limitations the generator has

Currently it's not clear from the docs/readme what we don't support and why, so we'll need to make an effort to include this in our documentation.

Configure/Setup CodeQL

We should add CodeQL to our CI for code quality assurance using the provided docs