Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
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 krok za krokem vytvořením konzolové klientské aplikace v jazyce C#, úplně od začátku.
- Nastavení projektu
- Začínáme s kódem projektu
- Kompletní ukázka kódu
- Vyčistěte zdroje
- Další kroky
Prerequisites
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, potřebujete 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 (část Azure.Identity knihovny) k ověření v instanci Azure Digital Twins při spuštění ukázky na místním počítači.
DefaultAzureCredential je jednou z mnoha možností ověřování. 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.
S pomocí DefaultAzureCredential ukázka vyhledá přihlašovací údaje ve svém místním prostředí, jako je přihlášení k Azure v místním Azure CLI nebo ve Visual Studiu 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. Jakmile se přihlásíte, ukázka kódu vás při spuštění automaticky ověří.
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ě jednoho s názvem Program.cs , kde píš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 přidejte do projektu dvě závislosti, které jsou potřeba pro práci se službou Azure Digital Twins. První závislostí je balíček pro sadu SDK Azure Digital Twins pro .NET. Druhá závislost 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 vašeho programu průběžně.
Začněte tím, že soubor otevřete Program.cs v libovolném editoru kódu. Zobrazí se minimální šablona kódu, která vypadá přibližně takto:
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ěřit se vůči službě
První věc, kterou vaše aplikace potřebuje, 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 Program.cs vložte následující kód pod řádek tisku "Hello, World!" 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: "Klient služby vytvořený – připravený k přechodu".
- 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.
Note
V současné době existuje známý problém, který ovlivňuje DefaultAzureCredential wrapper class a může způsobit chybu při autentizaci. 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. Pomocí modelů definujete typy prvků ve vašem prostředí, které můžete reprezentovat ve službě Azure Digital Twins. Modely jsou podobné třídám v objektově orientovaných programovacích jazycích; poskytují uživatelsky definované šablony pro digitální dvojčata, které mohou později sledovat a vytvořit 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í obsah 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, možná budete chtít 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. Tato hodnota vlastnosti umožňuje sadě Visual Studio 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 přidejte další kód do Program.cs pro nahrání modelu, 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)
{
Note
Použití async není výhradně povinné, protože sada SDK také poskytuje synchronní verze všech volání. Tento návod procvičuje používání 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 text "Nahrát model", který indikuje, že byl tento kód dosažen. Zatím ale neexistuje žádný výstup, který by indikoval, jestli nahrávání proběhlo úspěšně.
Pokud chcete přidat příkaz print zobrazující všechny modely, které se úspěšně nahrály 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 neumožňuje nahrávat 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. Při pokusu o nahrání modelu, který je již nahraný, vrátí služba prostřednictvím rozhraní REST API chybu "špatný požadavek". V důsledku toho klientská sada SDK služby Azure Digital Twins vyvolá výjimku pro každou službu, která vrací jiný kód 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.
Záchyt 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ě. Zjistíte, že získáte podrobnější informace o problému s nahráním modelu, včetně kódu chyby, který uvádí, že ModelIdAlreadyExists.
Od tohoto okamžiku kurz obalí všechna volání metod služby do obslužných rutin 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.
Chcete-li vytvořit a inicializovat tři digitální dvojčata na základě tohoto modelu, přidejte na konec Main metody následující kód.
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 zprávy o tom, že 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 volání PUT s sémantikou upsertu na úrovni REST. 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ána žá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 výpisy, které uvádějí, že se tyto dvě relace úspěšně vytvořily.
Azure Digital Twins neumožňuje vytvořit relaci, pokud už existuje jiná relace se stejným ID. V důsledku toho se při vytváření relace zobrazí výjimky, pokud program spustíte vícekrát. Tento kód zachytí výjimky a ignoruje je.
Seznam vztahů
Další kód, který přidáte, vám umožní zobrazit seznam relací, které jste vytvořili.
Do třídy přidejte následující novou metodu 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}");
}
}
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:
Dotazování digitálních dvojčat
Hlavní funkcí služby Azure Digital Twins je schopnost snadno a efektivně dotazovat se na graf dvojčat, abyste získali odpovědi na dotazy 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.
Note
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. Následující příklad uvádí úplný kód programu v 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>
}
}
Vyčistěte zdroje
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> -yPokud 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ů.
Important
Odstranění skupiny prostředků je nevratné. Skupina prostředků a všechny prostředky obsažené v ní se trvale odstraní. Ujistěte se, že omylem nesmažete špatnou skupinu prostředků nebo jednotlivé 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: