Kom igång med IoT Hub-modulidentitet och modultvilling (.NET)

Artikel
10/01/2024

Modulidentiteter och modultvillingar liknar enhetsidentitet och enhetstvilling i Azure IoT Hub, men har en större detaljnivå. Även om Azure IoT Hub-enhetsidentiteten och enhetstvillingen gör det möjligt för serverdelsprogrammet att konfigurera en enhet och ge insyn i enhetens villkor, ger en modulidentitet och modultvilling dessa funktioner för enskilda komponenter på en enhet. På kompatibla enheter med flera komponenter, till exempel operativsystemenheter eller enheter för inbyggd programvara, tillåter modulidentiteter och modultvillingar isolerade konfigurationer och villkor för varje komponent.

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.

I slutet av den här artikeln har du två .NET-konsolappar:

CreateIdentiteter: skapar en enhetsidentitet, en modulidentitet och en tillhörande säkerhetsnyckel för att ansluta dina enhets- och modulklienter.
UpdateModuleTwinReportedProperties: skickar uppdaterade modultvillingar, rapporterade egenskaper till din IoT-hubb.

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 i din Azure-prenumeration. Om du inte har någon hubb ännu kan du följa stegen i Skapa en IoT-hubb.

Modulautentisering

Du kan använda symmetriska nycklar eller X.509-certifikat för att autentisera modulidentiteter. För X.509-certifikatautentisering måste modulens certifikat ha sitt gemensamma namn (CN) formaterat som CN=<deviceid>/<moduleid>. Till exempel:

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

Hämta IoT Hub-anslutningssträng

I den här artikeln skapar du en serverdelstjänst som lägger till en enhet i identitetsregistret och sedan lägger till en modul på enheten. Tjänsten kräver registerskrivningsbehörigheten. Som standard skapas varje IoT-hubb med en princip för delad åtkomst med namnet registryReadWrite som ger den här behörigheten.

Följ dessa steg för att hämta IoT Hub-anslutningssträng för registryReadWrite-principen:

I Azure Portal 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.
I listan över principer väljer du registerReadWrite-principen .
Kopiera 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.

Viktigt!

Den här artikeln innehåller steg för att ansluta till en tjänst med hjälp av en signatur för delad åtkomst. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men autentisering till en tjänst med Microsoft Entra-ID eller hanterade identiteter är en säkrare metod. Mer information finns i Metodtips för > säkerhet Molnsäkerhet.

Skapa en modulidentitet

I det här avsnittet skapar du en .NET-konsolapp som skapar en enhetsidentitet och en modulidentitet i identitetsregistret i hubben. En enhet eller modul kan inte ansluta till hubben om den inte har en post i identitetsregistret. Mer information finns i avsnittet Identitetsregister i utvecklarguiden för IoT Hub.

När du kör den här konsolappen, genereras ett unikt ID och en unik nyckel för både enheten och modulen. Enheten och modulen använder dessa värden för att identifiera sig när de skickar meddelanden från enhet till moln till IoT Hub. ID:n är skiftlägeskänsliga.

Öppna Visual Studio och välj Skapa ett nytt projekt.
I Skapa ett nytt projekt väljer du Konsolapp (.NET Framework).
Välj Nästa för att öppna Konfigurera ditt nya projekt. Ge projektet namnet CreateIdentities och välj sedan Nästa.
Behåll standardalternativet .NET Framework och välj Skapa för att skapa projektet.
Öppna Verktyg>NuGet Package Manager>Hantera NuGet-paket för lösning i Visual Studio. Välj fliken Bläddra.
Sök efter Microsoft.Azure.Devices. Välj den och välj sedan Installera.

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

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

Lägg till följande fält i klassen Program. Ersätt platshållarvärdet med IoT Hub-anslutningssträngen som du skapade i föregående avsnitt.

const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";

Lägg till följande kod i klassen Main .

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

Lägg till följande metoder i klassen Program:

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);
}

Metoden AddDeviceAsync skapar en enhetsidentitet med ID myFirstDevice. Om det enhets-ID:t redan finns i identitetsregistret hämtar koden helt enkelt den befintliga enhetsinformationen. Appen visar sedan den primära nyckeln för den identiteten. Du använder den här nyckeln i den simulerade enhetsappen för att ansluta till din hubb.

Metoden AddModuleAsync skapar en modulidentitet med ID myFirstModule under enheten myFirstDevice. Om modul-ID:t redan finns i identitetsregistret hämtar koden helt enkelt den befintliga modulinformationen. Appen visar sedan den primära nyckeln för den identiteten. Du använder den här nyckeln i den simulerade modulappen för att ansluta till din hubb.

Viktigt!

Enhets-ID visas kanske i de loggar som samlas in för support och felsökning, så se till att undvika känslig information när du namnger det.

Kör den här appen och anteckna enhetsnyckeln och modulnyckeln.

Kommentar

IoT Hub-identitetsregistret lagrar endast enhets- och modulidentiteter för säker åtkomst till hubben. Enhets-ID:n och nycklar lagras i identitetsregistret och används som autentiseringsuppgifter. I identitetsregistret lagras också en aktiverad/inaktiverad-flagga för varje enhet som du kan använda till att inaktivera enhetens åtkomst. Om din app behöver lagra andra enhetsspecifika metadata bör den använda ett programspecifikt arkiv. Det finns ingen aktiverad/inaktiverad flagga för modulidentiteter. Mer information finns i utvecklarhandboken för IoT Hub.

Uppdatera modultvillingen med SDK för .NET-enheter

Nu ska vi kommunicera med molnet från din simulerade enhet. När en modulidentitet har skapats skapas en modultvilling implicit i IoT Hub. I det här avsnittet skapar du en .NET-konsolapp på din simulerade enhet som uppdaterar modultvillingens rapporterade egenskaper.

Om du vill hämta modulen anslutningssträng navigerar du till din IoT-hubb och väljer sedan Enheter. Leta upp och välj myFirstDevice för att öppna den och välj sedan myFirstModule för att öppna den. I Modulidentitetsinformation kopierar du anslutningssträngen (primärnyckeln) och sparar den för konsolappen.

Viktigt!

Den här artikeln innehåller steg för att ansluta en enhet med en signatur för delad åtkomst, även kallad symmetrisk nyckelautentisering. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men att autentisera en enhet med X.509-certifikat är en säkrare metod. Mer information finns i Metodtips > för säkerhet Anslutningssäkerhet.

I Visual Studio lägger du till ett nytt projekt i din lösning genom att välja Fil>nytt>projekt. I Skapa ett nytt projekt väljer du Konsolapp (.NET Framework) och sedan Nästa.
I Konfigurera det nya projektet namnger du projektet UpdateModuleTwinReportedProperties och väljer sedan Nästa.
Behåll standardalternativet .NET Framework och välj Skapa för att skapa projektet.
Öppna Verktyg>NuGet Package Manager>Hantera NuGet-paket för lösning i Visual Studio. Välj fliken Bläddra.
Sök efter och välj Microsoft.Azure.Devices.Client och välj sedan Installera.

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

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

Lägg till följande fält i klassen Program. Ersätt platshållarens värde med modulens anslutningssträng.

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);
}

Lägg till följande metod OnDesiredPropertyChanged till klassen Program:

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);
    }

Lägg till följande rader i main-metoden :

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();
}

Nu vet du hur du hämtar modultvillingen och uppdaterar rapporterade egenskaper med AMQP-protokollet.

Du kan också lägga till dessa instruktioner i main-metoden för att skicka en händelse till IoT Hub från din modul. Placera dessa rader under try catch blocket.

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.");

Köra apparna

Nu kan du köra apparna.

Högerklicka på lösningen i Solution Explorer i Visual Studio och välj sedan Ange StartUp-projekt.
Under Vanliga egenskaper väljer du Startprojekt.
Välj Flera startprojekt och välj sedan Starta som åtgärd för apparna och OK för att acceptera ändringarna.
Starta apparna genom att trycka på F5 .

Nästa steg

Mer information om hur du kan komma igång med IoT Hub och utforska andra IoT-scenarier finns här:

Connecting your device (Komma igång med enhetshantering)
Komma igång med IoT Edge

Dela via

Kom igång med IoT Hub-modulidentitet och modultvilling (.NET)

Förutsättningar

Modulautentisering

Hämta IoT Hub-anslutningssträng

Skapa en modulidentitet

Uppdatera modultvillingen med SDK för .NET-enheter

Köra apparna

Nästa steg

Feedback

Ytterligare resurser