Ezt a böngészőt már nem támogatjuk.
Frissítsen a Microsoft Edge-re, hogy kihasználhassa a legújabb funkciókat, a biztonsági frissítéseket és a technikai támogatást.
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.
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:
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 példány és a hitelesítés beállítása című témakör 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. A gazdagép nevét az Azure Portalon találja.
Ez a minta a DefaultAzureCredential (a tár része) használatával hitelesíti a Azure.Identity felhasználókat az Azure Digital Twins-példánysal, amikor a helyi gépen futtatja. 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 olvashat bővebben.
Ezzel DefaultAzureCredentiala példával a minta 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. Ezt követően a kódminta futtatásakor automatikusan hitelesíteni kell.
Ha készen áll az Azure Digital Twins-példányra, indítsa 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 .NET-hez készült Azure Digital Twins SDK csomagja. 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
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:
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.
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 az Azure adtInstanceUrl Digital Twins-példány gazdagépének nevét.
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.
Megjegyzés
Jelenleg ismert probléma van a DefaultAzureCredential burkolóosztályt érintően, amely a hitelesítés során hibát okozhat. Ha ezt a problémát tapasztalja, a probléma megoldásához próbálja meg példányosítani DefaultAzureCredential a következő opcionális paramétert: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });
A problémával kapcsolatos további információkért tekintse meg az Azure Digital Twins ismert problémáit.
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"
}
Tipp
Ha ehhez az oktatóanyaghoz a Visual Studiót használja, érdemes lehet kiválasztania az újonnan létrehozott JSON-fájlt, és a TulajdonságfelügyelőBen a Másolás kimeneti könyvtárra tulajdonságot a Másolás, ha újabb vagy a Mindig másolás parancsra állítja. Ez a tulajdonságérték lehetővé teszi, hogy a Visual Studio megkeresse az alapértelmezett elérési úttal rendelkező JSON-fájlt, amikor az oktatóanyag többi részében az F5-tel futtatja a programot.
Tipp
A modelldokumentumokban ellenőrizheti, hogy a DTDL érvényes-e a DTDLParser kódtár használatával. A kódtár használatáról további információt a modellek elemzése és érvényesítése című témakörben talál.
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)
{
Megjegyzés
A használat async nem feltétlenül szükséges, mivel az SDK az összes hívás szinkron verzióit is biztosítja. Ez az oktatóanyag a következőt használja async: .
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 kivennie. 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.
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 dotnet run a programot 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 becsomagolja a szolgáltatásba irányuló összes hívást a try/catch kezelőkben.
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 ikerpéldányok második létrehozásakor nem jelenik meg hiba, annak ellenére, hogy az ikerpéldányok 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.
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.
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:
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 az osztály használatát a JsonSerializer digitális ikeradatok 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.
Megjegyzés
A gráf adatainak módosítása után akár 10 másodperces késés is előfordulhat, mielőtt a módosítások megjelennek a lekérdezésekben.
A DigitalTwins API azonnal tükrözi a változásokat, ezért ha azonnali válaszra van szüksége, lekérdezés helyett használjon EGY API-kérést (DigitalTwins GetById) vagy egy SDK-hívást (GetDigitalTwin).
Az oktatóanyag ezen szakaszában egy teljes ügyfélalkalmazással rendelkezik, amely alapvető műveleteket hajthat végre az Azure Digital Twinsen. 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 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 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.
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:
Oktatás
Tanúsítvány
Microsoft Certified: Azure Developer Associate - Certifications
A Microsoft Azure-ban végpontok közötti megoldásokat hozhat létre az Azure Functions létrehozásához, webalkalmazások implementálásához és kezeléséhez, az Azure Storage használatával történő megoldások fejlesztéséhez stb.