你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
使用 DTDL 分析程序库分析和验证模型
本文介绍如何使用 .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 上传模型(并执行其他管理操作):