Megosztás a következőn keresztül:

Modellek elemzése és érvényesítése a DTDL-elemzőtárral

  • Cikk

Ez a cikk azt ismerteti, hogyan elemezheti és érvényesítheti az Azure Digital Twins-modelleket a .NET-elemzőtár használatával.

Az Azure Digital Twins modelljei a JSON-LD-alapú Digital Twins Definition nyelv (DTDL) használatával vannak definiálva.

A modell létrehozása után ajánlott offline állapotban ellenőrizni a modelleket, mielőtt feltöltené őket az Azure Digital Twins-példányba.

A modellek ellenőrzéséhez .NET ügyféloldali DTDL-elemzési kódtárat biztosít a NuGet: DTDLParser. Az elemzési kódtárat közvetlenül a C#-kódban használhatja. Az elemző mintahasználatát a GitHub DTDLParserResolveSample szolgáltatásában is megtekintheti.

A .NET-elemzőtár ismertetése

A DTDLParser kódtár a DTDL-definíciókhoz biztosít modellhozzáférést, amely lényegében a DTDL C#-tükröződésének megfelelője. Ez a kódtár bármely Azure Digital Twins SDK-tól függetlenül használható, különösen a vizualizáció- vagy szövegszerkesztőben történő DTDL-ellenőrzéshez. Hasznos, ha meggyőződik arról, hogy a modelldefiníciós fájlok érvényesek, mielőtt megpróbálná feltölteni őket a szolgáltatásba.

Az elemzőtár használatához DTDL-dokumentumokat kell megadnia. Ezek a modelldokumentumok általában lekérhetők a szolgáltatásból, de előfordulhat, hogy helyileg is elérhetők, ha az ügyfél volt a felelős azért, hogy először feltöltse őket a szolgáltatásba.

Az elemző használatának általános munkafolyamata a következő:

  1. Néhány vagy az összes DTDL-dokumentum lekérése a szolgáltatásból.
  2. Adja át a visszaadott, memórián belüli DTDL-dokumentumokat az elemzőnek.
  3. Az elemző ellenőrzi a neki átadott dokumentumok készletét, és részletes hibainformációkat ad vissza. Ez a képesség szerkesztői forgatókönyvekben hasznos.
  4. Az elemző API-k segítségével folytathatja a dokumentumkészletben szereplő modellek elemzését.

Az elemző képességei a következők:

  • Szerezze be az összes implementált modellillesztőt (a felület szakaszának extends tartalmát).
  • Lekérheti a modellben deklarált összes tulajdonságot, telemetriát, parancsot, összetevőt és kapcsolatot. Ez a parancs a definíciókban szereplő összes metaadatot is lekéri, és figyelembe veszi az öröklést (extends szakaszokat).
  • Szerezze be az összes összetett modelldefiníciót.
  • Annak meghatározása, hogy egy modell hozzárendelhető-e egy másik modellhez.

Feljegyzés

Az IoT Plug and Play-eszközök egy kis szintaxisvariánst használnak a funkciójuk leírásához. Ez a szintaxisvariáns az Azure Digital Twinsben használt DTDL szemantikailag kompatibilis részhalmaza. Az elemzőtár használatakor nem kell tudnia, hogy melyik szintaxisvariánst használták a digitális ikerpéldány DTDL-jének létrehozásához. Az elemző alapértelmezés szerint ugyanazt a modellt adja vissza mind az IoT Plug and Play, mind az Azure Digital Twins szintaxishoz.

Kód az elemzőtárral

Az elemzőtárat közvetlenül használhatja például a modellek saját alkalmazásban való érvényesítéséhez, vagy dinamikus, modellalapú felhasználói felület, irányítópultok és jelentések létrehozásához.

Az alábbi elemzőkód-példa támogatásához fontolja meg egy Azure Digital Twins-példányban definiált modelleket:

[
    {
      "@context": "dtmi:dtdl:context;3",
      "@id": "dtmi:com:contoso:coffeeMaker;1",
      "@type": "Interface",
      "contents": [
        {
          "@type": "Component",
          "name": "coffeeMaker",
          "schema": "dtmi:com:contoso:coffeeMakerInterface;1"
        }
      ]
    },
    {
      "@context": "dtmi:dtdl:context;3",
      "@id": "dtmi:com:contoso:coffeeMakerInterface;1",
      "@type": "Interface",
      "contents": [
        {
          "@type": "Property",
          "name": "waterTemp",
          "schema": "double"
        }
      ]
    },
    {
      "@context": "dtmi:dtdl:context;3",
      "@id": "dtmi:com:contoso:coffeeBar;1",
      "@type": "Interface",
      "contents": [
        {
          "@type": "Relationship",
          "name": "foo",
          "target": "dtmi:com:contoso:coffeeMaker;1"
        },
        {
          "@type": "Property",
          "name": "capacity",
          "schema": "integer"
        }
      ]
    }
  ]

Az alábbi kód egy példát mutat be arra, hogyan használhatja az elemzőtárat az alábbi definíciók C#-ban való tükrözésére:

using Azure;
using Azure.DigitalTwins.Core;
using DTDLParser;
using DTDLParser.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace DigitalTwins_Samples
{
    public static class ListExtensions
    {
        public static async IAsyncEnumerable<T> AsAsyncEnumerable<T>(this IEnumerable<T> input)
        {
            foreach (var value in input)
            {
                yield return value;
            }
            await Task.Yield();
        }
    }

    public class ParseModelsSample
    {
        public async Task ParseDemoAsync(DigitalTwinsClient client)
        {
            try
            {
                AsyncPageable<DigitalTwinsModelData> mdata = client.GetModelsAsync(new GetModelsOptions { IncludeModelDefinition = true });
                var models = new List<string>();
                await foreach (DigitalTwinsModelData md in mdata)
                    models.Add(md.DtdlModel);
                var parser = new ModelParser();
                IReadOnlyDictionary<Dtmi, DTEntityInfo> dtdlOM = await parser.ParseAsync(models.AsAsyncEnumerable());

                var interfaces = new List<DTInterfaceInfo>();
                IEnumerable<DTInterfaceInfo> ifenum =
                    from entity in dtdlOM.Values
                    where entity.EntityKind == DTEntityKind.Interface
                    select entity as DTInterfaceInfo;
                interfaces.AddRange(ifenum);
                foreach (DTInterfaceInfo dtif in interfaces)
                {
                    PrintInterfaceContent(dtif, dtdlOM);
                }
            }
            catch (RequestFailedException ex)
            {
                Console.WriteLine($"Failed due to {ex}");
                throw;
            }
        }

        public void PrintInterfaceContent(DTInterfaceInfo dtif, IReadOnlyDictionary<Dtmi, DTEntityInfo> dtdlOM, int indent = 0)
        {
            var sb = new StringBuilder();
            for (int i = 0; i < indent; i++) sb.Append("  ");
            Console.WriteLine($"{sb}Interface: {dtif.Id} | {dtif.DisplayName}");
            IReadOnlyDictionary<string, DTContentInfo> contents = dtif.Contents;

            foreach (DTContentInfo item in contents.Values)
            {
                switch (item.EntityKind)
                {
                    case DTEntityKind.Property:
                        DTPropertyInfo pi = item as DTPropertyInfo;
                        Console.WriteLine($"{sb}--Property: {pi.Name} with schema {pi.Schema}");
                        break;
                    case DTEntityKind.Relationship:
                        DTRelationshipInfo ri = item as DTRelationshipInfo;
                        Console.WriteLine($"{sb}--Relationship: {ri.Name} with target {ri.Target}");
                        break;
                    case DTEntityKind.Telemetry:
                        DTTelemetryInfo ti = item as DTTelemetryInfo;
                        Console.WriteLine($"{sb}--Telemetry: {ti.Name} with schema {ti.Schema}");
                        break;
                    case DTEntityKind.Component:
                        DTComponentInfo ci = item as DTComponentInfo;
                        Console.WriteLine($"{sb}--Component: {ci.Id} | {ci.Name}");
                        DTInterfaceInfo component = ci.Schema;
                        PrintInterfaceContent(component, dtdlOM, indent + 1);
                        break;                
                }
            }
        }
    }
}

Következő lépések

Miután befejezte a modellek írását, tekintse meg, hogyan töltheti fel őket (és hogyan végezhet más felügyeleti műveleteket) az Azure Digital Twins Models API-kkal: