Oktatóanyag: Kódolás az Azure Digital Twins SDK-val

Az Azure Digital Twins szolgáltatással dolgozó fejlesztők gyakran írnak ügyfélalkalmazásokat az Azure Digital Twins szolgáltatás példányával való interakcióhoz. Ez a fejlesztőközpontú oktatóanyag bemutatja az Azure Digital Twins szolgáltatással való programozást az Azure Digital Twins SDK for .NET (C#) használatával. Lépésről lépésre végigvezeti egy C#-konzol ügyfélalkalmazásának írásán, az alapoktól kezdve.

Előfeltételek

Ez az Azure Digital Twins-oktatóanyag a parancssort használja a beállításhoz és a projektmunkához. Így bármilyen kódszerkesztőt használhat a gyakorlatok végigjárásához.

Mit kell kezdenie:

• Bármely kódszerkesztő
• .NET Core 3.1 a fejlesztői gépen. A .NET Core SDK ezen verzióját több platformra is letöltheti a .NET Core 3.1 letöltéséből.

Azure Digital Twins-példány előkészítése

Az Azure Digital Twins jelen cikkben való használatához azure Digital Twins-példányra és a használatához szükséges engedélyekre van szüksége. Ha már beállított egy Azure Digital Twins-példányt, használhatja ezt a példányt, és ugorjon a következő szakaszra. Ellenkező esetben kövesse a(z) Példány és hitelesítés beállítása utasításait. Az utasítások olyan információkat tartalmaznak, amelyek segítenek ellenőrizni, hogy sikeresen végrehajtotta-e az egyes lépéseket.

A példány beállítása után jegyezze fel a példány állomásnevét. Az Azure Portalon találhatja meg a gazdagép nevét.

Helyi Azure-hitelesítő adatok beállítása

Ez a minta a DefaultAzureCredential (a Azure.Identity kódtár része) használatával hitelesíti az Azure Digital Twins-példányt, amikor a mintát a helyi gépen futtatja. DefaultAzureCredential a számos hitelesítési lehetőség egyike. Az ügyfélalkalmazások Azure Digital Twins-hitelesítésének különböző módjairól az alkalmazáshitelesítési kód írása című témakörben talál további információt.

A DefaultAzureCredentialminta hitelesítő adatokat keres a helyi környezetben, például egy Azure-bejelentkezést egy helyi Azure CLI-ben vagy a Visual Studióban vagy a Visual Studio Code-ban. Ezért helyileg kell bejelentkeznie az Azure-ba ezen mechanizmusok egyikével a minta hitelesítő adatainak beállításához.

Ha a Visual Studio vagy a Visual Studio Code használatával futtat kódmintákat, győződjön meg arról , hogy ugyanazokkal az Azure-hitelesítő adatokkal jelentkezett be a szerkesztőbe , amelyeket az Azure Digital Twins-példány eléréséhez használni szeretne. Ha helyi CLI-ablakot használ, futtassa a parancsot az az login Azure-fiókba való bejelentkezéshez. Miután bejelentkezett, a kódminta automatikusan hitelesíti Önt a futtatáskor.

Projekt beállítása

Ha készen áll az Azure Digital Twins-példány használatára, kezdje el az ügyfélalkalmazás-projekt beállítását.

Nyisson meg egy konzolablakot a számítógépen, és hozzon létre egy üres projektkönyvtárat, ahol az oktatóanyag során tárolni szeretné a munkáját. Nevezze el a kívánt könyvtárat (például DigitalTwinsCodeTutorial).

Lépjen az új könyvtárba.

A projektkönyvtárban hozzon létre egy üres .NET-konzolalkalmazás-projektet. A parancsablakban a következő parancs futtatásával létrehozhat egy minimális C#-projektet a konzolhoz:

dotnet new console

Ez a parancs több fájlt hoz létre a címtárban, köztük egy Program.cs nevű fájlt, ahová a kód nagy részét írja.

Tartsa nyitva a parancsablakot, ahogy az oktatóanyag során is használni fogja.

Ezután adjon hozzá két függőséget a projekthez, amelyek szükségesek az Azure Digital Twins használatához. Az első függőség a Azure Digital Twins SDK csomagja a .NET-hez. A második függőség eszközöket biztosít az Azure-beli hitelesítéshez.

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

A projektkód használatának első lépései

Ebben a szakaszban elkezdi írni az új alkalmazásprojekt kódját az Azure Digital Twins használatához. Az érintett műveletek a következők:

• Hitelesítés a szolgáltatással szemben
• Modell feltöltése
• Hibák észlelése
• Digitális ikerpéldányok létrehozása
• Kapcsolatok létrehozása
• Digitális ikrek lekérdezése

Az oktatóanyag végén található egy szakasz, amely a teljes kódot mutatja. Ezt a szakaszt hivatkozásként használhatja a program útközbeni ellenőrzéséhez.

Először nyissa meg a fájlt Program.cs bármely kódszerkesztőben. A következőhöz hasonló minimális kódsablon jelenik meg:

Először adjon hozzá néhány using sort a kód tetején a szükséges függőségek lekéréséhez.

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

Ezután kódot ad hozzá ehhez a fájlhoz, hogy kitöltsön néhány funkciót.

Hitelesítés a szolgáltatáson

Az alkalmazásnak először is hitelesítenie kell magát az Azure Digital Twins szolgáltatással. Ezután létrehozhat egy szolgáltatásügyfél-osztályt az SDK-függvények eléréséhez.

A hitelesítéshez szüksége van az Azure Digital Twins-példány gazdagépnevére.

A Program.cs illessze be a következő kódot a "Hello, World!" nyomtatási sor alá a Main metódusban. Állítsa be a(z) adtInstanceUrl értékét az Azure Digital Twins példányának gazdagépnevére.

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

Mentse a fájlt.

A parancsablakban futtassa a kódot a következő paranccsal:

dotnet run

Ez a parancs először visszaállítja a függőségeket, majd végrehajtja a programot.

• Ha nem történik hiba, a program a következőt nyomtatja: "Service client created - ready to go".
• Mivel ebben a projektben még nincs hibakezelés, ha bármilyen probléma merül fel, a kód kivételt jelez.

Modell feltöltése

Az Azure Digital Twins nem rendelkezik belső tartományi szókincsekkel. Modellekkel definiálhatja a környezetében az Azure Digital Twinsben képviselhető elemek típusait. A modellek hasonlóak az objektumorientált programozási nyelvek osztályaihoz; felhasználó által definiált sablonokat biztosítanak a digitális ikerpéldányokhoz , amelyeket később követhetnek és példányosíthatnak. Ezek egy JSON-szerű, Digital Twins Definition Language (DTDL) nevű nyelven vannak megírva.

Az Azure Digital Twins-megoldás létrehozásának első lépése egy DTDL-fájl legalább egy modelljének meghatározása.

Hozzon létre egy új .json SampleModel.json nevű fájlt abban a könyvtárban, amelyben létrehozta a projektet. Illessze be a következő fájltörzset:

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

Ezután adjon hozzá néhány további kódot a Program.cs a létrehozott modell Azure Digital Twins-példányba való feltöltéséhez.

Először adjon hozzá néhány using utasítást a fájl elejéhez:

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

Ezután készüljön fel az aszinkron metódusok használatára a C# szolgáltatás SDK-ban a metódusaláírás módosításával, hogy lehetővé tegye az Main aszinkron végrehajtást.

static async Task Main(string[] args)
{

Ezután következik az Első kódrészlet, amely az Azure Digital Twins szolgáltatással kommunikál. Ez a kód betölti a lemezről létrehozott DTDL-fájlt, majd feltölti azt az Azure Digital Twins szolgáltatáspéldányba.

Illessze be a következő kódot a korábban hozzáadott engedélyezési kód alá.

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

A parancsablakban futtassa a programot a következő paranccsal:

dotnet run

A kimenetben a "Modell feltöltése" felirat jelenik meg, amely jelzi, hogy a kód el lett érve. Azonban még nincs kimenet, amely jelezze, hogy a feltöltés sikeres volt-e.

Ha a példányra sikeresen feltöltött modelleket tartalmazó nyomtatási utasítást szeretne hozzáadni, adja hozzá a következő kódot közvetlenül az előző szakasz után:

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

Mielőtt újra futtatná a programot az új kód teszteléséhez, ne feledje, hogy a program utolsó futtatásakor már feltöltötte a modellt. Az Azure Digital Twins nem teszi lehetővé, hogy kétszer töltse fel ugyanazt a modellt, ezért ha újra megpróbálja feltölteni ugyanazt a modellt, a program kivételt fog kivenni.

Ezeket az információkat szem előtt tartva futtassa újra a programot a parancsablakban található paranccsal:

dotnet run

A programnak kivételt kell dobnia. Amikor egy már feltöltött modellt próbál feltölteni, a szolgáltatás "hibás kérést" ad vissza a REST API-val. Ennek eredményeképpen az Azure Digital Twins ügyféloldali SDK kivételt vet ki minden olyan szolgáltatás visszaküldési kódjára, amely nem sikeres.

A következő szakasz az ehhez hasonló kivételekről és azok kódban való kezeléséről szól.

Fogási hibák

Ha meg szeretné tartani a program összeomlását, hozzáadhat kivételkódot a modellfeltöltési kódhoz. Csomagolja be a meglévő ügyfélhívást await client.CreateModelsAsync(typeList) egy try/catch kezelőbe, a következőképpen:

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

Futtassa újra a programot dotnet run a parancsablakban. Láthatja, hogy további részleteket kap a modell feltöltésével kapcsolatos problémáról, beleértve egy hibakódot is, amely azt jelzi, hogy ModelIdAlreadyExists.

Ettől a ponttól kezdve az oktatóanyag a szolgáltatás metódusainak összes hívását try/catch kezelőkbe foglalja.

Digitális ikerpéldányok létrehozása

Most, hogy feltöltött egy modellt az Azure Digital Twinsbe, ezzel a modelldefinícióval digitális ikerpéldányokat hozhat létre. A digitális ikerpéldányok egy modell példányai, és az üzleti környezeten belüli entitásokat képviselik– ilyenek például a farm érzékelői, az épület helyiségei vagy az autó fényei. Ez a szakasz a korábban feltöltött modell alapján hoz létre néhány digitális ikerpéldányt.

Ha három digitális ikerpéldányt szeretne létrehozni és inicializálni a modell alapján, adja hozzá a következő kódot a Main metódus végéhez.

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

A parancsablakban futtassa a programot a következővel dotnet run: . A kimenetben keresse meg a sampleTwin-0, a sampleTwin-1 és a sampleTwin-2 által létrehozott nyomtatási üzeneteket.

Ezután futtassa újra a programot.

Figyelje meg, hogy az ikrek második létrehozásakor nem jelentkezik hiba, annak ellenére, hogy az ikrek már léteznek az első futtatás után. A modelllétrehozástól eltérően az ikerpéldány létrehozása egy PUT-hívás, amely rest szinten upsert szemantikával rendelkezik. Az ilyen típusú REST-hívás azt jelenti, hogy ha már létezik ikerpéldány, az azonos ikerpéldány ismételt létrehozására tett kísérlet csak az eredeti ikerpéldányt váltja fel. Nincs hiba.

Kapcsolatok létrehozása

Ezután kapcsolatokat hozhat létre a létrehozott ikerpéldányok között, hogy összekapcsolja őket egy ikergráfban. Az ikergráfok a teljes környezet ábrázolására szolgálnak.

Adjon hozzá egy új statikus metódust az Program osztályhoz a Main metódus alatt (a kódnak most két metódusa van):

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

Ezután adja hozzá a következő kódot a Main metódus végére, hogy meghívja a metódust CreateRelationship , és használja az imént írt kódot:

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

A parancsablakban futtassa a programot a következővel dotnet run: . A kimenetben keresse meg azokat a nyomtatási utasításokat, amelyek szerint a két kapcsolat sikeresen létrejött.

Az Azure Digital Twins nem teszi lehetővé, hogy kapcsolatot hozzon létre, ha már létezik egy másik, azonos azonosítóval rendelkező kapcsolat. Ennek eredményeképpen kivételek láthatók a kapcsolat létrehozásakor, ha többször futtatja a programot. Ez a kód elkapja a kivételeket, és figyelmen kívül hagyja őket.

Kapcsolatok listázása

A következő hozzáadandó kód lehetővé teszi a létrehozott kapcsolatok listájának megtekintését.

Adja hozzá a következő új metódust a Program osztályhoz:

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

Ezután adja hozzá a következő kódot a metódus végére a Main kód meghívásához ListRelationships :

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

A parancsablakban futtassa a programot a következővel dotnet run: . A kimeneti utasításban létrehozott összes kapcsolat listáját a következőképpen kell látnia:

Digitális ikerpéldányok lekérdezése

Az Azure Digital Twins fő funkciója az ikergráf egyszerű és hatékony lekérdezése a környezettel kapcsolatos kérdések megválaszolásához.

Az oktatóanyagban hozzáadandó kód utolsó szakasza lekérdezést futtat az Azure Digital Twins-példányon. Az ebben a példában használt lekérdezés a példány összes digitális ikerpéldányát visszaadja.

Adja hozzá ezt az using utasítást, amely lehetővé teszi a JsonSerializer osztály használatát a digitális ikerinformáció bemutatásához.

using System.Text.Json;

Ezután adja hozzá a következő kódot a Main metódus végéhez:

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

A parancsablakban futtassa a programot a következővel dotnet run: . Ebben a példányban az összes digitális ikerpéldánynak meg kell jelennie a kimenetben.

Példa a teljes kódra

Az oktatóanyag ezen szakaszában egy teljes ügyfélalkalmazással rendelkezik, amely alapvető műveleteket hajthat végre az Azure Digital Twins elleni. Az alábbi példa a program teljes kódját sorolja fel a 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>
    }
}

Az erőforrások megtisztítása

Az oktatóanyag elvégzése után kiválaszthatja, hogy mely erőforrásokat szeretné eltávolítani a következő lépéstől függően.

• Ha a következő oktatóanyag folytatását tervezi, az oktatóanyagban használt példány újra felhasználható a következőben. Megtarthatja az itt beállított Azure Digital Twins-erőforrásokat, és kihagyhatja a szakasz többi részét.

• Ha továbbra is az Azure Digital Twins-példányt szeretné használni ebből a cikkből, de törli az összes modellt, ikerpéldányt és kapcsolatot, futtassa az alábbi az dt feladattörlési parancssori parancsot:

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

  Ha csak néhány elemet szeretne törölni, az az dt twin relationship delete, az dt twin delete és az dt model delete parancsokkal csak az eltávolítani kívánt elemeket törölheti szelektíven.

• Ha nincs szüksége az oktatóanyagban létrehozott erőforrások egyikére sem, törölheti az Azure Digital Twins-példányt és az összes többi erőforrást ebből a cikkből az az group delete CLI paranccsal. Ez törli az erőforráscsoport összes Azure-erőforrását, valamint magát az erőforráscsoportot is.

  Fontos

  Az erőforráscsoport törlése nem vonható vissza. Az erőforráscsoport és a benne foglalt erőforrások véglegesen törlődnek. Figyeljen, nehogy véletlenül rossz erőforráscsoportot vagy erőforrásokat töröljön.

  Nyissa meg az Azure Cloud Shellt vagy egy helyi CLI-ablakot, és futtassa a következő parancsot az erőforráscsoport és a benne található elemek törléséhez.

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

Előfordulhat, hogy törölni szeretné a projektmappát a helyi gépről.

Következő lépések

Ebben az oktatóanyagban létrehozott egy .NET-konzol ügyfélalkalmazást az alapoktól. Az ügyfélalkalmazás kódját egy Azure Digital Twins-példány alapműveleteinek végrehajtásához írta.

Folytassa a következő oktatóanyaggal az ilyen ügyfélalkalmazásokkal elvégezhető műveletek megismeréséhez: