Azure Digital Twin library, which contains common services for Azure Digital Twins, Model Validation and parsing.
- Introduction
- Table of Content
- Atc.Azure.DigitalTwin
- CLI
- Sample Project
- Requirements
- How to contribute
The Atc.Azure.DigitalTwin library provides a suite of services designed to facilitate the development, deployment, and management of Azure Digital Twins solutions. This library encompasses tools for robust model validation, efficient parsing, and comprehensive management of digital twins and their relationships. It supports seamless integration with existing Azure services, offering scalable options for managing complex digital twins environments. The library is essential for developers looking to leverage Azure Digital Twins in their IoT, AI, and data analytics applications, ensuring both flexibility and precision in digital twin interactions.
The IDigitalTwinService offers comprehensive functionalities for managing and interacting with digital twins and their models, including CRUD operations, relationship handling, and querying capabilities within an Azure Digital Twins instance.
- Model Management: Create, retrieve, update, and delete digital twin models.
- Twin Management: Perform operations on digital twins such as creation, retrieval, update, and deletion
- Relationship Management: Manage relationships between digital twins, including creation, updates, and deletions.
- Querying Capabilities: Execute queries to retrieve twins, relationships, and other data points based on specific criteria.
Below is a usage example of how to interact with digital twins using IDigitalTwinService:
var digitalTwinService = serviceProvider.GetRequiredService<IDigitalTwinService>();
var twinId = "your_twin_id";
var twinData = await digitalTwinService.GetTwin(twinId);
if (twinData is not null)
{
Console.WriteLine($"Retrieved Twin: {twinData.Id}");
}
// Create a new relationship between two twins
var sourceTwinId = "source_twin_id";
var targetTwinId = "target_twin_id";
var relationshipName = "relatesTo";
var createResult = await digitalTwinService.CreateRelationship(sourceTwinId, targetTwinId, relationshipName);
if (createResult.Succeeded)
{
Console.WriteLine("Relationship created successfully.");
}
else
{
Console.WriteLine($"Failed to create relationship: {createResult.ErrorMessage}");
}The ConfigureDigitalTwinsClient extension method from ServiceCollectionExtensions helps configure and register Digital Twin related services with your application's IServiceCollection.
Here's how you can configure your services using this extension method:
public void ConfigureServices(IServiceCollection services)
{
var digitalTwinOptions = new DigitalTwinOptions
{
TenantId = "your_tenant_id",
InstanceUrl = "your_instance_url",
};
// Ensure these options are added to the DI container
services.AddSingleton<DigitalTwinOptions>(digitalTwinOptions);
services.ConfigureDigitalTwinsClient();
}The IModelRepositoryService manages local repositories of digital twin models, providing functionality for adding, retrieving, and clearing models from the local store.
- Model Storage: Manage a local repository of digital twin models.
- Content Management: Handle the content of model files, including loading and storing JSON representations.
- Validation: Validate the models against a set of predefined rules and definitions.
Below is an example demonstrating how to utilize the IModelRepositoryService to manage DTDL models:
var modelRepositoryService = serviceProvider.GetRequiredService<IModelRepositoryService>();
var modelDirectoryInfo = new DirectoryInfo("path_to_model_files"); // Specify the path to your model files
var loadedSuccessfully = await modelRepositoryService.LoadModelContent(modelDirectoryInfo);
if (loadedSuccessfully)
{
var validationSucceeded = await modelRepositoryService.ValidateModels(modelDirectoryInfo);
if (validationSucceeded)
{
Console.WriteLine("Models loaded and validated successfully.");
}
else
{
Console.WriteLine("Model validation failed.");
}
}
else
{
Console.WriteLine("Failed to load model content.");
}The IDigitalTwinParser provides functionality for parsing JSON models into Digital Twin Interface definitions, aiding in the transformation and validation of digital twin data schemas.
- Model Transformation: Convert JSON formatted digital twin models into DTDL (Digital Twins Definition Language) interface definitions.
- Validation: Ensure the integrity and correctness of digital twin models through rigorous validation checks.
-
- Error Handling: Efficiently manage parsing errors, providing detailed insight into the issues encountered during the parsing process.
Below is an example demonstrating how to utilize the IDigitalTwinParser to parse JSON DTDL models:
var digitalTwinParser = serviceProvider.GetRequiredService<IDigitalTwinParser>();
var jsonModels = new[] { "{...JSON data...}" }; // Replace with actual JSON strings
var parsingResult = await digitalTwinParser.Parse(jsonModels);
if (parsingResult.Succeeeded)
{
foreach (var dtInterface in parsingResult.Interfaces)
{
Console.WriteLine($"Parsed Interface: {dtInterface.Key}, Info: {dtInterface.Value}");
}
}
else
{
Console.WriteLine("Failed to parse models.");
}
The Atc.Azure.DigitalTwin.CLI tool is available through a cross platform command line application.
The tool can be installed as a .NET global tool by the following command
dotnet tool install --global atc-azure-digitaltwinor by following the instructions here to install a specific version of the tool.
A successful installation will output something like
The tool can be invoked by the following command: atc-azure-digitaltwin
Tool 'atc-azure-digitaltwin' (version '1.0.xxx') was successfully installed.`The tool can be updated by the following command
dotnet tool update --global atc-azure-digitaltwinSince the tool is published as a .NET Tool, it can be launched from anywhere using any shell or command-line interface by calling atc-azure-digitaltwin. The help information is displayed when providing the --help argument to atc-azure-digitaltwin
atc-azure-digitaltwin --help
USAGE:
atc-azure-digitaltwin.exe [OPTIONS] <COMMAND>
EXAMPLES:
atc-azure-digitaltwin.exe model decommission --tenantId -a <adt-instance-url> -m <model-id>
atc-azure-digitaltwin.exe model validate -d <directory-path>
atc-azure-digitaltwin.exe route create
atc-azure-digitaltwin.exe route delete
atc-azure-digitaltwin.exe twin count --tenantId -a <adt-instance-url>
OPTIONS:
-h, --help Prints help information
-v, --version Prints version information
COMMANDS:
model Operations related to models
route Operations related to event routes
twin Operations related to twinsThis console application serves as an example to demonstrate the utilization of services provided by the library. It showcases a series of operations related to Digital Twins using the example DTDL (Digital Twins Definition Language) models.
The sample application executes the following operations:
- Validate Models: Validates the DTDL models located in the models folder.
- Load Models: Loads the DTDL models from the models folder.
- Create Models: Registers the loaded models with a Digital Twin instance.
- Retrieve Model: Fetches a specific model from the Digital Twin instance.
- Create Digital Twin: Generates a digital twin instance of a Press Machine.
Note: This twin inherits properties from
TwinModelBase, which provides essential attributes for twin creation. - Retrieve Twins: Collects all existing twins.
- Delete Twin: Removes the specified twin instance.