Modelleri DTDL ayrıştırıcı kütüphanesi ile ayrıştırın ve doğrulayın

Bu makale, .NET ayrıştırıcı kütüphanesini kullanarak Azure Digital Twins modellerini nasıl ayrıştıracağınızı ve doğrulayacağınızı açıklar.

Modeller Azure Digital Twins'de JSON-LD tabanlı Digital Twins Tanım Dili (DTDL) kullanılarak tanımlanır.

Model oluşturduktan sonra, modellerinizi Azure Digital Twins örneğine yüklemeden önce çevrimdışı olarak doğrulamanızı öneririz.

Modellerinizi doğrulamanıza yardımcı olmak için NuGet: DTDLParser üzerinde bir .NET istemci tarafı DTDL ayrıştırma kitaplığı sağlanır. Ayrıştırıcı kitaplığını doğrudan C# kodunuzda kullanabilirsiniz. Ayrıştırıcının örnek kullanımını GitHub'daki DTDLParserResolveSample'da da görüntüleyebilirsiniz.

.NET Ayrıştırıcı Kütüphanesi Hakkında

DTDLParser kütüphanesi, DTDL tanımlarına model erişimi sağlar ve esasen DTDL için C# yansımasının eşdeğeri olarak işlev görür. Bu kütüphane, herhangi bir Azure Digital Twins SDK'den bağımsız olarak, özellikle bir görsel veya metin düzenleyicisinde DTDL doğrulaması için kullanılabilir. Model tanım dosyalarınızın hizmete yüklemeye çalışmadan önce geçerli olduğundan emin olmak için kullanışlıdır.

Ayrıştırıcı kütüphanesini kullanmak için ona bir dizi DTDL belgesi sağlarsınız. Normalde, bu model belgeleri hizmetten alırsınız, ancak müşteri bunları başlangıçta hizmete yüklemekten sorumluysa, bunlara yerel olarak da erişebilirsiniz.

İşte ayrıştırıcıyı kullanma genel iş akışı:

1. Hizmetten bazı veya tüm DTDL belgelerini alın.
2. Döndürülen, bellek içi DTDL belgelerini ayrıştırıcıya geçirin.
3. Ayrıştırıcı, ona geçirilen belge kümesini doğrular ve ayrıntılı hata bilgilerini döndürür. Bu yetenek, düzenleyici senaryolarında faydalıdır.
4. Belgelerin kümelerinde yer alan modelleri analiz etmeye devam etmek için çevirici API'lerini kullanın.

Ayrıştırıcının yetenekleri şunlardır:

• Tüm uygulanmış model arayüzlerini alın (arayüzün extends bölümünün içeriği).
• Modelde tanımlanan tüm özellikleri, telemetriyi, komutları, bileşenleri ve ilişkileri alın. Bu komut, bu tanımlara dahil edilen tüm meta verileri alır ve miras (extends bölümleri) durumunu dikkate alır.
• Tüm karmaşık model tanımlarını alın.
• Bir modelin başka bir modelden atanabilir olup olmadığını belirleyin.

Uyarı

IoT Plug and Play cihazlar, işlevselliklerini tanımlamak için küçük bir sözdizimi varyantı kullanır. Bu söz dizimi varyantı, Azure Digital Twins'te kullanılan DTDL'nin anlamsal olarak uyumlu bir alt kümesidir. Ayrıştırıcı kitaplığını kullanırken, dijital ikizinizin DTDL'sini oluşturmak için hangi söz dizimi değişkeninin kullanıldığını bilmeniz gerekmez. Ayrıştırıcı, varsayılan olarak, hem IoT Plug and Play hem de Azure Digital Twins söz dizimi için her zaman aynı modeli döndürecektir.

Ayrıştırıcı kütüphanesi ile kodlama

Parser kütüphanesini doğrudan kullanabilirsiniz; kendi uygulamanızda modelleri doğrulamak veya dinamik, model odaklı kullanıcı arayüzleri, panolar ve raporlar oluşturmak gibi şeyler için kullanabilirsiniz.

Aşağıdaki ayrıştırıcı kod örneğini desteklemek için Azure Digital Twins örneğinde tanımlanan birkaç modeli göz önünde bulundurun:

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

Aşağıdaki kod, bu tanımlamalar üzerinde düşünmek için ayrıştırıcı kütüphanesini nasıl kullanabileceğinize dair bir örnek gösteriyor.

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

Sonraki adımlar

Modellerinizi tamamladıktan sonra, Azure Digital Twins Modelleri API'leri ile nasıl yükleme yapacağınızı (ve diğer yönetim işlemlerini) öğrenin.

• Azure Digital Twins modellerini yönetme