Kom igång med enhetstvillingar (.NET)

Artikel
01/29/2024

Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, som metadata, konfigurationer och villkor. IoT Hub bevarar en enhetstvilling för varje enhet som ansluter till den.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Använd enhetstvillingar för att:

Lagra enhetsmetadata från lösningens serverdel.
Rapportera aktuell tillståndsinformation, till exempel tillgängliga funktioner och villkor, till exempel den anslutningsmetod som används, från enhetsappen.
Synkronisera tillståndet för långvariga arbetsflöden, till exempel inbyggd programvara och konfigurationsuppdateringar, mellan en enhetsapp och en serverdelsapp.
Fråga efter enhetens metadata, konfiguration eller tillstånd.

Enhetstvillingar är utformade för synkronisering och för att köra frågor mot enhetskonfigurationer och villkor. Mer information om enhetstvillingar, inklusive när du ska använda enhetstvillingar, finns i Förstå enhetstvillingar.

IoT Hubs lagrar enhetstvillingar som innehåller följande element:

Taggar. Enhetsmetadata är endast tillgängliga för lösningens serverdel.
Önskade egenskaper. JSON-objekt som kan ändras av lösningens serverdel och kan observeras av enhetsappen.
Rapporterade egenskaper. JSON-objekt kan ändras av enhetsappen och kan läsas av lösningens serverdel.

Taggar och egenskaper får inte innehålla matriser, men kan innehålla kapslade objekt.

Följande bild visar enhetstvillingorganisationen:

Skärmbild av ett konceptdiagram för enhetstvillingar.

Dessutom kan lösningens serverdel köra frågor mot enhetstvillingar baserat på alla ovanstående data. Mer information om enhetstvillingar finns i Förstå enhetstvillingar. Mer information om frågor finns i IoT Hub-frågespråk.

Den här artikeln visar hur du gör följande:

Använd en simulerad enhetsapp för att rapportera dess anslutningskanal som en rapporterad egenskap på enhetstvillingen.
Fråga enheter från serverdelsappen med filter på taggarna och egenskaperna som skapades tidigare.

I den här artikeln skapar du två .NET-konsolappar:

AddTagsAndQuery: en serverdelsapp som lägger till taggar och frågar enhetstvillingar.
Rapport Anslut ivity: en simulerad enhetsapp som ansluter till din IoT-hubb och rapporterar dess anslutningsvillkor.

Kommentar

Mer information om de SDK-verktyg som är tillgängliga för att skapa både enhets- och serverdelsappar finns i Azure IoT SDK:er .

Förutsättningar

Visual Studio.
En IoT-hubb. Skapa en med CLI eller Azure-portalen.
En registrerad enhet. Registrera en i Azure-portalen.
Kontrollera att port 8883 är öppen i brandväggen. Enhetsexemplet i den här artikeln använder MQTT-protokollet, som kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Anslut ing to IoT Hub (MQTT).

Hämta IoT Hub-anslutningssträng

I den här artikeln skapar du en serverdelstjänst som lägger till önskade egenskaper till en enhetstvilling och sedan frågar identitetsregistret för att hitta alla enheter med rapporterade egenskaper som har uppdaterats i enlighet med detta. Tjänsten behöver behörigheten för tjänstanslutning för att ändra önskade egenskaper för en enhetstvilling, och den behöver registerläsningsbehörighet för att köra frågor mot identitetsregistret. Det finns ingen standardprincip för delad åtkomst som bara innehåller dessa två behörigheter, så du måste skapa en.

Följ dessa steg för att skapa en princip för delad åtkomst som beviljar behörigheter för tjänstanslutning och registerläsning och få en anslutningssträng för den här principen:

I Azure-portalen väljer du Resursgrupper. Välj den resursgrupp där hubben finns och välj sedan din hubb i listan över resurser.
I den vänstra rutan i hubben väljer du Principer för delad åtkomst.
Välj Lägg till princip för delad principåtkomst på den översta menyn ovanför listan med principer.
I fönstret Lägg till princip för delad åtkomst till höger anger du ett beskrivande namn för din princip, till exempel serviceAndRegistryRead. Under Behörigheter väljer du Registerläsning och tjänst Anslut och väljer sedan Lägg till.
Välj din nya princip i listan över principer.
Välj kopieringsikonen för den primära anslutningssträng och spara värdet.

Mer information om principer och behörigheter för delad åtkomst i IoT Hub finns i Åtkomstkontroll och behörigheter.

Skapa en enhetsapp som uppdaterar rapporterade egenskaper

I det här avsnittet skapar du en .NET-konsolapp som ansluter till din hubb som myDeviceId och uppdaterar sedan dess rapporterade egenskaper för att bekräfta att den är ansluten med hjälp av ett mobilnät.

Öppna Visual Studio och välj Skapa nytt projekt.
Välj Konsolapp (.NET Framework) och välj sedan Nästa.
I Konfigurera det nya projektet namnger du projektet Report Anslut ivity och väljer sedan Nästa.
Högerklicka på projektet Report Anslut ivity i Solution Explorer och välj sedan Hantera NuGet-paket.
Behåll standardvärdet .NET Framework och välj sedan Skapa för att skapa projektet.
Välj Bläddra och sök efter och välj Microsoft.Azure.Devices.Client. Välj Installera.

Det här steget laddar ned, installerar och lägger till en referens till Azure IoT-enhetens SDK NuGet-paket och dess beroenden.

Lägg till följande using-uttryck överst i Program.cs-filen:

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Lägg till följande fält i klassen Program. Ersätt {device connection string} med enheten anslutningssträng du såg när du registrerade en enhet i IoT Hub:

static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

Lägg till följande metod i klassen 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);
    }
}

Klientobjektet exponerar alla metoder som du behöver för att interagera med enhetstvillingar från enheten. Koden som visas ovan initierar klientobjektet och hämtar sedan enhetstvillingen för myDeviceId.

Lägg till följande metod i klassen 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);
    }
}

Koden ovan uppdaterar den rapporterade egenskapen för myDeviceId med anslutningsinformationen.

Slutligen lägger du till följande rader till Main-metoden:

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Högerklicka på lösningen i Solution Explorer och välj Ange startprojekt.
I Common Properties Startup Project (Startprojekt för vanliga egenskaper>) väljer du Flera startprojekt. För Rapport Anslut ivitet väljer du Starta som åtgärd. Spara ändringarna genom att välja OK.
Kör den här appen genom att högerklicka på projektet Report Anslut ivity (Rapport Anslut ivity) och välja Felsök och sedan Starta ny instans. Du bör se hur appen hämtar tvillinginformationen och sedan skickar anslutningen som en rapporterad egenskap.

När enheten har rapporterat sin anslutningsinformation bör den visas i båda frågorna.
Högerklicka på projektet AddTagsAndQuery och välj Felsök>Starta ny instans för att köra frågorna igen. Den här gången bör myDeviceId visas i båda frågeresultaten.

Skapa en tjänstapp som uppdaterar önskade egenskaper och frågar tvillingar

I det här avsnittet skapar du en .NET-konsolapp med C#, som lägger till platsmetadata till enhetstvillingen som är associerad med myDeviceId. Appen frågar IoT Hub efter enheter som finns i USA och frågar sedan enheter som rapporterar en mobilnätverksanslutning.

I Visual Studio väljer du Nytt >> filprojekt. I Skapa ett nytt projekt väljer du Konsolapp (.NET Framework) och sedan Nästa.
I Konfigurera det nya projektet ger du projektet namnet AddTagsAndQuery och väljer Nästa.
Acceptera standardversionen av .NET Framework och välj sedan Skapa för att skapa projektet.
Högerklicka på projektet AddTagsAndQuery i Solution Explorer och välj sedan Hantera NuGet-paket.
Välj Bläddra och sök efter och välj Microsoft.Azure.Devices. Välj Installera.

Det här steget laddar ned, installerar och lägger till en referens till Azure IoT Service SDK NuGet-paketet och dess beroenden.
Lägg till följande using-uttryck överst i Program.cs-filen:
```
using Microsoft.Azure.Devices;
```
Lägg till följande fält i klassen Program. Ersätt {iot hub connection string} med IoT Hub-anslutningssträng som du kopierade i Hämta IoT Hub-anslutningssträng.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```

Lägg till följande metod i klassen 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)));
}

Klassen RegistryManager exponerar alla metoder som krävs för att interagera med enhetstvillingar från tjänsten. Den föregående koden initierar först registryManager-objektet , hämtar sedan enhetstvillingen för myDeviceId och uppdaterar slutligen taggarna med önskad platsinformation.

Efter uppdateringen kör den två frågor: den första väljer endast enhetstvillingar för enheter som finns i Redmond43-anläggningen och den andra förfinar frågan för att endast välja de enheter som också är anslutna via mobilt nätverk.

När den föregående koden skapar frågeobjektet anger du ett maximalt antal returnerade dokument. Frågeobjektet innehåller en boolesk egenskap för HasMoreResults som du kan använda för att anropa Metoderna GetNextAsTwinAsync flera gånger för att hämta alla resultat. En metod med namnet GetNextAsJson är tillgänglig för resultat som inte är enhetstvillingar, till exempel resultat av aggregeringsfrågor.

Slutligen lägger du till följande rader till Main-metoden:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Kör det här programmet genom att högerklicka på projektet AddTagsAndQuery och välja Felsökning följt av Starta ny instans. Du bör se en enhet i resultatet för frågan som frågar efter alla enheter som finns i Redmond43 och ingen för frågan som begränsar resultatet till enheter som använder ett mobilnät.

Den här artikeln innehåller följande avsnitt:

Enhetsmetadata har lagts till som taggar från en serverdelsapp
Rapporterad anslutningsinformation för enheter i enhetstvillingen
Efterfrågade information om enhetstvillingen med hjälp av SQL-liknande IoT Hub-frågespråk

Nästa steg

Om du vill ta reda på hur du:

Skicka telemetri från enheter finns i Snabbstart: Skicka telemetri från en IoT Plug and Play-enhet till Azure IoT Hub.
Konfigurera enheter med hjälp av enhetstvillingens önskade egenskaper finns i Självstudie: Konfigurera dina enheter från en serverdelstjänst.
Kontrollera enheter interaktivt, till exempel aktivera en fläkt från en användarkontrollerad app, se Snabbstart: Kontrollera en enhet som är ansluten till en IoT-hubb.

Share via

Kom igång med enhetstvillingar (.NET)

Förutsättningar

Hämta IoT Hub-anslutningssträng

Skapa en enhetsapp som uppdaterar rapporterade egenskaper

Skapa en tjänstapp som uppdaterar önskade egenskaper och frågar tvillingar

Nästa steg

Ytterligare resurser