Разбирайте и проверяйте модели с помощью библиотеки парсера DTDL

Эта статья описывает, как анализировать и проверять модели Azure Digital Twins с использованием библиотеки парсера .NET.

Модели в Azure Digital Twins определяются с использованием языка определения цифровых двойников (DTDL) на основе JSON-LD.

После создания модели рекомендуется проверить модели в автономном режиме перед их отправкой в экземпляр Azure Digital Twins.

Чтобы помочь вам проверить модели, клиентская библиотека анализа DTDL на стороне клиента .NET предоставляется в NuGet: DTDLParser. Библиотеку синтаксического анализа можно использовать непосредственно в коде C#. Вы также можете просмотреть пример использования средства синтаксического анализа в DTDLParserResolveSample в GitHub.

О библиотеке анализа .NET

Библиотека DTDLParser предоставляет модельный доступ к определениям DTDL, по сути, выступая в качестве эквивалента отражения C# для DTDL. Эта библиотека может использоваться независимо от любого Azure Digital Twins SDK, особенно для проверки DTDL в визуальном или текстовом редакторе. Полезно убедиться, что файлы определения вашей модели действительны, прежде чем пытаться загрузить их в службу.

Чтобы использовать библиотеку синтаксического анализатора, необходимо предоставить ей набор документов DTDL. Как правило, эти документы модели можно получить из сервиса, но они также могут быть доступны локально, если ваш клиент был ответственен за их загрузку в сервис в первую очередь.

Вот общий рабочий процесс использования парсера:

1. Извлеките некоторые или все документы DTDL из сервиса.
2. Передайте возвращенные в памяти DTDL-документы в синтаксический анализатор.
3. Средство синтаксического анализа проверяет набор документов, переданных в него, и возвращает подробные сведения об ошибке. Эта способность полезна в сценариях редактирования.
4. Используйте API синтаксического анализатора, чтобы продолжить анализ моделей, включенных в набор документов.

К возможностям парсера можно отнести:

• Получите все реализованные интерфейсы модели (содержимое раздела интерфейса extends ).
• Получите все свойства, данные телеметрии, команды, компоненты и связи, объявленные в модели. Эта команда также получает все метаданные, включенные в эти определения, и учитывает наследование (разделы extends).
• Получите все сложные определения моделей.
• Определите, может ли модель быть назначена из другой модели.

Писать код с библиотекой парсера

Вы можете использовать библиотеку парсера напрямую для таких задач, как валидация моделей в вашем приложении или генерация динамических, управляемых моделями пользовательских интерфейсов, панелей мониторинга и отчетов.

Для поддержки следующего примера кода синтаксического анализа рассмотрим несколько моделей, определенных в экземпляре Azure Digital Twins:

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

Приведенный ниже код показывает пример использования библиотеки синтаксического анализатора для отражения этих определений в C#.

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

Дальнейшие действия

После того как вы закончите создавать свои модели, узнайте, как их загрузить (а также выполнить другие операции управления) с помощью API моделей Azure Digital Twins.

• Управление моделями Azure Digital Twins