Elastacloud.TwinMigration 0.0.0.1

Introduction

An SDK wrapper around Azure Digital Twins SDK that provides additional best practices around versioning, query helpers, fluent access to creation.

Versioning

Digital Twin instances are typed. These types are described by DTDL models which can be versioned. You should keep your DTDL in JSON files, git control them and then target a deployment in an automated way.

The main challenges facing us with Versioning are:

• How do we keep digital twin instance matching the desired version of the DTDL model?
  • We may want migrate digital twin instances to new versions of DTDL models over time or there may be a migration process, such as adding a value for a new property
• When working with digital twin instances in client code (e.g. C#) how do we map the digital twin instance to the appropriate POCO? (Or, perhaps, is there one POCO that subsumes all versions?)

This repo provides a dotnet tool, a Global Tool to assist in the validation and deployment of Azure Digital Twin models. It has multiple modes, as described below.

Installation

dotnet tool install twinmigration

Validation

Purpose: To generate Markdown compatible tables of DTDL compliance between a source input path and a target ADT.

You can execute it in a number of ways:

1. Source Input Files to Target ADT - allows you to ask "what is deployed that is different to my local DTML?"
2. Source Input Files to Target Input Files - allows you to ask "what is different two sets of DTDL files held locally?"
3. Source ADT to Target ADT - allows you to ask "what is deployed differently between these ADT instances?"
4. Source ADT to Target Input Files - allows you to ask "what is different from the deployment to my local DTML?"

Usage

twinmigration validate --source-input-path C:\DTDL\Latest --target-twin-instance https://[myTwinInstance].api.weu.digitaltwins.azure.net

Example Output

Deployment

twinmigration deploy --source-input-path C:\DTDL\Latest --target-twin-instance https://[myTwinInstance].api.weu.digitaltwins.azure.net

This will take all the Models defined in the --source-input-path and apply them to the target instance.

Available flags:

• -f --force will skip local validation code and attempt the full deployment
• -c --strict will cause local validation to fail if there is a version update that skips a version, for example from dtmi:elastacloud:code;1 to dtmi:elastacloud:code;3.

Decommission

twinmigration decommission --target-twin-instance https://[myTwinInstance].api.weu.digitaltwins.azure.net

This will take all the Models defined in the target Azure Digital Twin and will decommission it, if there is a later version of the model available. This means we can deploy new models, have runtime code still able to target old models while the runtime code is being updated, and then have the old models decommissioned when the runtime code has been replaced.

Available Flags:

• -o --tolerance default 1, controls how many versions out of date a model must be before it is selected for decommissioning. For instance if dtmi:elastacloud:code;4 exists and running with tolerance of 2 will decommission dtmi:elastacloud:code;1 and dtmi:elastacloud:code;2

Query Helpers

This repo provides a dotnet package to assist in the runtime management of these versions, to provide a POCO for acting as a container for the instance data, and validating POCOs against deployed DTDL instances.