Planen und Übertragen von Aufträgen (.NET)

  • Artikel

Verwenden Sie Azure IoT Hub zum Planen und Nachverfolgen von Aufträgen, die Millionen von Geräte aktualisieren. Verwenden Sie Aufträge zum:

  • Aktualisieren gewünschter Eigenschaften

  • Aktualisieren von Tags

  • Aufrufen direkter Methoden

Ein Auftrag umschließt eine dieser Aktionen und verfolgt die Ausführung für eine Gruppe von Geräten nach, die anhand einer Gerätezwillingsabfrage definiert wird. Eine Back-End-App kann z.B. einen Auftrag verwenden, um eine direkte Methode auf 10.000 Geräten aufzurufen, die die Geräte neu startet. Sie geben die Gruppe von Geräten mit einer Gerätezwillingsabfrage ein und planen die Ausführung des Auftrags zu einem späteren Zeitpunkt. Der Auftrag verfolgt den Fortschritt nach, während jedes der Geräte die direkte Methode zum Neustart empfängt und ausführt.

Weitere Informationen zu diesen Funktionen finden Sie unter:

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.

In diesem Artikel wird gezeigt, wie Sie zwei .NET (C#)-Konsolen-Apps erstellen:

  • Eine Geräte-App, SimulateDeviceMethods, die eine direkte Methode namens LockDoor implementiert, die von der Back-End-App aufgerufen werden kann.

  • Eine Back-End-App, ScheduleJob, die zwei Aufträge erstellt. Ein Auftrag ruft die direkte Methode lockDoor auf, und ein anderer Auftrag sendet die gewünschten Eigenschaftenupdates an mehrere Geräte.

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.

  • Einen IoT Hub. Erstellen Sie einen mit der CLI oder dem Azure-Portal.

  • Ein registriertes Gerät. Registrieren Sie eins im Azure-Portal.

  • Stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Das Beispielgerät in diesem Artikel verwendet das MQTT-Protokoll, das über Port 8883 kommuniziert. In einigen Netzwerkumgebungen von Unternehmen oder Bildungseinrichtungen ist dieser Port unter Umständen blockiert. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

Erstellen einer simulierten Geräte-App

In diesem Abschnitt erstellen Sie eine .NET-Konsolen-App, die auf eine vom Lösungs-Back-End aufgerufene direkte Methode antwortet.

  1. Wählen Sie in Visual Studio Neues Projekt erstellen und dann die Projektvorlage Konsolen-App (.NET Framework) aus. Klicken Sie auf Weiter, um fortzufahren.

  2. Geben Sie dem Projekt unter Neues Projekt konfigurieren den Namen SimulateDeviceMethods, und wählen Sie Weiter aus.

    Screenshot des Popups „Neues Projekt konfigurieren“ in Visual Studio.

  3. Akzeptieren Sie die Standardversion von .NET Framework, und wählen Sie Erstellen aus, um das Projekt zu erstellen.

  4. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt SimulateDeviceMethods, und wählen Sie NuGet-Pakete verwalten aus.

  5. Wählen Sie im NuGet-Paket-Manager die Option Durchsuchen aus, suchen Sie nach dem Paket Microsoft.Azure.Devices.Client, und wählen Sie es aus. Wählen Sie Installieren aus.

    Screenshot des NuGet-Paket-Managers in Visual Studio.

    In diesem Schritt wird das NuGet-Paket Azure IoT-Geräte-SDK heruntergeladen und installiert sowie ein Verweis auf das Paket und seine Abhängigkeiten hinzugefügt.

  6. 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 Newtonsoft.Json;
using System.Threading.Tasks;
using System.Text;

  7. Fügen Sie der Program -Klasse die folgenden Felder hinzu. Ersetzen Sie den Platzhalterwert durch die Geräteverbindungszeichenfolge, die Sie sich im vorherigen Abschnitt notiert haben:

    static string DeviceConnectionString = "<yourDeviceConnectionString>";
static DeviceClient Client = null;

  8. Fügen Sie den folgenden Code hinzu, um die direkte Methode auf dem Gerät zu implementieren:

    static Task<MethodResponse> LockDoor(MethodRequest methodRequest, object userContext)
{
    Console.WriteLine();
    Console.WriteLine("Locking Door!");
    Console.WriteLine("\nReturning response for method {0}", methodRequest.Name);

    string result = "'Door was locked.'";
    return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

  9. Fügen Sie die folgende Methode hinzu, um den Listener für Gerätezwillinge auf dem Gerät zu implementieren:

    private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
{
    Console.WriteLine("Desired property change:");
    Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
}

  10. Fügen Sie abschließend der Main-Methode folgenden Code hinzu, um die Verbindung mit dem IoT Hub zu öffnen und den Listener der Methode zu initialisieren:

    try
{
    Console.WriteLine("Connecting to hub");
    Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
      TransportType.Mqtt);

    Client.SetMethodHandlerAsync("LockDoor", LockDoor, null);
    Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null);

    Console.WriteLine("Waiting for direct method call and device twin update\n Press enter to exit.");
    Console.ReadLine();

    Console.WriteLine("Exiting...");

    Client.SetMethodHandlerAsync("LockDoor", null, null);
    Client.CloseAsync().Wait();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}

  11. Speichern Sie Ihre Arbeit, und erstellen Sie Ihre Lösung.

Hinweis

Der Einfachheit halber wird in diesem Artikel keine Wiederholungsrichtlinie implementiert. Im Produktionscode sollten Sie Wiederholungsrichtlinien implementieren (z. B. einen erneuten Verbindungsversuch), wie unter Behandeln vorübergehender Fehler beschrieben.

Abrufen der IoT-Hub-Verbindungszeichenfolge

In diesem Artikel erstellen Sie einen Back-End-Dienst, der einen Auftrag zum Aufrufen einer direkten Methode auf einem Gerät sowie einen Auftrag zum Aktualisieren des Gerätezwillings plant und den Fortschritt der beiden Aufträge überwacht. Für diese Vorgänge benötigt Ihr Dienst die Berechtigungen Lesevorgänge in Registrierung und Schreibvorgänge in Registrierung. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens registryReadWrite erstellt, die diese Berechtigungen erteilt.

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

  1. 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.

  2. Wählen Sie im linken Bereich Ihres Hubs SAS-Richtlinien aus.

  3. Wählen Sie in der Liste der Richtlinien die Richtlinie registryRead Write aus.

  4. Kopieren Sie die primäre Verbindungszeichenfolge und speichern Sie den Wert.

    Screenshot: Abrufen der Verbindungszeichenfolge

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

Planen von Aufträgen zum Aufrufen einer direkten Methode und Senden der Gerätezwillingsupdates

In diesem Abschnitt erstellen Sie eine .NET-Konsolen-App (mithilfe von C#), die Aufträge zum Aufrufen der direkten LockDoor-Methode und Senden der Aktualisierungen der gewünschten Eigenschaft an mehrere Geräte verwendet.

  1. Klicken Sie in Visual Studio auf Datei>Neu>Projekt. Wählen Sie unter Neues Projekt erstellen die Option Konsolen-App (.NET Framework) und dann Weiter aus.

  2. Geben Sie Ihrem Projekt in Neues Projekt konfigurieren den Namen ScheduleJob, und wählen Sie Weiter aus.

    Benennen und Konfigurieren des Projekts „ScheduleJob“

    Screenshot des Popups „Neues Projekt konfigurieren“ in Visual Studio, in dem Sie einen Namen hinzufügen.

  3. Akzeptieren Sie die Standardversion von .NET Framework, und wählen Sie Erstellen aus, um das Projekt zu erstellen.

  4. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt ScheduleJob, und wählen Sie dann NuGet-Pakete verwalten aus.

  5. Wählen Sie im NuGet-Paket-Manager die Option Durchsuchen aus, suchen Sie nach Microsoft.Azure.Devices, und wählen Sie diese Option und dann Installieren aus.

    In diesem Schritt wird das NuGet-Paket Azure IoT-Dienst-SDK heruntergeladen und installiert und ein Verweis auf das Paket und seine Abhängigkeiten hinzugefügt.

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

    using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

  7. Fügen Sie die folgende using-Anweisung in den Standardanweisungen hinzu, sofern sie noch nicht vorhanden ist.

    using System.Threading;
using System.Threading.Tasks;

  8. Fügen Sie der Program -Klasse die folgenden Felder hinzu. Ersetzen Sie die Platzhalter durch die IoT-Hub-Verbindungszeichenfolge, die Sie zuvor unter Abrufen der IoT-Hub-Verbindungszeichenfolge kopiert haben, bzw. durch den Namen Ihres Geräts.

    static JobClient jobClient;
static string connString = "<yourIotHubConnectionString>";
static string deviceId = "<yourDeviceId>";

  9. Fügen Sie der Program -Klasse die folgende Methode hinzu:

    public static async Task MonitorJob(string jobId)
{
    JobResponse result;
    do
    {
        result = await jobClient.GetJobAsync(jobId);
        Console.WriteLine("Job Status : " + result.Status.ToString());
        Thread.Sleep(2000);
    } while ((result.Status != JobStatus.Completed) && 
      (result.Status != JobStatus.Failed));
}

  10. Fügen Sie der Program -Klasse die folgende Methode hinzu:

    public static async Task StartMethodJob(string jobId)
{
    CloudToDeviceMethod directMethod = 
      new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
      TimeSpan.FromSeconds(5));

    JobResponse result = await jobClient.ScheduleDeviceMethodAsync(jobId,
        $"DeviceId IN ['{deviceId}']",
        directMethod,
        DateTime.UtcNow,
        (long)TimeSpan.FromMinutes(2).TotalSeconds);

    Console.WriteLine("Started Method Job");
}

  11. Fügen Sie der Program-Klasse eine weitere Methode hinzu:

    public static async Task StartTwinUpdateJob(string jobId)
{
    Twin twin = new Twin(deviceId);
    twin.Tags = new TwinCollection();
    twin.Tags["Building"] = "43";
    twin.Tags["Floor"] = "3";
    twin.ETag = "*";

    twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

    JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
        jobId,
        $"DeviceId IN ['{deviceId}']", 
        twin, 
        DateTime.UtcNow, 
        (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

    Console.WriteLine("Started Twin Update Job");
}

    Hinweis

    Weitere Informationen zur Abfragesyntax finden Sie unter IoT Hub-Abfragesprache.

  12. Fügen Sie abschließend der Main -Methode die folgenden Zeilen hinzu:

    Console.WriteLine("Press ENTER to start running jobs.");
Console.ReadLine();

jobClient = JobClient.CreateFromConnectionString(connString);

string methodJobId = Guid.NewGuid().ToString();

StartMethodJob(methodJobId);
MonitorJob(methodJobId).Wait();
Console.WriteLine("Press ENTER to run the next job.");
Console.ReadLine();

string twinUpdateJobId = Guid.NewGuid().ToString();

StartTwinUpdateJob(twinUpdateJobId);
MonitorJob(twinUpdateJobId).Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

  13. Speichern Sie Ihre Arbeit, und erstellen Sie Ihre Lösung.

Ausführen der Apps

Sie können die Apps nun ausführen.

  1. Klicken Sie im Projektmappen-Explorer von Visual Studio mit der rechten Maustaste auf Ihre Projektmappe, und wählen Sie dann Startprojekte festlegen aus.

  2. Wählen Sie Allgemeine Eigenschaften>Startprojekt und dann Mehrere Startprojekte aus.

  3. Stellen Sie sicher, dass SimulateDeviceMethods ganz oben in der Liste angezeigt wird, gefolgt von ScheduleJob. Legen Sie die Aktionen für beide auf Starten fest, und wählen Sie OK aus.

  4. Führen Sie die Projekte aus, indem Sie auf Starten klicken oder in das Menü Debuggen wechseln und auf Debugging starten klicken.

    Sie sehen die Ausgabe von Geräte- und Back-End-App.

    Führen Sie die Apps aus, um Aufträge zu planen.

Nächste Schritte

In diesem Artikel haben Sie Aufträge geplant, um eine direkte Methode auszuführen und die Eigenschaften des Gerätezwillings zu aktualisieren.

Informationen zur weiteren Erkundung von IoT Hub und Geräteverwaltungsmustern, aktualisieren Sie ein Image unter Device Update for Azure IoT Hub unter Verwendung des Raspberry Pi 3 B+-Referenzimages.