你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 DTDL 分析程序库分析和验证模型

项目
10/27/2023

本文介绍如何使用 .NET 分析器库分析和验证 Azure 数字孪生模型。

Azure 数字孪生中的模型是使用基于 JSON-LD 的数字孪生定义语言 (DTDL) 定义的。

创建模型后，建议先离线对其进行验证，然后再将其上传到 Azure 数字孪生实例。

为了帮助你验证模型，NuGet： DTDLParser 上提供了一个 .NET 客户端 DTDL 分析库。可以直接在 C# 代码中使用分析器库。还可以在 GitHub 的 DTDLParserResolveSample 中查看分析器的示例用法。

关于 .NET 分析程序库

DTDLParser 库提供对 DTDL 定义的模型访问权限，实质上相当于 DTDL 的 C# 反射。此库可独立于任何 Azure 数字孪生 SDK 使用，尤其适合在可视化编辑器或文本编辑器中进行 DTDL 验证。使用它，可以在尝试将模型定义文件上传到服务之前确保这些文件有效。

若要使用分析程序库，请向其提供一组 DTDL 文档。通常情况下，你将从服务中检索这些模型文档，但如果你的客户端从一开始就负责将它们上传到服务中，则也可在本地获取它们。

下面是使用分析程序的一般工作流：

从服务中检索部分或全部 DTDL 文档。
将返回的内存中 DTDL 文档传递到分析程序。
分析程序会验证传递给它的文档集，并返回详细的错误信息。这种功能在编辑器场景中很有用。
使用分析程序 API 继续分析文档集中包括的模型。

分析程序的功能包括：

获取所实现的所有模型接口（接口的 extends 节的内容）。
获取在模型中声明的所有属性、遥测、命令、组件和关系。此命令还获取这些定义中包括的所有元数据，并且会考虑到继承（extends 节）。
获取所有复杂的模型定义。
确定模型是否可从另一个模型分配。

注意

IoT 即插即用设备使用小语法变体来描述其功能。此语法变体是 Azure 数字孪生中使用的 DTDL 的一个子集，在语义上与其兼容。使用分析程序库时，你不需要知道数字孪生体的 DTDL 是使用哪种语法变体创建的。默认情况下，对于 IoT 即插即用语法和 Azure 数字孪生语法，分析程序会始终返回相同的模型。

包含分析程序库的代码

你可以直接将分析程序库用于下述用途：在你自己的应用程序中验证模型，或者生成动态的、模型驱动的 UI、仪表板和报表。

若要支持下面的分析程序代码示例，请考虑 Azure 数字孪生实例中定义的多个模型：

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

后续步骤

编写完模型后，请参阅如何使用 Azure 数字孪生模型 API 上传模型（并执行其他管理操作）：

管理 DTDL 模型

通过

使用 DTDL 分析程序库分析和验证模型

关于 .NET 分析程序库

包含分析程序库的代码

后续步骤

反馈

其他资源