Zelfstudie: Coderen met de Azure Digital Twins-API's

Ontwikkelaars die met Azure Digital Twins schrijven vaak clienttoepassingen voor interactie met hun exemplaar van de Azure Digital Twins service. Deze zelfstudie voor ontwikkelaars biedt een inleiding op het programmeren van de Azure Digital Twins-service, met behulp van de Azure Digital Twins-SDK voor .NET (C#). U wordt stap voor stap begeleid bij het schrijven van een C# console-client-app, vanaf het begin.

Vereisten

In Azure Digital Twins zelfstudie wordt de opdrachtregel gebruikt voor installatie- en projectwerk. U kunt dus elke code-editor gebruiken om de oefeningen te doorloopen.

U gaat als volgt aan de slag:

• Elk soort code-editor
• .NET Core 3.1 op uw ontwikkelcomputer. U kunt deze versie van .NET Core SDK voor meerdere platforms downloaden van .NET Core 3.1. downloaden.

Een Azure Digital Twins-exemplaar voorbereiden

Als u met Azure Digital Twins in dit artikel wilt werken, moet u eerst een Azure Digital Twins instellen. U hebt ook de vereiste machtigingen nodig om deze te kunnen gebruiken. Als u al een Azure Digital Twins hebt ingesteld, kunt u deze in plaats daarvan gebruiken.

Volg anders de instructies in Een instantie en verificatie instellen. De instructies bevatten informatie om u te helpen controleren of u elke stap met succes hebt voltooid.

Nadat u uw exemplaar hebt ingesteld, noteert u de volgende waarden. U hebt deze waarden later nodig om verbinding te maken met het exemplaar:

• De hostnaam van het exemplaar. U vindt de hostnaam in de Azure Portal.
• Het Azure-abonnement dat u hebt gebruikt om het exemplaar te maken. De naam of id werkt. U vindt het abonnement op de pagina Overzicht van uw exemplaar in Azure Portal.

Lokale Azure-referenties instellen

In dit voorbeeld wordt gebruikgemaakt van DefaultAzureCredential (onderdeel van de Azure.Identity-bibliotheek) om gebruikers te verifiëren bij de Azure Digital Twins-instantie wanneer u deze uitvoert op uw lokale machine. Voor meer informatie over verschillende manieren waarop een client-app kan verifiëren met Azure Digital Twins, raadpleegt u Verificatiecode voor app schrijven.

Met DefaultAzureCredential zoekt het voorbeeld naar referenties in uw lokale omgeving, zoals een Azure-aanmelding in een lokale Azure-CLI of in Visual Studio of Visual Studio Code. Daarom moet u zich lokaal aanmelden bij Azure via een van deze mechanismen om referenties in te stellen voor het voorbeeld.

Als u gebruikmaakt van Visual Studio of Visual Studio Code om het codevoorbeeld uit te voeren, moet u ervoor zorgen dat u bent aangemeld bij die editor met dezelfde Azure-referenties die u wilt gebruiken om uw Azure Digital Twins-instantie te openen.

Anders kunt u de Azure-CLI lokaal installeren, de opdrachtprompt uitvoeren op uw machine en de opdracht az login uitvoeren om u aan te melden bij uw Azure-account. Wanneer u hierna uw codevoorbeeld moet uitvoeren, zou u automatisch aangemeld moeten worden.

Project instellen

Zodra u klaar bent om aan de slag te gaan met Azure Digital Twins-exemplaar, begint u met het instellen van het client-app-project.

Open een opdrachtprompt of een ander consolevenster op uw computer en maak een lege projectmap waarin u uw werk wilt opslaan tijdens deze zelfstudie. Noem de map wat u wilt (bijvoorbeeld DigitalTwinsCodeTutorial).

Navigeer naar de nieuwe map.

Maak een leeg .NET-console-app-project in de projectmap. In het opdrachtvenster kunt u de volgende opdracht uitvoeren om een minimaal C#-project voor de console te maken:

dotnet new console

Met deze opdracht maakt u verschillende bestanden in uw map, waaronder een met de naam Program.cs, waar u de meeste code gaat schrijven.

Houd het opdrachtvenster geopend, omdat u het in de zelfstudie blijft gebruiken.

Vervolgens voegt u twee afhankelijkheden toe aan uw project die nodig zijn om te werken met Azure Digital Twins. De eerste bestaat uit het pakket voor Azure Digital Twins SDK voor .NET, de tweede biedt hulpmiddelen voor de verificatie met Azure.

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

Aan de slag met projectcode

In deze sectie begint u met het schrijven van de code voor uw nieuwe app-project om te werken met Azure Digital Twins. De behandelde acties zijn onder meer:

• Verificatie op basis van de service
• Een model uploaden
• Fouten waarnemen
• Digitale tweelingen maken
• Relaties maken
• Query uitvoeren voor digitale tweeling

Er is ook een sectie met de volledige code aan het einde van de zelfstudie. U kunt deze sectie als referentie gebruiken om uw programma tijdens het gebruik te controleren.

Open het bestand Program.cs in een code-editor om te beginnen. U ziet een minimale codesjabloon die er zo uitziet:

Voeg eerst enkele using regels toe boven aan de code om de benodigde afhankelijkheden op te halen.

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

Vervolgens voegt u code toe aan dit bestand om een deel van de functionaliteit in te vullen.

Verificatie op basis van de service

Het eerste wat uw app moet doen, is verifiëren op basis van de Azure Digital Twins-service. Vervolgens kunt u een service-clientklasse maken voor toegang tot de SDK-functies.

Voor verificatie hebt u de hostnaam van uw Azure Digital Twins nodig.

Plak de volgende code in Program.cs onder de regel "Hello World!" in de Main methode. Stel de waarde van in adtInstanceUrl op Azure Digital Twins hostnaam van het exemplaar.

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

Sla het bestand op.

Voer in het opdrachtvenster de code uit met de volgende opdracht:

dotnet run

Met deze opdracht worden de afhankelijkheden bij de eerste uitvoering hersteld en vervolgens het programma uitgevoerd.

• Als er geen fout optreedt, drukt het programma Serviceclient gemaakt, klaar on te starten af.
• Omdat er nog geen foutafhandeling in dit project is, ziet u, als er problemen zijn, een uitzondering die door de code wordt veroorzaakt.

Een model uploaden

Azure Digital Twins heeft geen intrinsieke domeinwoordenlijst. De typen elementen in uw omgeving die u kunt vertegenwoordigen in Azure Digital Twins, worden door u gedefinieerd met behulp van Modellen. Modellen lijken op klassen in objectgeoriënteerde programmeertalen. Ze bieden door de gebruiker gedefinieerde sjablonen die digitale tweelingen later kunnen volgen en instantiëren. Ze zijn geschreven in een JSON-achtige taal met de naam Digital Twins Definition Language (DTDL).

De eerste stap bij het maken van een Azure Digital Twins-oplossing is het definiëren van ten minste een model in een DTDL-bestand.

Maak in de map waar u het project hebt gemaakt een nieuw .json-bestand met de naam SampleModel.json. Plak in de volgende hoofdtekst van het bestand:

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

Voeg vervolgens wat meer code toe aan Program.cs om het model dat u hebt gemaakt, te uploaden naar uw Azure Digital Twins instantie.

Voer eerst boven aan het bestand de volgende using-instructies toe:

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

Vervolgens bereidt u het gebruik van de asynchrone methoden in de C# service-SDK voor door de handtekening van de Main methode te wijzigen zodat asynchrone uitvoering kan worden uitgevoerd.

static async Task Main(string[] args)
{

Vervolgens wordt de eerste bit van code geleverd die samenwerkt met de Azure Digital Twins-service. Met deze code wordt het DTDL-bestand dat u hebt gemaakt op basis van de schijf, geladen en vervolgens geüpload naar uw Azure Digital Twins-service-exemplaar.

Plak de volgende code onder de autorisatiecode die u eerder hebt toegevoegd.

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

Voer in het opdrachtvenster de programma uit met de volgende opdracht:

dotnet run

'Upload model' wordt afgedrukt in de uitvoer, wat aangeeft dat deze code is bereikt, maar er is nog geen uitvoer om aan te geven of het uploaden is geslaagd.

Als u een afdrukinstructie wilt toevoegen waarmee alle modellen worden weergegeven die zijn geüpload, voegt u de volgende code toe, direct na de vorige sectie:

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

Voordat u het programma opnieuw uitvoert om deze nieuwe code te testen, moet u even terug denken aan de laatste keer dat u het programma hebt uitgevoerd. U hebt uw model toen al geüpload. Azure Digital Twins kunt hetzelfde model niet twee keer uploaden, dus als u hetzelfde model opnieuw probeert te uploaden, moet het programma een uitzondering geven.

Met deze informatie in gedachten moet u het programma opnieuw uitvoeren met deze opdracht in het opdrachtvenster:

dotnet run

Het programma moet een uitzondering genereren. Wanneer u probeert een model te uploaden dat al is geüpload, retourneert de service de fout "ongeldige aanvraag" via de REST API. Als gevolg hiervan zal de Azure Digital Twins-client SDK een uitzondering genereren voor elke serviceretourcode die niet geslaagd is.

In de volgende sectie vindt u informatie over uitzonderingen zoals deze en hoe u deze in uw code kunt verwerken.

Fouten detecteren

Als u wilt voorkomen dat het programma vastloopt, kunt u uitzonderingscode toevoegen rond de code voor het uploaden van het model. Verpak de bestaande clientaanroep await client.CreateModelsAsync(typeList) in een try/catch-handler, zoals:

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

Als u nu het programma met in het opdrachtvenster hebt uitgevoerd, ziet u dat u dotnet run een foutcode terug krijgt. De uitvoer van de code voor het maken van het model laat deze fout zien:

Vanaf dit punt verstuurt de zelfstudie alle aanroepen naar servicemethoden in try/catch-handlers.

Digitale tweelingen maken

Nu u een model hebt geüpload naar Azure Digital Twins, kunt u deze modeldefinitie gebruiken om digitale tweelingen te maken. Digitale tweelingen zijn exemplaren van een model en vertegenwoordigen de entiteiten in uw bedrijfsomgeving: dingen als sensoren op een boerderij, ruimten in een gebouw, of lichten in een auto. In deze sectie wordt een aantal digitale tweelingen gemaakt op basis van het model dat u eerder hebt geüpload.

Voeg de volgende code toe aan het einde van de methode Main om drie digitale tweelingen te maken en initialiseren op basis van dit model.

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

Voer in het opdrachtvenster de programma uit met dotnet run. Zoek in de uitvoer naar de weergaveberichten die melden dat sampleTwin-0, sampleTwin-1 en sampleTwin-2 zijn gemaakt.

Voer vervolgens het programma opnieuw uit.

U ziet dat er geen fout wordt gegenereerd wanneer de tweelingen de tweede keer worden gemaakt, zelfs als tweeling al bestaan na de eerste uitvoering. In tegenstelling tot het maken van een model, is het maken van tweelingen op het REST-niveau een PUT-aanroep met upsert-semantiek. Als u dit soort REST-aanroep gebruikt, betekent dit dat als er al een tweeling bestaat, een poging om dezelfde tweeling opnieuw te maken alleen de oorspronkelijke tweeling vervangt. Er wordt geen fout gegenereerd.

Relaties maken

Vervolgens kunt u relaties maken tussen deze gemaakte tweelingen, om ze te verbinden in een tweelinggrafiek. Tweelinggrafieken worden gebruikt om uw gehele omgeving voor te stellen.

Voeg vervolgens een nieuwe statische methode toe aan de Program-klasse, onder de Main-methode (de code bevat nu twee methodes):

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

Voeg vervolgens de volgende code toe aan het einde van de Main-methode om de CreateRelationship-methode aan te roepen en gebruik de code die u zojuist hebt geschreven:

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

Voer in het opdrachtvenster de programma uit met dotnet run. Zoek in de uitvoer naar afdrukinstructies, waarin wordt gemeld dat de twee relaties zijn gemaakt.

Azure Digital Twins kunt u geen relatie maken als er al een andere relatie met dezelfde id bestaat. Als u het programma dus meerdere keren hebt uitgevoerd, ziet u uitzonderingen bij het maken van relaties. Met deze code worden de uitzonderingen onderschept en genegeerd.

Lijst met relaties

Met de volgende code die u toevoegt, kunt u de lijst met relaties zien die u hebt gemaakt.

Voeg de volgende nieuwe methode toe aan de Program-klasse:

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

Voeg vervolgens de volgende code toe aan het einde van de Main-methode om de ListRelationships-code aan te roepen:

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

Voer in het opdrachtvenster de programma uit met dotnet run. U ziet een lijst met alle relaties die u hebt gemaakt in een uitvoer-instructie die er als volgende uitziet:

Query's uitvoeren op digitale tweelingen

Een hoofdfunctie van Azure Digital Twins is de mogelijkheid om gemakkelijk en efficiënt query's uit te voeren op uw tweelinggrafiek om vragen over uw omgeving te beantwoorden.

In de laatste sectie van de code die in deze zelfstudie moet worden toegevoegd, wordt een query uitgevoerd op het Azure Digital Twins-exemplaar. Met de query die in dit voorbeeld wordt gebruikt, worden alle digitale tweelingen in het exemplaar geretourneerd.

Voeg deze using-instructie toe om het gebruik van de JsonSerializer-klasse in te schakelen om de informatie over de digitale tweeling te presenteren:

using System.Text.Json;

Voeg vervolgens de volgende code aan het einde van de Main-methode toe:

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

Voer in het opdrachtvenster de programma uit met dotnet run. In de uitvoer ziet u alle digitale tweelingen in dit exemplaar.

Volledig voorbeeld van de code

Op dit punt in de zelfstudie hebt u een volledige client-app die basisacties kan uitvoeren op Azure Digital Twins. Ter referentie wordt de volledige code van het programma in Program.cs hieronder weergegeven:

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

Resources opschonen

Nadat u deze zelfstudie hebt doorlopen, kunt u kiezen welke resources u wilt verwijderen, afhankelijk van wat u hierna wilt doen.

• Als u wilt doorgaan met de volgende zelfstudie, kan het exemplaar dat in deze zelfstudie wordt gebruikt, opnieuw worden gebruikt in de volgende zelfstudie. U kunt de Azure Digital Twins die u hier hebt ingesteld behouden en de rest van deze sectie overslaan.

• Als u het Azure Digital Twins-exemplaar dat u in dit artikel hebt ingesteld, wilt blijven gebruiken, maar sommige of alle modellen, tweelingen en relaties wilt wissen, kunt u de az dt CLI-opdrachten in een Azure Cloud Shell-venster gebruiken om de elementen te verwijderen die u wilt verwijderen.

• Als u de resources die u in deze zelfstudie hebt gemaakt niet nodig hebt, kunt u de Azure Digital Twins-instantie en alle andere resources uit dit artikel verwijderen met de opdracht az group delete. Hiermee verwijdert u alle Azure-resources in een resourcegroep, evenals de resourcegroep zelf.

  Belangrijk

  Het verwijderen van een resourcegroep kan niet ongedaan worden gemaakt. De resourcegroep en alle resources daarin worden permanent verwijderd. Zorg ervoor dat u niet per ongeluk de verkeerde resourcegroep of resources verwijdert.

  Open Azure Cloud Shellen voer de volgende opdracht uit om de resourcegroep en alles wat deze bevat te verwijderen.

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

U kunt ook de projectmap van uw lokale computer verwijderen.

Volgende stappen

In deze zelfstudie hebt u een volledig nieuwe .NET-console-clienttoepassing gemaakt. U hebt code voor deze client-app geschreven om de basisacties uit te voeren op een Azure Digital Twins-exemplaar.

Ga verder met de volgende zelfstudie om de dingen te bekijken die u kunt doen met een dergelijke voorbeeld-client-app: