Erste Schritte mit der Modulidentität und dem Modulzwilling von IoT Hub (.NET)

Artikel
10/01/2024

Modulidentitäten und Modulzwillinge ähneln den Geräteidentitäten und Gerätezwillingen von Azure IoT Hub, ermöglichen jedoch eine feinere Granularität. Azure IoT Hub-Geräteidentitäten und -Gerätezwillinge ermöglichen der Back-End-Anwendung die Konfiguration eines Geräts und geben Aufschluss über den Gerätezustand. Modulidentitäten und Modulzwillinge bieten diese Funktionalität für einzelne Komponenten eines Geräts. Auf geeigneten Geräten mit mehreren Komponenten (beispielsweise auf Betriebssystem- oder Firmwaregeräten) ermöglichen Modulidentitäten und Modulzwillinge isolierte Konfiguration und Zustände für jede Komponente.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

Am Ende dieses Artikels verfügen Sie über zwei .NET-Konsolen-Apps:

CreateIdentities: Hiermit werden eine Geräteidentität, eine Modulidentität und ein zugeordneter Sicherheitsschlüssel zum Verbinden Ihrer Geräte- und Modulclients erstellt.
UpdateModuleTwinReportedProperties: Hiermit werden aktualisierte, vom Modulzwilling gemeldete Eigenschaften an Ihren IoT-Hub gesendet.

Hinweis

Weitere Informationen zu den SDK-Tools zum Erstellen von Geräten und Back-End-Apps finden Sie unter Azure IoT SDKs.

Voraussetzungen

Visual Studio.
Ein IoT Hub in Ihrem Azure-Abonnement. Wenn Sie noch keinen Hub haben, können Sie die Schritte unter Erstellen eines IoT-Hubs ausführen.

Modulauthentifizierung

Sie können symmetrische Schlüssel oder X.509-Zertifikate verwenden, um Modulidentitäten zu authentifizieren. Für die X.509-Zertifikatauthentifizierung muss das Zertifikat des Moduls seinen allgemeinen Namen (Common Name, CN) wie CN=<deviceid>/<moduleid> formatiert haben. Zum Beispiel:

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst, der ein Gerät in der Identitätsregistrierung hinzufügt und dann diesem Gerät ein Modul. Ihr Dienst erfordert die Berechtigung Schreibvorgänge in Registrierung. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens registryReadWrite erstellt, die diese Berechtigung erteilt.

Führen Sie zum Abrufen der IoT-Hub-Verbindungszeichenfolge für die Richtlinie registryReadWrite die folgenden Schritte aus:

Wählen Sie im Azure-Portal die Option Ressourcengruppen aus. Wählen Sie die Ressourcengruppe aus, in der sich der Hub befindet, und wählen Sie dann in der Liste der Ressourcen Ihren Hub aus.
Wählen Sie im linken Bereich Ihres Hubs SAS-Richtlinien aus.
Wählen Sie in der Liste der Richtlinien die Richtlinie registryRead Write aus.
Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.

Weitere Informationen zu SAS-Richtlinien und Berechtigungen für IoT-Hubs finden Sie unter Access Control und Berechtigungen.

Wichtig

Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloudsicherheit.

Erstellen einer Modulidentität

In diesem Abschnitt erstellen Sie eine .NET-Konsolen-App, mit der eine Geräte- und eine Modulidentität in der Identitätsregistrierung Ihres Hubs erstellt werden. Ein Gerät oder Modul kann nur dann eine Verbindung mit dem Hub herstellen, wenn in der Identitätsregistrierung ein Eintrag für dieses Gerät vorhanden ist. Weitere Informationen finden Sie im IoT Hub-Entwicklerhandbuch im Abschnitt zur Identitätsregistrierung.

Wenn Sie diese Konsolen-App ausführen, generiert sie eine eindeutige ID und einen eindeutigen Schlüssel für das Gerät und das Modul. Ihr Gerät und Ihr Modul verwenden diese Werte, um sich beim Senden von D2C-Nachrichten an IoT Hub zu identifizieren. Bei den IDs gilt Groß-/Kleinschreibung.

Öffnen Sie Visual Studio, und wählen Sie Neues Projekt erstellen aus.
Wählen Sie in Neues Projekt erstellen die Option Konsolen-App (.NET Framework) aus.
Wählen Sie Weiter aus, um Neues Projekt konfigurieren zu öffnen. Nennen Sie das Projekt CreateIdentities, und wählen Sie dann Weiter aus.
Behalten Sie die .NET-Framework-Standardoption bei, und wählen Sie Erstellen aus, um Ihr Projekt zu erstellen.
Navigieren Sie in Visual Studio zu Tools>NuGet-Paket-Manager>NuGet-Pakete für Projektmappe verwalten. Wählen Sie die Registerkarte Durchsuchen aus.
Suchen Sie Microsoft.Azure.Devices. Wählen Sie diese Option aus, und wählen Sie Installieren aus.

Fügen Sie am Anfang der Datei Program.cs die folgenden using-Anweisungen hinzu:

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;

Fügen Sie der Program -Klasse die folgenden Felder hinzu. Ersetzen Sie den Platzhalterwert durch die IoT Hub-Verbindungszeichenfolge für den Hub, den Sie im vorherigen Abschnitt erstellt haben.
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

Fügen Sie den folgenden Code der Main-Klasse hinzu.

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

Fügen Sie der Program-Klasse die folgenden Methoden hinzu:
```
private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}
```
Mit der AddDeviceAsync-Methode wird eine Geräteidentität mit der ID myFirstDevice erstellt. Falls diese Geräte-ID in der Identitätsregistrierung bereits vorhanden ist, werden mit dem Code lediglich die vorhandenen Geräteinformationen abgerufen. Anschließend zeigt die App den Primärschlüssel für diese Identität an. Sie verwenden diesen Schlüssel in der App für das simulierte Gerät, um eine Verbindung mit Ihrem Hub herzustellen.

Die AddModuleAsync-Methode erstellt eine Modulidentität mit der ID myFirstModule unter dem Gerät myFirstDevice. Falls diese Modul-ID in der Identitätsregistrierung bereits vorhanden ist, werden mit dem Code lediglich die vorhandenen Modulinformationen abgerufen. Anschließend zeigt die App den Primärschlüssel für diese Identität an. Sie verwenden diesen Schlüssel in der App für das simulierte Modul, um eine Verbindung mit Ihrem Hub herzustellen.

Wichtig

Diese Geräte-ID ist unter Umständen in den Protokollen sichtbar, die für den Kundensupport und die Problembehandlung erfasst werden. Stellen Sie also sicher, dass Sie beim Benennen keine sensiblen Informationen verwenden.
Führen Sie diese App aus, und notieren Sie den Geräte- und den Modulschlüssel.

Hinweis

Die Identitätsregistrierung in IoT Hub speichert nur Geräte- und Modulidentitäten, um sicheren Zugriff auf den Hub zu ermöglichen. In der Identitätsregistrierung werden Geräte-IDs und -schlüssel für die Verwendung als Sicherheitsanmeldeinformationen gespeichert. Darüber hinaus wird in der Identitätsregistrierung ein Flag für den Aktivierungszustand des jeweiligen Geräts gespeichert, mit dem Sie den Zugriff für das betreffende Gerät deaktivieren können. Wenn Ihre App das Speichern weiterer gerätespezifischer Metadaten erfordert, sollte dafür ein anwendungsspezifischer Speicher verwendet werden. Es gibt keinen Flag „Aktiviert/deaktiviert“ für Modulidentitäten. Weitere Informationen finden Sie im IoT Hub-Entwicklerhandbuch.

Aktualisieren des Modulzwillings mithilfe des .NET-Geräte-SDKs

Kommunizieren Sie jetzt von Ihrem simulierten Gerät aus mit der Cloud. Sobald eine Modulidentität erstellt wurde, wird implizit ein Gerätezwilling in IoT Hub erstellt. In diesem Abschnitt erstellen Sie eine .NET-Konsolen-App auf Ihrem simulierten Gerät, die die vom Modulzwilling gemeldeten Eigenschaften aktualisiert.

Um Ihre Modulverbindungszeichenfolge abzurufen, navigieren Sie zu Ihrem IoT-Hub, und wählen Sie Geräte aus. Suchen Sie den Eintrag myFirstDevice, und wählen Sie ihn aus, um ihn zu öffnen. Wählen Sie dann den Eintrag myFirstModule aus, um ihn zu öffnen. Kopieren Sie in Details zur Modulidentität die Verbindungszeichenfolge (Primärschlüssel), und speichern Sie sie für die Konsolen-App.

Wichtig

Dieser Artikel enthält Schritte zum Verbinden eines Geräts mithilfe einer Shared Access Signature, was auch als symmetrische Schlüsselauthentifizierung bezeichnet wird. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung eines Geräts mit X.509-Zertifikaten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Verbindungssicherheit.

Fügen Sie Ihrer Projektmappe in Visual Studio ein neues Projekt hinzu, indem Sie Datei>Neu>Projekt auswählen. Wählen Sie in Neues Projekt erstellen die Option Konsolen-App (.NET Framework) und dann Weiter aus.
Geben Sie dem Projekt in Neues Projekt konfigurieren den Namen UpdateModuleTwinReportedProperties, und wählen Sie dann Weiter aus.
Behalten Sie die .NET-Framework-Standardoption bei, und wählen Sie Erstellen aus, um Ihr Projekt zu erstellen.
Navigieren Sie in Visual Studio zu Tools>NuGet-Paket-Manager>NuGet-Pakete für Projektmappe verwalten. Wählen Sie die Registerkarte Durchsuchen aus.
Suchen Sie nach Microsoft.Azure.Devices.Client, und wählen Sie diese Option aus. Wählen Sie dann Installieren aus.

Fügen Sie am Anfang der Datei Program.cs die folgenden using-Anweisungen hinzu:

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

Fügen Sie der Program -Klasse die folgenden Felder hinzu. Ersetzen Sie den Platzhalterwert durch die Verbindungszeichenfolge des Moduls.

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

Fügen Sie die folgende Methode OnDesiredPropertyChanged der Klasse Program hinzu:

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

Fügen Sie der Main-Methode die folgenden Zeilen hinzu:

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

Jetzt wissen Sie, wie Sie den Modulzwilling abrufen und gemeldete Eigenschaften mit dem AMQP-Protokoll aktualisieren können.

Optional können Sie diese Anweisungen der Main-Methode hinzufügen, um ein Ereignis von Ihrem Modul an IoT Hub zu senden. Platzieren Sie diese Zeilen unterhalb des Blocks try catch.

Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");

Ausführen der Apps

Sie können die Apps nun ausführen.

Klicken Sie in Visual Studio im Projektmappen-Explorer mit der rechten Maustaste auf Ihre Projektmappe, und wählen Sie Startprojekte festlegen aus.
Wählen Sie unter Allgemeine Eigenschaften die Option Startprojekt aus.
Wählen Sie Mehrere Startprojekte, dann Starten als Aktion für die App und dann OK aus, um die Änderungen zu akzeptieren.
Drücken SieF5, um die Apps zu starten.

Nächste Schritte

Informationen zu den weiteren ersten Schritten mit IoT Hub und zum Kennenlernen anderer IoT-Szenarien finden Sie in den folgenden Artikeln:

Freigeben über

Erste Schritte mit der Modulidentität und dem Modulzwilling von IoT Hub (.NET)

Voraussetzungen

Modulauthentifizierung

Abrufen der IoT-Hub-Verbindungszeichenfolge

Erstellen einer Modulidentität

Aktualisieren des Modulzwillings mithilfe des .NET-Geräte-SDKs

Ausführen der Apps

Nächste Schritte

Feedback

Zusätzliche Ressourcen