设备孪生入门 (.NET/.NET)

介绍

设备孪生是存储设备状态信息(元数据、配置和条件)的 JSON 文档。 IoT 中心为连接到 IoT 中心的每台设备保留一个设备孪生。

使用设备孪生可以:

  • 存储来自解决方案后端的设备元数据。
  • 通过设备应用报告当前状态信息,例如可用功能和条件(例如,使用的连接方法)。
  • 同步设备应用和后端应用之间的长时间运行的工作流的状态(例如固件和配置更新)。
  • 查询设备的元数据、配置或状态。
Note

设备孪生旨在执行同步以及查询设备的配置和条件。 可在 了解设备孪生中找到设备孪生适用情况的详细信息。

设备孪生存储在 IoT 中心内,其中包含:

  • 标记,仅可由解决方案后端访问的设备元数据;
  • 所需属性,可以由解决方案后端修改以及由设备应用观察的 JSON 对象;以及
  • 报告属性,可由设备应用修改以及由解决方案后端读取的 JSON 对象。 标记和属性不能包含数组,但可以嵌套对象。

此外,解决方案后端可以根据上述所有数据查询设备孪生。 有关设备孪生的详细信息,请参阅了解设备孪生,有关查询的详细信息,请参阅 IoT 中心查询语言

Note

此时,只能从使用 MQTT 协议连接到 IoT 中心的设备访问设备孪生。 有关如何转换现有设备应用以使用 MQTT 的说明,请参阅 MQTT 支持 一文。

本教程演示如何:

  • 创建将标记添加到设备孪生的后端应用,以及将其连接通道作为设备孪生上的报告属性进行报告的模拟设备应用。
  • 使用标记上的筛选器和之前创建的属性通过后端应用查询设备。

在本教程结束时,将会创建这些 .NET 控制台应用:

  • CreateDeviceIdentity,一个 .NET 应用,用于创建设备标识和关联的安全密钥以连接模拟设备应用。
  • AddTagsAndQuery,一个 .NET 后端应用,用于添加标记并查询设备孪生。
  • ReportConnectivity,一个 .NET 设备应用,它模拟使用早前创建的设备标识连接到 IoT 中心的设备,并报告其连接条件。
Note

Azure IoT SDK 文章介绍了可用于构建设备和后端应用的 Azure IoT SDK。

若要完成本教程,需要满足以下条件:

  • Visual Studio 2015 或 Visual Studio 2017。
  • 有效的 Azure 帐户。 如果没有帐户,可以创建一个试用帐户,只需几分钟即可完成。

创建 IoT 中心

创建模拟设备应用要连接到的 IoT 中心。 以下步骤说明如何使用 Azure 门户来完成此任务。

  1. 登录到 Azure 门户
  2. 在“跳转栏”中,依次单击“新建” > “物联网” > “IoT 中心”。

    Azure 门户跳转栏

  3. 在“IoT 中心”边栏选项卡中,选择 IoT 中心的配置。

    IoT 中心边栏选项卡

    • 在“名称”框中,输入 IoT 中心的名称。 如果该“名称”有效且可用,“名称”框中会出现绿色的勾选标记。
    • 选择 定价和缩放层。 本教程不需要特定的层。 对于本教程,请使用免费 F1 层。
    • 在“资源组”中,创建资源组或选择现有的资源组。 有关详细信息,请参阅使用资源组管理 Azure 资源
    • 在“位置”中,选择托管 IoT 中心的位置。 对于本教程,请选择最近位置。
  4. 选择 IoT 中心配置选项后,单击“创建”。 Azure 可能需要几分钟时间来创建 IoT 中心。 若要检查状态,可以在“启动板”或“通知”面板中监视进度。

    新的 IoT 中心状态

  5. 成功创建 IoT 中心后,请在 Azure 门户中单击 IoT 中心对应的新磁贴,以打开新 IoT 中心的边栏选项卡。 记下“主机名”,然后单击“共享访问策略”。

    新的 IoT 中心边栏选项卡

  6. 在“共享访问策略”边栏选项卡中,单击“iothubowner”策略,然后复制并记下“iothubowner”边栏选项卡中的 IoT 中心连接字符串。 有关详细信息,请参阅“IoT 中心开发人员指南”中的访问控制

    共享访问策略边栏选项卡

创建设备标识

在本部分中,将使用 Azure 门户在 IoT 中心的标识注册表中创建设备标识。 设备无法连接到 IoT 中心,除非它在标识注册表中具有条目。 有关详细信息,请参阅 IoT 中心开发人员指南的“标识注册表”部分。 门户中的“Device Explorer”可帮助生成唯一的设备 ID 和密钥,当设备连接到 IoT 中心时,可以使用这些信息进行自我标识。 设备 ID 区分大小写。

  1. 请确保已登录到 Azure 门户

  2. 在跳转栏中单击“所有资源”,然后查找 IoT 中心资源。

    导航到 IoT 中心

  3. IoT 中心资源打开以后,单击“Device Explorer”工具,然后单击顶部的“添加”。 提供新设备的名称(例如 myDeviceId),然后单击“保存”。

    在门户中创建设备标识

    这将为 IoT 中心创建新设备标识。

  4. 在 Device Explorer 的设备列表中,单击新创建的设备,记下“连接字符串---主键”。

    设备连接字符串

Note

IoT 中心标识注册表仅存储用于实现 IoT 中心安全访问的设备标识。 它存储设备 ID 和密钥作为安全凭据,以及启用或禁用标志让你禁用对单个设备的访问。 如果应用程序需要存储其他特定于设备的元数据,则应使用特定于应用程序的存储。 有关详细信息,请参阅 IoT 中心开发人员指南

如果想改为以编程方式创建设备标识,请阅读文章使用 .NET 将模拟设备连接到 IoT 中心中的相应部分。

创建服务应用

在本部分中,将创建一个 .NET 控制台应用(使用 C#),该应用将位置元数据添加到与 myDeviceId 关联的设备孪生。 然后,该应用将选择设备来查询存储在 IoT 中心的设备孪生,然后查询报告手机网络连接的设备孪生。

  1. 在 Visual Studio 中,使用“ 控制台应用程序 ”项目模板将 Visual C# Windows 经典桌面项目添加到当前解决方案。 将项目命名为 AddTagsAndQuery

    新的 Visual C# Windows 经典桌面项目

  2. 在“解决方案资源管理器”中,右键单击“AddTagsAndQuery”项目,然后单击“管理 NuGet 包...”。
  3. 在“NuGet 包管理器”窗口中,选择“浏览”,然后搜索“microsoft.azure.devices”。 选择“安装”以安装“Microsoft.Azure.Devices”包,并接受使用条款。 该过程将下载、安装 Azure IoT 服务 SDK NuGet 包及其依赖项并添加对它的引用。

    “NuGet 包管理器”窗口

  4. Program.cs 文件顶部添加以下 using 语句:

     using Microsoft.Azure.Devices;
    
  5. 将以下字段添加到 Program 类。 将占位符值替换为在上一部分中为中心创建的 IoT 中心连接字符串。

     static RegistryManager registryManager;
     static string connectionString = "{iot hub connection string}";
    
  6. 将以下方法添加到 Program 类:

     public static async Task AddTagsAndQuery()
     {
         var twin = await registryManager.GetTwinAsync("myDeviceId");
         var patch =
             @"{
                 tags: {
                     location: {
                         region: 'US',
                         plant: 'Redmond43'
                     }
                 }
             }";
         await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
    
         var query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
         var twinsInRedmond43 = await query.GetNextAsTwinAsync();
         Console.WriteLine("Devices in Redmond43: {0}", string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));
    
         query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
         var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
         Console.WriteLine("Devices in Redmond43 using cellular network: {0}", string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
     }
    

    RegistryManager 类公开从该服务与设备孪生交互所需的所有方法。 上面的代码首先初始化 registryManager 对象,然后检索 myDeviceId 的设备孪生,最后使用所需位置信息更新其标记。

    在更新后,它将执行两个查询:第一个仅选择位于 Redmond43 工厂的设备的设备孪生,第二个将查询细化为仅选择还要通过移动电话网络连接的设备。

    请注意上面的代码,当它创建 query 对象时,会指定返回的最大文档数。 query 对象包含 HasMoreResults 布尔值属性,你可以使用它多次调用 GetNextAsTwinAsync 方法来检索所有结果。 名为 GetNextAsJson 的方法可用于非设备孪生的结果(例如聚合查询的结果)。

  7. 最后,在 Main 方法中添加以下行:

     registryManager = RegistryManager.CreateFromConnectionString(connectionString);
     AddTagsAndQuery().Wait();
     Console.WriteLine("Press Enter to exit.");
     Console.ReadLine();
    
  8. 在“解决方案资源管理器”中,打开“设置启动项目...”,并确保 AddTagsAndQuery 项目的“操作”为“启动”。 生成解决方案。

  9. 右键单击 AddTagsAndQuery 项目并选择“调试”,然后选择“启动新实例”来运行此应用程序。 在查询位于 Redmond43 的所有设备的查询结果中,你应该会看到一个设备,而在将结果限制为使用蜂窝网络的设备的查询结果中没有任何设备。

    在窗口中查询结果

在下一部分中,创建的设备应用将报告连接信息,并更改上一部分中查询的结果。

创建设备应用

在此部分,需创建一个 .NET 控制台应用作为“myDeviceId”连接到中心,然后更新其报告属性,使其包含它使用手机网络进行连接的信息。

  1. 在 Visual Studio 中,使用“ 控制台应用程序 ”项目模板将 Visual C# Windows 经典桌面项目添加到当前解决方案。 将项目命名为“ReportConnectivity”。

    新的 Visual C# Windows 经典设备应用

  2. 在解决方案资源管理器中,右键单击“ReportConnectivity”项目,然后单击“管理 NuGet 包...”。

  3. 在“NuGet 包管理器”窗口中,选择“浏览”,搜索“microsoft.azure.devices.client”。 选择“安装”,安装“microsoft.azure.devices.client”包,并接受使用条款。 该过程将下载、安装 Azure IoT 设备 SDK NuGet 包及其依赖项并添加对它的引用。

    “NuGet 包管理器”窗口客户端应用

  4. Program.cs 文件顶部添加以下 using 语句:

     using Microsoft.Azure.Devices.Client;
     using Microsoft.Azure.Devices.Shared;
     using Newtonsoft.Json;
    
  5. 将以下字段添加到 Program 类。 将占位符值替换为在上一部分中记下的设备连接字符串。

     static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.cn;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
     static DeviceClient Client = null;
    
  6. 将以下方法添加到 Program 类:

    public static async void InitClient()
     {
         try
         {
             Console.WriteLine("Connecting to hub");
             Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, TransportType.Mqtt);
             Console.WriteLine("Retrieving twin");
             await Client.GetTwinAsync();
         }
         catch (Exception ex)
         {
             Console.WriteLine();
             Console.WriteLine("Error in sample: {0}", ex.Message);
         }
     }
    

    Client 对象公开从该设备与设备孪生交互所需的所有方法。 上述代码会初始化“客户端”对象,然后检索 myDeviceId设备孪生。

  7. 将以下方法添加到 Program 类:

     public static async void ReportConnectivity()
     {
         try
         {
             Console.WriteLine("Sending connectivity data as reported property");
    
             TwinCollection reportedProperties, connectivity;
             reportedProperties = new TwinCollection();
             connectivity = new TwinCollection();
             connectivity["type"] = "cellular";
             reportedProperties["connectivity"] = connectivity;
             await Client.UpdateReportedPropertiesAsync(reportedProperties);
         }
         catch (Exception ex)
         {
             Console.WriteLine();
             Console.WriteLine("Error in sample: {0}", ex.Message);
         }
     }
    

    上述代码会使用连接信息更新 myDeviceId 的报告属性。

  8. 最后,在 Main 方法中添加以下行:

    try
    {
         InitClient();
         ReportConnectivity();
    }
    catch (Exception ex)
    {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
    }
    Console.WriteLine("Press Enter to exit.");
    Console.ReadLine();
    
  9. 在“解决方案资源管理器”中,打开“设置启动项目...”,并确保“ReportConnectivity”项目的“操作”为“启动”。 生成解决方案。

  10. 右键单击“ReportConnectivity”项目并选择“调试”,然后选择“启动新实例”来运行此应用程序。 应该可以看到应用获取孪生信息,然后发送连接信息作为报告属性。

    运行设备应用来报告连接信息

  11. 现在设备报告了其连接信息,该信息应出现在两个查询中。 运行 .NET AddTagsAndQuery 应用即可再次运行查询。 这次 myDeviceId 应出现在两个查询结果中。

    成功报告设备连接信息

后续步骤

本教程中,在 Azure 门户中配置了新的 IoT 中心,然后在 IoT 中心的标识注册表中创建了设备标识。 已从后端应用以标记形式添加了设备元数据,并编写了模拟的设备应用,用于报告设备孪生中的设备连接信息。 还学习了如何使用类似 SQL 的 IoT 中心查询语言来查询此信息。

充分利用以下资源: