Kurz: Kódování pomocí sady Azure Digital Twins SDK

Vývojáři, kteří pracují se službou Azure Digital Twins, často zapisují klientské aplikace pro interakci s jejich instancí služby Azure Digital Twins. Tento kurz zaměřený na vývojáře poskytuje úvod do programování ve službě Azure Digital Twins pomocí sady Azure Digital Twins SDK pro .NET (C#). Provede vás podrobným zápisem klientské aplikace konzolové aplikace v jazyce C#, počínaje od začátku.

  • Nastavení projektu
  • Začínáme s kódem projektu
  • Kompletní ukázka kódu
  • Vyčištění prostředků
  • Další kroky

Požadavky

Tento kurz služby Azure Digital Twins používá příkazový řádek pro nastavení a práci na projektu. K procházení cvičení můžete použít libovolný editor kódu.

Co je potřeba začít:

  • Libovolný editor kódu
  • .NET Core 3.1 na vývojovém počítači Tuto verzi sady .NET Core SDK pro více platforem si můžete stáhnout z webu Download .NET Core 3.1.

Příprava instance Služby Azure Digital Twins

Pokud chcete pracovat se službou Azure Digital Twins v tomto článku, budete potřebovat instanci služby Azure Digital Twins a požadovaná oprávnění k jeho použití. Pokud už máte nastavenou instanci Služby Azure Digital Twins, můžete tuto instanci použít a přeskočit k další části. V opačném případě postupujte podle pokynů v části Nastavení instance a ověřování. Pokyny obsahují informace, které vám pomůžou ověřit, že jste každý krok úspěšně dokončili.

Po nastavení instance si poznamenejte název hostitele instance. Název hostitele najdete na webu Azure Portal.

Nastavení místních přihlašovacích údajů Azure

Tato ukázka používá defaultAzureCredential (součást Azure.Identity knihovny) k ověřování uživatelů s instancí Služby Azure Digital Twins, když ji spustíte na místním počítači. Další informace o různých způsobech ověřování klientské aplikace pomocí služby Azure Digital Twins najdete v tématu Psaní ověřovacího kódu aplikace.

Pomocí DefaultAzureCredentialtéto ukázky vyhledáte přihlašovací údaje ve vašem místním prostředí, jako je přihlášení k Azure v místním Azure CLI nebo v sadě Visual Studio nebo Visual Studio Code. Z tohoto důvodu byste se měli k Azure přihlásit místně prostřednictvím jednoho z těchto mechanismů, abyste pro ukázku nastavili přihlašovací údaje.

Pokud ke spouštění ukázek kódu používáte Visual Studio nebo Visual Studio Code, ujistěte se, že jste k ho editoru přihlášeni pomocí stejných přihlašovacích údajů Azure, které chcete použít pro přístup k vaší instanci Azure Digital Twins. Pokud používáte místní okno rozhraní příkazového řádku, spusťte az login příkaz pro přihlášení ke svému účtu Azure. Potom byste při spuštění ukázky kódu měli být automaticky ověřeni.

Nastavení projektu

Jakmile budete připraveni začít s instancí služby Azure Digital Twins, začněte nastavovat projekt klientské aplikace.

Otevřete okno konzoly na počítači a vytvořte prázdný adresář projektu, do kterého chcete uložit práci během tohoto kurzu. Pojmenujte adresář podle potřeby (například DigitalTwinsCodeTutorial).

Přejděte do nového adresáře.

V adresáři projektu vytvořte prázdný projekt konzolové aplikace .NET. V příkazovém okně můžete spuštěním následujícího příkazu vytvořit minimální projekt jazyka C#pro konzolu:

dotnet new console

Tento příkaz vytvoří v adresáři několik souborů, včetně souboru s názvem Program.cs , kde napíšete většinu kódu.

Nechte příkazové okno otevřené, protože ho budete dál používat v průběhu kurzu.

Dále do projektu přidejte dvě závislosti, které budou potřeba pro práci se službou Azure Digital Twins. První je balíček sady Azure Digital Twins SDK pro .NET, druhý poskytuje nástroje, které vám pomůžou s ověřováním v Azure.

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

Začínáme s kódem projektu

V této části začnete psát kód nového projektu aplikace pro práci s Azure Digital Twins. Mezi zahrnuté akce patří:

  • Ověřování ve službě
  • Nahrání modelu
  • Zachytávání chyb
  • Vytváření digitálních dvojčat
  • Vytváření relací
  • Dotazování digitálních dvojčat

Na konci kurzu je také část s úplným kódem. Tuto část můžete použít jako referenci ke kontrole programu při přechodu.

Začněte tím, že soubor Program.cs otevřete v libovolném editoru kódu. Zobrazí se minimální šablona kódu, která vypadá nějak takto:

Screenshot of a snippet of sample code in a code editor.

Nejprve přidejte několik using řádků v horní části kódu, abyste mohli vyžádat potřebné závislosti.

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

Dále do tohoto souboru přidáte kód, který vyplní některé funkce.

Ověření vůči službě

První věc, kterou vaše aplikace bude muset udělat, je ověření ve službě Azure Digital Twins. Potom můžete vytvořit třídu klienta služby pro přístup k funkcím sady SDK.

K ověření potřebujete název hostitele vaší instance Azure Digital Twins.

Do souboru Program.cs vložte následující kód pod řádek "Hello, World!" print line v Main metodě. Nastavte hodnotu adtInstanceUrl na název hostitele instance služby 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");

Uložte soubor.

V příkazovém okně spusťte kód pomocí tohoto příkazu:

dotnet run

Tento příkaz obnoví závislosti při prvním spuštění a pak program spustí.

  • Pokud nedojde k žádné chybě, program vytiskne: "Service client created - ready to go".
  • Vzhledem k tomu, že v tomto projektu ještě není žádné zpracování chyb, v případě jakýchkoli problémů se zobrazí výjimka vyvolaná kódem.

Poznámka:

V současné době existuje známý problém ovlivňující DefaultAzureCredential třídu obálky, která může způsobit chybu při ověřování. Pokud narazíte na tento problém, můžete zkusit vytvořit instanci DefaultAzureCredential s následujícím volitelným parametrem a vyřešit ho: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Další informace o tomto problému najdete v tématu Známé problémy služby Azure Digital Twins.

Nahrání modelu

Azure Digital Twins nemá žádný vnitřní slovník domény. Typy prvků ve vašem prostředí, které můžete reprezentovat ve službě Azure Digital Twins, jsou definované pomocí modelů. Modely se podobají třídám v objektově orientovaných programovacích jazycích. Poskytují uživatelsky definované šablony pro digitální dvojčata , které budou později sledovat a vytvářet instance. Jsou napsané v jazyce podobném formátu JSON s názvem DTDL (Digital Twins Definition Language).

Prvním krokem při vytváření řešení Azure Digital Twins je definování alespoň jednoho modelu v souboru DTDL.

V adresáři, ve kterém jste vytvořili projekt, vytvořte nový soubor .json s názvem SampleModel.json. Vložte následující text souboru:

{
  "@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"
}

Tip

Pokud pro tento kurz používáte Visual Studio, můžete vybrat nově vytvořený soubor JSON a nastavit vlastnost Kopírovat do výstupního adresáře v inspektoru vlastností na kopírovat, pokud je novější nebo kopírovat vždy. Visual Studio tak umožní najít soubor JSON s výchozí cestou při spuštění programu pomocí klávesy F5 ve zbývající části kurzu.

Tip

Pomocí knihovny DTDLParser můžete zkontrolovat dokumenty modelu a ujistit se, že je DTDL platný. Další informace o použití této knihovny najdete v tématu Parsování a ověřování modelů.

Dále do souboru Program.cs přidejte další kód, který nahraje model, který jste vytvořili do instance služby Azure Digital Twins.

Nejprve do horní části souboru přidejte několik using příkazů:

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

Dále se připravte na použití asynchronních metod v sadě SDK služby C# změnou Main podpisu metody tak, aby umožňoval asynchronní spuštění.

static async Task Main(string[] args)
{

Poznámka:

Použití async není nezbytně nutné, protože sada SDK také poskytuje synchronní verze všech volání. V tomto kurzu se používá async.

Dále přichází první část kódu, která komunikuje se službou Azure Digital Twins. Tento kód načte soubor DTDL, který jste vytvořili z disku, a pak ho nahraje do instance služby Azure Digital Twins.

Do autorizačního kódu, který jste přidali dříve, vložte následující kód.

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);

V příkazovém okně spusťte program pomocí tohoto příkazu:

dotnet run

Ve výstupu se vytiskne "Nahrát model", což značí, že tento kód byl dosažen, ale zatím neexistuje žádný výstup, který by indikoval, jestli bylo nahrávání úspěšné.

Pokud chcete přidat příkaz tisku zobrazující všechny modely, které byly úspěšně odeslány do instance, přidejte následující kód hned za předchozí oddíl:

// 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}");
}

Než program znovu spustíte a otestujete tento nový kód, vzpomeňte si, že při posledním spuštění programu jste model už nahráli. Azure Digital Twins vám nedovolí nahrát stejný model dvakrát, takže pokud se pokusíte stejný model nahrát znovu, program by měl vyvolat výjimku.

S ohledem na tyto informace spusťte program znovu pomocí tohoto příkazu v příkazovém okně:

dotnet run

Program by měl vyvolat výjimku. Když se pokusíte nahrát model, který už byl nahraný, služba vrátí chybu chybný požadavek prostřednictvím rozhraní REST API. V důsledku toho klientská sada SDK služby Azure Digital Twins vyvolá výjimku pro každý kód, který vrací jinou službu než úspěch.

V další části se dozvíte o výjimkách, jako je tento, a o tom, jak je zpracovat v kódu.

Zachycení chyb

Pokud chcete zabránit chybovému ukončení programu, můžete do kódu pro nahrání modelu přidat kód výjimky. Zabalte stávající volání await client.CreateModelsAsync(typeList) klienta do obslužné rutiny try/catch, například takto:

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

Spusťte program znovu v dotnet run příkazovém okně. Uvidíte, že získáte další podrobnosti o problému s nahráním modelu, včetně kódu chyby, který ModelIdAlreadyExiststo hlásí .

Od tohoto okamžiku kurz zabalí všechna volání metod služby v obslužných rutinách try/catch.

Vytvoření digitálních dvojčat

Teď, když jste nahráli model do služby Azure Digital Twins, můžete pomocí této definice modelu vytvořit digitální dvojčata. Digitální dvojčata jsou instancemi modelu a představují entity ve vašem obchodním prostředí – například senzory ve farmě, místnosti v budově nebo světla v autě. Tato část vytvoří několik digitálních dvojčat na základě modelu, který jste nahráli dříve.

Na konec metody přidejte následující kód pro vytvoření a inicializaci tří digitálních Main dvojčat na základě tohoto modelu.

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}");
    }
}

V příkazovém okně spusťte program pomocí dotnet runpříkazu . Ve výstupu vyhledejte tiskové zprávy, které byly vytvořeny sampleTwin-0, sampleTwin-1 a sampleTwin-2.

Pak program spusťte znovu.

Všimněte si, že při druhém vytvoření dvojčat se nevyvolá žádná chyba, i když dvojčata již existují po prvním spuštění. Na rozdíl od vytvoření modelu je vytvoření dvojčete na úrovni REST volání PUT s sémantikou upsertu . Použití tohoto typu volání REST znamená, že pokud už dvojče existuje, pokus o vytvoření stejného dvojčete znovu nahradí původní dvojče. Není vyvolán žádná chyba.

Vytvoření vztahů

Dále můžete vytvořit vztahy mezi dvojčaty, která jste vytvořili, a propojit je s grafem dvojčete. Grafy dvojčat se používají k reprezentaci celého prostředí.

Přidejte novou statickou metodu Program do třídy pod metodu Main (kód teď má dvě metody):

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}");
    }
}

Dále na konec Main metody přidejte následující kód, který zavolá metodu CreateRelationship a použije kód, který jste právě napsali:

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

V příkazovém okně spusťte program pomocí dotnet runpříkazu . Ve výstupu vyhledejte příkazy tisku, které říkají, že se tyto dvě relace úspěšně vytvořily.

Azure Digital Twins vám nedovolí vytvořit relaci, pokud už existuje jiná relace se stejným ID, takže pokud program spustíte několikrát, zobrazí se výjimky při vytváření relací. Tento kód zachytí výjimky a ignoruje je.

Výpis relací

Další kód, který přidáte, vám umožní zobrazit seznam relací, které jste vytvořili.

Do třídy Program přidejte následující novou metodu:

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}");
    }
}

Pak na konec Main metody přidejte následující kód pro volání ListRelationships kódu:

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

V příkazovém okně spusťte program pomocí dotnet runpříkazu . Měl by se zobrazit seznam všech relací, které jste vytvořili ve výstupním příkazu, který vypadá takto:

Screenshot of a console showing the program output, which results in a message that lists the twin relationships.

Dotazování digitálních dvojčat

Hlavní funkcí služby Azure Digital Twins je možnost snadno a efektivně dotazovat graf dvojčete na otázky týkající se vašeho prostředí.

Poslední část kódu, kterou chcete přidat v tomto kurzu, spustí dotaz na instanci Služby Azure Digital Twins. Dotaz použitý v tomto příkladu vrátí všechna digitální dvojčata v instanci.

Přidáním tohoto using příkazu povolíte použití JsonSerializer třídy k prezentaci informací o digitálním dvojčeti:

using System.Text.Json;

Pak na konec Main metody přidejte následující kód:

// 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("---------------");
}

V příkazovém okně spusťte program pomocí dotnet runpříkazu . Ve výstupu by se měly zobrazit všechna digitální dvojčata v této instanci.

Poznámka:

Po provedení změny dat v grafu může docházet k latenci až 10 sekund, než se změny projeví v dotazech.

Rozhraní API DigitalTwins okamžitě odráží změny, takže pokud potřebujete okamžitou odpověď, použijte požadavek rozhraní API (DigitalTwins GetById) nebo volání sady SDK (GetDigitalTwin) k získání dat dvojčat místo dotazu.

Kompletní příklad kódu

V tomto okamžiku v kurzu máte úplnou klientskou aplikaci, která může provádět základní akce s Azure Digital Twins. Úplný kód programu v souboru Program.cs je uvedený níže:

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>
    }
}

Vyčištění prostředků

Po dokončení tohoto kurzu můžete v závislosti na tom, co chcete udělat dál, vybrat, které prostředky chcete odebrat.

  • Pokud chcete pokračovat k dalšímu kurzu, instance použitá v tomto kurzu se dá znovu použít v dalším kurzu. Prostředky služby Azure Digital Twins, které tady nastavíte, si můžete ponechat a zbytek této části přeskočit.
  • Pokud chcete dál používat instanci azure Digital Twins z tohoto článku, ale vymazejte všechny její modely, dvojčata a relace, spusťte následující příkaz az dt job deletion CLI:

    az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -y
    

    Pokud chcete odstranit jenom některé z těchto prvků, můžete k selektivnímu odstranění pouze prvků, které chcete odebrat, použít az dt twin relationship delete, az dt twin delete a az dt model delete.

  • Pokud nepotřebujete žádné prostředky, které jste vytvořili v tomto kurzu, můžete pomocí příkazu az group delete CLI odstranit instanci Azure Digital Twins a všechny ostatní prostředky z tohoto článku. Tím se odstraní všechny prostředky Azure ve skupině prostředků i samotná skupina prostředků.

    Důležité

    Odstranění skupiny prostředků je nevratné. Skupina prostředků i všechny prostředky v ní obsažené se trvale odstraní. Ujistěte se, že nechtěně neodstraníte nesprávnou skupinu prostředků nebo prostředky.

    Otevřete Azure Cloud Shell nebo místní okno rozhraní příkazového řádku a spuštěním následujícího příkazu odstraňte skupinu prostředků a vše, co obsahuje.

    az group delete --name <your-resource-group>
    

Můžete také odstranit složku projektu z místního počítače.

Další kroky

V tomto kurzu jste vytvořili zcela novou klientskou aplikaci konzoly .NET. Napsali jste kód pro tuto klientskou aplikaci, abyste provedli základní akce v instanci služby Azure Digital Twins.

Pokračujte k dalšímu kurzu a prozkoumejte, co můžete s takovou ukázkovou klientskou aplikací dělat: