Azure IoT Digital Twins client library for .NET - version 1.4.0

Article
10/11/2022

This library provides access to the Azure Digital Twins service for managing twins, models, relationships, etc.

Getting started

The complete Microsoft Azure SDK can be downloaded from the Microsoft Azure downloads page, and it ships with support for building deployment packages, integrating with tooling, rich command line tooling, and more.

For the best development experience, developers should use the official Microsoft NuGet packages for libraries. NuGet packages are regularly updated with new functionality and hotfixes.

Install the package

Install the Azure Digital Twins client library for .NET with NuGet:

dotnet add package Azure.DigitalTwins.Core

View the package details at nuget.org.

Prerequisites

A Microsoft Azure Subscription
- To call Microsoft Azure services, create an Azure subscription.
An Azure Digital Twins instance
- In order to use the Azure Digital Twins SDK, first create a Digital Twins instance using one of options:
  - Using Azure portal
  - Using Azure Management APIs
  - Using Azure CLI
    - You will need to install azure cli and the Azure IoT extension for Azure CLI.
    - Refer to IoT CLI documentation for more information on how to create and interact with your Digital Twins instance.

Authenticate the Client

In order to interact with the Azure Digital Twins service, you will need to create an instance of a TokenCredential class and pass it to the constructor of your DigitalTwinsClient.

Key concepts

Azure Digital Twins Preview is an Azure IoT service that creates comprehensive models of the physical environment. It can create spatial intelligence graphs to model the relationships and interactions between people, spaces, and devices.

You can learn more about Azure Digital Twins by visiting Azure Digital Twins Documentation

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Examples

You can familiarize yourself with different APIs using samples for Digital Twins.

Source code folder structure

/src

The Digital Twins public client, DigitalTwinsClient, and the additional configuration options, DigitalTwinsClientOptions, that can be sent to the Digital Twins service.

/src/Generated

The code generated by autorest using the swagger file defined in the autorest config file.

To regenerate the code, run the powershell script generate.ps1.

Any time the client library code is updated, the following scripts need to be run:

Export-AdtApis.ps1, which will update the API surface document.
Update-Snippets.ps1, which will update all the code snippets in the readme files and in the client documentation comments.

/src/Customized

The customzied code written to override the following behavior of auto-generated code:

Rename some of the generated types, eg. GetModelsOptions
Declare some of the generated types as internal, instead of the autorest default of public.
Declare some methods to accept input parameters as strings instead of objects.
Declare some methods to return the response as strings instead of objects.

/src/Models

Model classes useful for use with the Digital Twins client operations.

/src/Properties

Assembly properties required for running unit tests.

/src/Serialization

Serialization helpers provided to help serialize/deserialize commonly used types within the Digital Twins service.

Troubleshooting

All service operations will throw RequestFailedException on failure reported by the service, with helpful error codes and other information.

For example, use the GetModelAsync operation to check if the model exists before creating it, catch only when that specific HttpStatusCode is specified.

try
{
    Response<ModelData> desiredModel = await DigitalTwinsClient.GetModelAsync(desiredModelId);
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
{
    // Model does not exist, so create it.
}

Next steps

See implementation examples with our code samples.

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 https://cla.microsoft.com.

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., label, 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.

Share via