Руководство. Написание кода с помощью пакета SDK для Azure Digital Twins

2025-02-14

Разработчики, использующие Azure Digital Twins, часто создают клиентские приложения для взаимодействия со своим экземпляром службы Azure Digital Twins. Этот учебник предназначен для разработчиков и содержит вводные сведения о программировании для службы Azure Digital Twins с помощью пакета SDK Azure Digital Twins для .NET (C#). В нем пошагово описывается процесс написания консольного клиентского приложения на C# с самого начала.

Настройка проекта
Начало создания кода проекта
Полный пример кода
Очистка ресурсов
Следующие шаги

Предварительные условия

В этом учебнике по Azure Digital Twins настройка и работа над проектом выполняется в командной строке. Поэтому для выполнения упражнений вы можете использовать любой редактор кода.

Для начала работы вам потребуется следующее.

Любой редактор кода.
.NET Core 3.1 на вашем компьютере разработчика. Вы можете скачать эту версию пакета SDK .NET Core для нескольких платформ по этой ссылке: Загрузка .NET Core 3.1.

Подготовьте экземпляр Azure Digital Twins

Для работы с Azure Digital Twins в этой статье требуется экземпляр Azure Digital Twins и необходимые разрешения для его использования. Если у вас уже настроен экземпляр Azure Digital Twins, вы можете использовать этот экземпляр и перейти к следующему разделу. В противном случае выполните инструкции по настройке экземпляра и аутентификации. Инструкции содержат сведения, помогающие убедиться, что каждый шаг выполнен успешно.

После настройки экземпляра запишите имя хоста экземпляра. Вы можете найти имя хоста на портале Azure.

Настройка локальных учетных данных Azure

В этом примере используется DefaultAzureCredential (часть библиотеки Azure.Identity) для аутентификации пользователей с помощью экземпляра Azure Digital Twins, запускаемого на локальном компьютере. Дополнительные сведения о различных способах аутентификации клиентского приложения в Azure Digital Twins см. в статье о записи кода аутентификации приложения.

В образце DefaultAzureCredential выполняется поиск учетных данных в вашей локальной среде, таких как вход в Azure через локальную командную строку Azure или в Visual Studio или Visual Studio Code. Поэтому вам нужно войти в Azure локально с помощью одного из этих механизмов, чтобы настроить учетные данные для примера.

Если вы используете Visual Studio или Visual Studio Code для выполнения примеров кода, убедитесь, что вы вошли в этот редактор с теми же учетными данными Azure, которые вы хотите использовать для доступа к экземпляру Azure Digital Twins. Если вы используете локальное окно CLI, выполните az login команду, чтобы войти в учетную запись Azure. После входа при запуске примера кода необходимо автоматически пройти проверку подлинности.

Настройка проекта

Когда вы будете готовы к работе со своим экземпляром Azure Digital Twins, начните с настройки проекта клиентского приложения.

Откройте окно консоли на компьютере и создайте пустой каталог проекта, в котором вы хотите сохранить работу в рамках этого руководства. Присвойте этому каталогу любое имя (например, DigitalTwinsCodeTutorial).

Перейдите в новый каталог.

В этом каталоге проекта создайте пустой проект консольного приложения .NET. В командном окне можно выполнить следующую команду, чтобы создать минимальный проект C# для консоли:

dotnet new console

Эта команда создает несколько файлов в каталоге, включая тот, который называется Program.cs, где вы пишете большую часть вашего кода.

Держите окно командной строки открытым, так как вы будете продолжать использовать его на протяжении всего руководства.

Затем добавьте две зависимости в проект, необходимые для работы с Azure Digital Twins. Первая зависимость — это пакет Azure Digital Twins SDK для .NET. Вторая зависимость предоставляет инструменты для проверки подлинности в Azure.

dotnet add package Azure.DigitalTwins.Core
dotnet add package Azure.Identity

Начало создания кода проекта

В этом разделе вы начнете писать код для нового проекта приложения для работы с Azure Digital Twins. Действия включают:

аутентификация в сервисе
Загрузка модели
выявления ошибок;
Создание цифровых двойников
Создание связей
Запросы к цифровым двойникам.

В конце руководства есть раздел, в котором приведен полный код. Вы можете использовать этот раздел в качестве справки для проверки своей программы по мере работы над ней.

Для начала откройте файл Program.cs в любом редакторе кода. Вы увидите минимальный шаблон кода, который выглядит примерно так:

В первую очередь добавьте несколько строк using в верхней части кода, чтобы включить необходимые зависимости.

using Azure.DigitalTwins.Core;
using Azure.Identity;

Затем добавьте код в этот файл, чтобы заполнить некоторые функциональные возможности.

Проверка подлинности в службе

Первое, что необходимо сделать для приложения, — проверка подлинности в службе Azure Digital Twins. Затем можно создать класс клиента службы для доступа к функциям пакета SDK.

Для аутентификации требуется имя хоста экземпляра Azure Digital Twins.

В Program.cs вставьте следующий код под строкой печати "Hello, World!" в методе Main. Установите значение adtInstanceUrl как имя узла вашей экземпляра Azure Digital Twins.

string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-hostName>"; 

var credential = new DefaultAzureCredential();
var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
Console.WriteLine($"Service client created – ready to go");

Сохраните файл.

В командном окне запустите этот код с помощью следующей команды:

dotnet run

Эта команда восстанавливает зависимости при первом запуске, а затем выполняет программу.

Если ошибка не возникает, программа выводит сообщение "Клиент службы создан - готов к переходу".
Так как в этом проекте еще нет обработки ошибок, при возникновении каких-либо проблем возникает исключение, возникающее в коде.

Примечание.

В настоящее время существует известная проблема, влияющая на DefaultAzureCredential класс оболочки, которая может привести к ошибке при проверке подлинности. Если вы столкнетесь с этой проблемой, можно попытаться инициализировать DefaultAzureCredential с помощью следующего необязательного параметра для ее устранения: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Дополнительные сведения об этой проблеме см. в статье об известных проблемах Azure Digital Twins.

Отправка модели

В Azure Digital Twins отсутствует встроенный словарь домена. Модели используются для определения типов элементов в среде, которые можно представить в Azure Digital Twins. Модели похожи на классы в объектно-ориентированных языках программирования. Они предоставляют определяемые пользователем шаблоны для цифровых двойников, экземпляры которых будут затем создаваться на основе этих шаблонов. Они написаны на языке, подобном JSON, который называется DTDL.

При создании решения Azure Digital Twins в первую очередь необходимо определить хотя бы одну модель в файле DTDL.

В каталоге, в котором вы создали проект, создайте новый файл .json с именем SampleModel.json. Вставьте в этот файл следующий текст:

{
  "@id": "dtmi:example:SampleModel;1",
  "@type": "Interface",
  "displayName": "SampleModel",
  "contents": [
    {
      "@type": "Relationship",
      "name": "contains"
    },
    {
      "@type": "Property",
      "name": "data",
      "schema": "string"
    }
  ],
  "@context": "dtmi:dtdl:context;3"
}

Совет

Если вы используете Visual Studio для этого руководства, вы можете выбрать только что созданный JSON-файл и задать свойство Copy to Output Directory в инспекторе свойств, чтобы скопировать, если новый или копировать всегда. Это значение свойства позволяет Visual Studio найти JSON-файл с путем по умолчанию при запуске программы с помощью F5 во время работы с этим руководством.

Совет

Вы можете использовать библиотеку DTDLParser, чтобы проверить документы модели и убедиться, что DTDL является допустимым. Дополнительные сведения об использовании этой библиотеки см. в разделе "Анализ и проверка моделей".

Затем добавьте дополнительный код в Program.cs, чтобы загрузить созданную модель в экземпляр Azure Digital Twins.

Сначала добавьте несколько инструкций using в начало файла:

using System.Threading.Tasks;
using System.IO;
using System.Collections.Generic;
using Azure;

Затем подготовьте использование асинхронных методов в пакете SDK службы C#, изменив сигнатуру метода Main, чтобы разрешить асинхронное выполнение.

static async Task Main(string[] args)
{

Примечание.

Использование async не является строго обязательным, так как пакет SDK также предоставляет синхронные версии всех вызовов. В этом руководстве отрабатывается использование async.

Далее идет первый фрагмент кода, который взаимодействует со службой Azure Digital Twins. Этот код загружает с диска созданный вами файл DTDL и отправляет его в ваш экземпляр службы Azure Digital Twins.

Вставьте следующий код под кодом проверки подлинности, который вы добавили ранее.

Console.WriteLine();
Console.WriteLine($"Upload a model");
string dtdl = File.ReadAllText("SampleModel.json");
var models = new List<string> { dtdl };
// Upload the model to the service
await client.CreateModelsAsync(models);

В командном окне запустите программу с помощью следующей команды:

dotnet run

"Загрузка модели" выводится в выводе, чтобы указать, что этот код был достигнут. Однако нет выходных данных, чтобы указать, выполнена ли отправка успешно.

Чтобы добавить инструкцию печати, показывающую все модели, успешно отправленные в экземпляр, добавьте следующий код сразу после предыдущего раздела:

// Read a list of models back from the service
AsyncPageable<DigitalTwinsModelData> modelDataList = client.GetModelsAsync();
await foreach (DigitalTwinsModelData md in modelDataList)
{
    Console.WriteLine($"Model: {md.Id}");
}

Прежде чем снова запустить программу для проверки этого нового кода, вспомните, что в последний раз, когда программа запускалась, вы уже отправили свою модель. Azure Digital Twins не позволяет отправлять одну и ту же модель дважды, поэтому при попытке повторной отправки той же модели программа должна вызвать исключение.

Учитывая эту информацию, запустите программу еще раз с помощью следующей команды в своем командном окне:

dotnet run

Программа должна выдать исключение. При попытке отправить модель, которая уже отправлена, служба возвращает ошибку "неправильный запрос" через REST API. В результате пакет SDK клиента Azure Digital Twins создает исключение для каждого кода возврата службы, отличного от успешного выполнения.

В следующем разделе говорится об исключениях, подобных этому, и о том, как обрабатывать их в вашем коде.

Обработка ошибок

Чтобы предотвратить сбой программы, можно добавить код исключения вокруг кода отправки модели. Заключите существующий клиентский вызов await client.CreateModelsAsync(typeList) в обработчик try/catch, например так:

try
{
    await client.CreateModelsAsync(models);
    Console.WriteLine("Models uploaded to the instance:");
}
catch (RequestFailedException e)
{
    Console.WriteLine($"Upload model error: {e.Status}: {e.Message}");
}

Снова запустите программу с dotnet run в командном окне. Вы увидите, что получите дополнительные сведения о проблеме загрузки модели, включая код ошибки, в котором указано ModelIdAlreadyExists.

С этого момента учебник упаковывает все вызовы методов службы в обработчики try/catch.

Создание цифровых двойников

После отправки модели в Azure Digital Twins можно использовать это определение модели для создания цифровых двойников. Цифровые двойники являются экземплярами модели и представляют сущности в вашей бизнес-среде — такие как датчики на ферме, комнаты в здании или фары автомобиля. В этом разделе создается несколько цифровых двойников на основе модели, которую вы отправили ранее.

Чтобы создать и инициализировать три цифровых двойника на основе этой модели, добавьте следующий код в конец Main метода.

var twinData = new BasicDigitalTwin();
twinData.Metadata.ModelId = "dtmi:example:SampleModel;1";
twinData.Contents.Add("data", $"Hello World!");

string prefix = "sampleTwin-";
for (int i = 0; i < 3; i++)
{
    try
    {
        twinData.Id = $"{prefix}{i}";
        await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinData.Id, twinData);
        Console.WriteLine($"Created twin: {twinData.Id}");
    }
    catch(RequestFailedException e)
    {
        Console.WriteLine($"Create twin error: {e.Status}: {e.Message}");
    }
}

В командном окне запустите программу с помощью команды dotnet run. В выходных данных найдите сообщения о том, что sampleTwin-0, sampleTwin-1 и sampleTwin-2 созданы.

Затем снова выполните программу.

Обратите внимание, что при повторном создании двойников ошибки не возникают, даже если двойники уже существуют после первого запуска. В отличие от создания модели, создание двойника — это вызов PUT с семантикой upsert на уровне REST. Использование такого вызова REST означает, что если двойник уже существует, попытка создать один и тот же двойник снова просто заменяет исходный двойник. Сообщение об ошибке при этом не выводится.

Создание отношений

Затем можно создать связи между созданными двойниками, чтобы подключить их к графу двойников. Графы двойников используются для представления всей вашей среды.

Добавьте новый статический метод в класс Program, под методом Main (в итоге в коде будет два метода).

public async static Task CreateRelationshipAsync(DigitalTwinsClient client, string srcId, string targetId)
{
    var relationship = new BasicRelationship
    {
        TargetId = targetId,
        Name = "contains"
    };

    try
    {
        string relId = $"{srcId}-contains->{targetId}";
        await client.CreateOrReplaceRelationshipAsync(srcId, relId, relationship);
        Console.WriteLine("Created relationship successfully");
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"Create relationship error: {e.Status}: {e.Message}");
    }
}

Затем добавьте следующий код в конец метода Main, чтобы вызвать метод CreateRelationship и использовать только что написанный код:

// Connect the twins with relationships
await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-1");
await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-2");

В командном окне запустите программу с помощью команды dotnet run. В выходных данных найдите сведения об успешном создании двух связей.

Azure Digital Twins не позволяет создавать связь, если другая связь с тем же идентификатором уже существует. В результате вы увидите исключения при создании связей, если программа запускается несколько раз. Этот код перехватывает исключения и игнорирует их.

Список связей

Следующий код, который вы добавите, позволяет просмотреть список созданных связей.

Добавьте в класс Program следующий новый метод.

public async static Task ListRelationshipsAsync(DigitalTwinsClient client, string srcId)
{
    try
    {
        AsyncPageable<BasicRelationship> results = client.GetRelationshipsAsync<BasicRelationship>(srcId);
        Console.WriteLine($"Twin {srcId} is connected to:");
        await foreach (BasicRelationship rel in results)
        {
            Console.WriteLine($" -{rel.Name}->{rel.TargetId}");
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"Relationship retrieval error: {e.Status}: {e.Message}");
    }
}

Затем добавьте следующий код в конец метода Main для вызова кода ListRelationships:

//List the relationships
await ListRelationshipsAsync(client, "sampleTwin-0");

В командном окне запустите программу с помощью команды dotnet run. Вы увидите список всех созданных вами связей в выводе, который выглядит следующим образом:

Запрашивание цифровых двойников

Главной особенностью Azure Digital Twins является возможность просто и эффективно запрашивать граф двойников, чтобы получать ответы о вашей среде.

В последнем разделе кода, который вы добавите в этом учебнике, выполняется запрос к экземпляру Azure Digital Twins. Запрос, используемый в этом примере, возвращает все цифровые двойники в экземпляре.

Добавьте этот оператор using, чтобы обеспечить использование класса JsonSerializer для представления сведений о цифровом двойнике:

using System.Text.Json;

Затем добавьте следующий код в конец метода Main:

// Run a query for all twins
string query = "SELECT * FROM digitaltwins";
AsyncPageable<BasicDigitalTwin> queryResult = client.QueryAsync<BasicDigitalTwin>(query);

await foreach (BasicDigitalTwin twin in queryResult)
{
    Console.WriteLine(JsonSerializer.Serialize(twin));
    Console.WriteLine("---------------");
}

В командном окне запустите программу с помощью команды dotnet run. В выходных данных вы должны увидеть все цифровые двойники в этом экземпляре.

Примечание.

После внесения изменений в данные в графе может возникнуть задержка до 10 секунд, прежде чем изменения будут отражены в запросах.

API DigitalTwins отражает изменения немедленно, поэтому, если вам нужен мгновенный ответ, используйте запрос API (DigitalTwins GetById) или вызов пакета SDK (GetDigitalTwin) для получения данных двойника вместо запроса.

Полный пример кода

На этом этапе у вас есть готовое клиентское приложение, которое может выполнять базовые действия в Azure Digital Twins. Для справки в следующем примере приводится полный код программы в Program.cs:

using System;
// <Azure_Digital_Twins_dependencies>
using Azure.DigitalTwins.Core;
using Azure.Identity;
// </Azure_Digital_Twins_dependencies>
// <Model_dependencies>
using System.Threading.Tasks;
using System.IO;
using System.Collections.Generic;
using Azure;
// </Model_dependencies>
// <Query_dependencies>
using System.Text.Json;
// </Query_dependencies>

namespace DigitalTwins_Samples
{
    class DigitalTwinsClientAppSample
    {
        // <Async_signature>
        static async Task Main(string[] args)
        {
        // </Async_signature>
            Console.WriteLine("Hello World!");
            // <Authentication_code>
            string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-hostName>"; 
            
            var credential = new DefaultAzureCredential();
            var client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
            Console.WriteLine($"Service client created – ready to go");
            // </Authentication_code>

            // <Model_code>
            Console.WriteLine();
            Console.WriteLine("Upload a model");
            string dtdl = File.ReadAllText("SampleModel.json");
            var models = new List<string> { dtdl };

            // Upload the model to the service
            // <Model_try_catch>
            try
            {
                await client.CreateModelsAsync(models);
                Console.WriteLine("Models uploaded to the instance:");
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine($"Upload model error: {e.Status}: {e.Message}");
            }
            // </Model_try_catch>

            // <Print_model>
            // Read a list of models back from the service
            AsyncPageable<DigitalTwinsModelData> modelDataList = client.GetModelsAsync();
            await foreach (DigitalTwinsModelData md in modelDataList)
            {
                Console.WriteLine($"Model: {md.Id}");
            }
            // </Print_model>
            // </Model_code>

            // <Initialize_twins>
            var twinData = new BasicDigitalTwin();
            twinData.Metadata.ModelId = "dtmi:example:SampleModel;1";
            twinData.Contents.Add("data", $"Hello World!");
            
            string prefix = "sampleTwin-";
            for (int i = 0; i < 3; i++)
            {
                try
                {
                    twinData.Id = $"{prefix}{i}";
                    await client.CreateOrReplaceDigitalTwinAsync<BasicDigitalTwin>(twinData.Id, twinData);
                    Console.WriteLine($"Created twin: {twinData.Id}");
                }
                catch(RequestFailedException e)
                {
                    Console.WriteLine($"Create twin error: {e.Status}: {e.Message}");
                }
            }
            // </Initialize_twins>

            // <Use_create_relationship>
            // Connect the twins with relationships
            await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-1");
            await CreateRelationshipAsync(client, "sampleTwin-0", "sampleTwin-2");
            // </Use_create_relationship>

            // <Use_list_relationships>
            //List the relationships
            await ListRelationshipsAsync(client, "sampleTwin-0");
            // </Use_list_relationships>

            // <Query_twins>
            // Run a query for all twins
            string query = "SELECT * FROM digitaltwins";
            AsyncPageable<BasicDigitalTwin> queryResult = client.QueryAsync<BasicDigitalTwin>(query);
            
            await foreach (BasicDigitalTwin twin in queryResult)
            {
                Console.WriteLine(JsonSerializer.Serialize(twin));
                Console.WriteLine("---------------");
            }
            // </Query_twins>
        }

        // <Create_relationship>
        public async static Task CreateRelationshipAsync(DigitalTwinsClient client, string srcId, string targetId)
        {
            var relationship = new BasicRelationship
            {
                TargetId = targetId,
                Name = "contains"
            };
        
            try
            {
                string relId = $"{srcId}-contains->{targetId}";
                await client.CreateOrReplaceRelationshipAsync(srcId, relId, relationship);
                Console.WriteLine("Created relationship successfully");
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine($"Create relationship error: {e.Status}: {e.Message}");
            }
        }
        // </Create_relationship>
        
        // <List_relationships>
        public async static Task ListRelationshipsAsync(DigitalTwinsClient client, string srcId)
        {
            try
            {
                AsyncPageable<BasicRelationship> results = client.GetRelationshipsAsync<BasicRelationship>(srcId);
                Console.WriteLine($"Twin {srcId} is connected to:");
                await foreach (BasicRelationship rel in results)
                {
                    Console.WriteLine($" -{rel.Name}->{rel.TargetId}");
                }
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine($"Relationship retrieval error: {e.Status}: {e.Message}");
            }
        }
        // </List_relationships>
    }
}

Очистка ресурсов

По завершении работы с этим руководством вы можете выбрать ресурсы, которые нужно удалить, в зависимости от планируемых действий.

Если вы планируете перейти к следующему руководству, экземпляр из этого руководства можно использовать в следующем. Вы можете оставить настроенные здесь ресурсы Azure Digital Twins и пропустить оставшуюся часть этого раздела.

Если вы хотите продолжить использование экземпляра Azure Digital Twins из этой статьи, но хотите очистить все его модели, двойники и связи, выполните следующую CLI-команду az dt job deletion:
```
az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -y
```
Если вы хотите удалить только некоторые из этих элементов, можно использовать команды az dt twin relationship delete, az dt twin delete и az dt model delete, чтобы выборочно удалить только нужные элементы.

Если вам не нужен какой-либо из ресурсов, созданных в этом руководстве, можно удалить экземпляр Azure Digital Twins и все остальные ресурсы из этой статьи с помощью команды az group delete CLI. При этом будут удалены все ресурсы Azure в группе ресурсов, а также сама группа.

Внимание

Удаление группы ресурсов — процесс необратимый. Группа ресурсов и все содержащиеся в ней ресурсы удаляются без возможности восстановления. Будьте внимательны, чтобы случайно не удалить не ту группу ресурсов или не те ресурсы.

Откройте Azure Cloud Shell или локальное окно CLI и выполните следующую команду, чтобы удалить группу ресурсов и все, что она содержит.
```
az group delete --name <your-resource-group>
```

Вы также можете удалить папку проекта с локального компьютера.

Следующие шаги

В этом руководстве вы с нуля создали консольное клиентское приложение консоли .NET. Вы написали код для этого клиентского приложения, чтобы выполнять базовые действия в экземпляре Azure Digital Twins.

Перейдите к следующему учебнику, чтобы изучить действия, которые можно выполнять с помощью такого примера клиентского приложения:

Изучение основных сведений с примером клиентского приложения

Поделиться через

Руководство. Написание кода с помощью пакета SDK для Azure Digital Twins

Предварительные условия

Подготовьте экземпляр Azure Digital Twins

Настройка локальных учетных данных Azure

Настройка проекта

Начало создания кода проекта

Проверка подлинности в службе

Отправка модели

Обработка ошибок

Создание цифровых двойников

Создание отношений

Список связей

Запрашивание цифровых двойников

Полный пример кода

Очистка ресурсов

Следующие шаги

Обратная связь

Дополнительные ресурсы