DTDL ayrıştırıcı kitaplığıyla modelleri ayrıştırma ve doğrulama

Bu makalede,.NET ayrıştırıcı kitaplığını kullanarak Azure Digital Twins modellerini ayrıştırma ve doğrulama işlemleri açıklanmaktadır.

Azure Digital Twins'deki modeller 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 önerilir.

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ı kitaplığı hakkında

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

Ayrıştırıcı kitaplığını kullanmak için bir DTDL belgeleri kümesi sağlarsınız. Normalde, bu model belgelerini hizmetten alırsınız, ancak istemciniz bunları hizmete yüklemekten sorumluysa bunları yerel olarak da kullanabilirsiniz.

Ayrıştırıcıyı kullanmaya yönelik genel iş akışı aşağıdadır:

1. Hizmetten DTDL belgelerinin bazılarını veya tümünü 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 özellik düzenleyici senaryolarında kullanışlıdır.
4. Belge kümesine dahil edilen modelleri analiz etmeye devam etmek için ayrıştırıcı API'lerini kullanın.

Ayrıştırıcının özellikleri şunlardır:

• Uygulanan tüm model arabirimlerini (arabirimin extends bölümünün içeriği) alın.
• Modelde bildirilen tüm özellikleri, telemetriyi, komutları, bileşenleri ve ilişkileri alın. Bu komut ayrıca bu tanımlara dahil edilen tüm meta verileri alır ve devralmayı (extends bölümler) dikkate alır.
• Tüm karmaşık model tanımlarını alın.
• Modelin başka bir modelden atanıp atanamayacağını belirleyin.

Ayrıştırıcı kitaplığıyla kod

Ayrıştırıcı kitaplığını doğrudan kendi uygulamanızdaki modelleri doğrulamak veya dinamik, model temelli kullanıcı arabirimi, panolar ve raporlar oluşturmak 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 kodda, C# dilinde bu tanımları yansıtmak için ayrıştırıcı kitaplığının nasıl kullanılacağına ilişkin bir örnek gösterilmektedir:

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 yazmayı tamamladıktan sonra, Azure Digital Twins Modelleri API'leriyle bunları karşıya yüklemeyi (ve diğer yönetim işlemlerini yapmayı) öğrenin:

• DTDL modellerini yönetme