Freigeben über

Tutorial: Entwickeln IoT Edge-Modulen mit Linux-Containern mithilfe von IoT Edge für Linux unter Windows

  • Artikel

Gilt für: Häkchen für IoT Edge 1.5 IoT Edge 1.5 IoT Edge 1.4 Häkchen IoT Edge 1.4

Wichtig

IoT Edge 1.5 LTS und IoT Edge 1.4 LTS sind unterstützte Releases. Das Ende der Lebensdauer von IoT Edge 1.4 LTS wird am 12. November 2024 erreicht. Wenn Sie ein früheres Release verwenden, finden Sie weitere Informationen unter Aktualisieren von IoT Edge.

In diesem Tutorial wird das Entwickeln, Debuggen und Bereitstellen von eigenem Code auf einem Azure IoT Edge-Gerät mithilfe von IoT Edge für Linux unter Windows und Visual Studio 2022 beschrieben. Sie lernen anhand der Bereitstellung eines C#-Moduls auf einem Linux-Gerät das gängigste Entwicklerszenario für IoT Edge-Lösungen kennen. Sie stellen ein benutzerdefiniertes IoT Edge-Modul bereit, das in einem Linux-Container unter Windows ausgeführt wird, und debuggen es. Auch wenn Sie die Verwendung einer anderen Sprache oder die Bereitstellung eines Azure-Diensts planen, ist dieses Tutorial nützlich, um mehr über Entwicklungstools und -konzepte zu erfahren.

Dieses Tutorial enthält Schritte für zwei IoT Edge-Entwicklungstools:

  • Die Azure IoT Edge Dev Tool-CLI ist das bevorzugte Tool für die Entwicklung.
  • Die Azure IoT Edge Tools-Erweiterung für Visual Studio befindet sich im Wartungsmodus.

Verwenden Sie die Auswahlschaltfläche am Anfang dieses Tutorials, um die Toolversion auszuwählen.

In diesem Tutorial lernen Sie Folgendes:

  • Einrichten Ihres Entwicklungscomputers
  • Verwenden Sie die IoT Edge-Tools zum Erstellen eines neuen Projekts.
  • Erstellen Ihres Projekts als Container und Speichern in einer Azure-Containerregistrierung
  • Bereitstellen Ihres Codes auf einem IoT Edge-Gerät

Voraussetzungen

In diesem Tutorial wird davon ausgegangen, dass Sie einen Windows-Computer als Entwicklungscomputer verwenden. Auf Windows-Computern können Sie entweder Windows- oder Linux-Module entwickeln. Dieses Tutorial führt Sie durch die Entwicklung von Linux-Containern mithilfe von IoT Edge für Linux unter Windows zum Erstellen und Bereitstellen der Module.

Vorbereitungen

  • Installieren Sie IoT Edge für Linux unter Windows.

  • Lesen Sie den Schnellstart Bereitstellen Ihres ersten IoT Edge-Moduls auf einem Windows-Gerät.

  • Laden Sie das .NET Core SDK herunter.

  • Installieren oder ändern Sie Visual Studio 2022 auf Ihrem Entwicklungscomputer. Wählen Sie die Workloadoptionen Azure-Entwicklung und Desktopentwicklung mit C++ aus.

  • Wenn Ihre Visual Studio 2022-Installation bereit ist, laden Sie die Azure IoT Edge Tools aus dem Visual Studio Marketplace herunter und installieren sie.

    Sie können die Azure IoT Edge Tools-Erweiterung verwenden, um Ihre IoT Edge-Lösung zu erstellen und kompilieren. Das bevorzugte Entwicklungstool ist die Azure IoT Edge Dev Tool-CLI. Die Erweiterung enthält die Azure IoT Edge-Projektvorlagen, die Sie zum Erstellen des Visual Studio-Projekts verwenden. Derzeit müssen Sie die Erweiterung unabhängig vom verwendeten Entwicklungstool installieren.

    Tipp

    Wenn Sie Visual Studio 2019 verwenden, müssen Sie Azure IoT Edge Tools für Visual Studio 2019 aus dem Visual Studio Marketplace herunterladen und installieren.

  • Erstellen Sie einen IoT-Hub in Azure als Cloudressource im Tarif „Free“ oder „Standard“.

Wenn Sie kein Azure-Abonnement haben, erstellen Sie ein kostenloses Azure-Konto, bevor Sie beginnen.

Wichtige Begriffe

In diesem Tutorial wird Schritt für Schritt die Entwicklung eines IoT Edge-Moduls beschrieben. Ein IoT Edge-Modul ist ein Container mit ausführbarem Code. Sie können ein oder mehrere Module auf einem IoT Edge-Gerät bereitstellen. Mit Modulen werden bestimmte Aufgaben durchgeführt, z. B. das Erfassen der Daten von Sensoren, das Bereinigen oder Analysieren von Daten oder das Senden von Nachrichten an einen IoT-Hub. Weitere Informationen finden Sie unter Grundlegendes zu Azure IoT Edge-Modulen.

Beim Entwickeln von IoT Edge-Modulen ist es wichtig, dass Sie den Unterschied zwischen dem Entwicklungscomputer und dem IoT Edge-Zielgerät verstehen, auf dem das Modul letztendlich bereitgestellt wird. Der Container, den Sie für Ihren Modulcode erstellen, muss mit dem Betriebssystem (BS) des Zielgeräts übereinstimmen.

Am häufigsten kommt beispielsweise ein Szenario vor, bei dem ein Modul auf einem Windows-Computer entwickelt wird, das für ein Linux-Gerät mit IoT Edge bestimmt ist. In diesem Fall ist das Containerbetriebssystem Linux.

Denken Sie beim Durcharbeiten dieses Tutorials an den Unterschied zwischen dem Betriebssystem des Entwicklungscomputers und dem Betriebssystem des Containers. In diesem Tutorial verwenden Sie Ihren Windows-Host für die Entwicklung und die VM mit IoT Edge für Linux unter Windows zum Erstellen und Bereitstellen der Module.

In diesem Tutorial geht es um Geräte, auf denen IoT Edge mit Linux-Containern ausgeführt wird. Sie können Ihr bevorzugtes Betriebssystem verwenden, solange auf Ihrem Entwicklungscomputer Linux-Container ausgeführt werden. Es wird empfohlen, Visual Studio für die Entwicklung mit Linux-Containern zu nutzen. Dies ist auch die Vorgehensweise in diesem Tutorial. Alternativ können Sie Visual Studio Code verwenden, aber zwischen den beiden Tools gibt es Unterschiede in Bezug auf die Unterstützung. Weitere Informationen finden Sie unter Entwickeln von Azure IoT Edge-Modulen mit Visual Studio Code.

Einrichten von Docker CLI und Docker-Engine für die Remoteverbindung

Da IoT Edge-Module als Container verpackt werden, benötigen Sie auf Ihrem Entwicklungscomputer eine Container-Engine zum Erstellen und Verwalten der Container.

Die VM mit IoT Edge für Linux unter Windows enthält bereits eine Instanz der Docker-Engine. In diesem Tutorial erfahren Sie, wie Sie eine Remoteverbindung vom Windows-Entwicklercomputer mit der Docker-Instanz der VM mit IoT Edge für Linux unter Windows herstellen. Mit dieser Remoteverbindung umgehen Sie die Abhängigkeit von Docker Desktop für Windows.

Konfigurieren der Docker CLI

Der erste Schritt besteht im Konfigurieren der Docker CLI auf dem Windows-Entwicklungscomputer, um eine Verbindung mit der Docker-Remote-Engine herstellen zu können:

  1. Laden Sie die vorkompilierte docker.exe-Version der Docker CLI von Chocolatey herunter. Sie können das offizielle cli-Projekt auch von GitHub herunterladen und es gemäß den Repositoryanweisungen kompilieren.

  2. Extrahieren Sie docker.exe in ein Verzeichnis auf Ihrem Entwicklungscomputer, z. B. C:\Docker\bin.

  3. Öffnen Sie Über Ihren PC>Systeminformationen>Erweiterte Systemeinstellungen.

  4. Wählen Sie Erweitert>Umgebungsvariablen aus. Wählen Sie unter Benutzervariablen die Option Pfad aus.

  5. Bearbeiten Sie die Variable Pfad, und fügen Sie den Speicherort von docker.exe hinzu.

  6. Öffnen Sie eine PowerShell-Sitzung mit erhöhten Rechten.

  7. Überprüfen Sie mithilfe des folgenden Befehls, ob auf die Docker CLI zugegriffen werden kann:

    docker --version

    Wenn Sie alles erfolgreich konfiguriert haben, sollte die Ausgabe des Befehls die Docker-Version enthalten. Dieser sollte ungefähr wie Docker version 20.10.12, build e91ed57 aussehen.

Konfigurieren der Docker-Engine

Im zweiten Schritt konfigurieren Sie die Docker-Engine der VM mit IoT Edge für Linux unter Windows so, dass externe Verbindungen akzeptiert werden, und fügen die entsprechenden Firewallregeln hinzu.

Warnung

Die Docker-Engine für externe Verbindungen verfügbar zu machen, kann zu erhöhten Sicherheitsrisiken führen. Sie sollten diese Konfiguration nur zu Entwicklungszwecken verwenden. Stellen Sie sicher, dass Sie die Konfiguration auf die Standardeinstellungen zurücksetzen, nachdem die Entwicklung abgeschlossen ist.

  1. Öffnen Sie eine PowerShell-Sitzung mit erhöhten Rechten, und führen Sie die folgenden Befehle aus:

    # Configure the IoT Edge for Linux on Windows VM Docker engine to accept external connections, and add the appropriate firewall rules.
Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"

# Create a copy of the IoT Edge for Linux on Windows VM _docker.service_ in the system folder.
Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"

# Replace the service execution line to listen for external connections.
Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g'  /etc/systemd/system/docker.service"

# Reload the IoT Edge for Linux on Windows VM services configurations.
Invoke-EflowVmCommand "sudo systemctl daemon-reload"

# Reload the Docker engine service.
Invoke-EflowVmCommand "sudo systemctl restart docker.service"

# Check that the Docker engine is listening to external connections.
Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"

    Dies ist ein Beispiel für eine Ausgabe:

    PS C:\> # Configure the IoT Edge for Linux on Windows virtual machine Docker engine to accept external connections, and add the appropriate firewall rules.
PS C:\> Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
PS C:\>
PS C:\> # Create a copy of the IoT Edge for Linux on Windows VM docker.service in the system folder.
PS C:\> Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
PS C:\>
PS C:\> # Replace the service execution line to listen for external connections.
PS C:\> Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g' /etc/systemd/system/docker.service"
PS C:\>
PS C:\> # Reload the IoT Edge for Linux on Windows VM services configurations.
PS C:\> Invoke-EflowVmCommand "sudo systemctl daemon-reload"
PS C:\>
PS C:\> # Reload the Docker engine service.
PS C:\> Invoke-EflowVmCommand "sudo systemctl restart docker.service"
PS C:\>
PS C:\> # Check that the Docker engine is listening to external connections.
PS C:\> Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
tcp6       0      0 :::2375                 :::*                    LISTEN      2790/dockerd

Testen der Verbindung

Der letzte Setupschritt besteht darin, die Docker-Verbindung mit der Docker-Engine der VM mit IoT Edge für Linux unter Windows zu testen:

  1. Rufen Sie die IP-Adresse der VM mit IoT Edge für Linux unter Windows ab:

    Get-EflowVmAddr

    Tipp

    Wenn die VM mit IoT Edge für Linux unter Windows ohne statische IP-Adresse bereitgestellt wurde, ändert sich die IP-Adresse möglicherweise bei Neustarts des Windows-Hostbetriebssystems oder bei Änderungen am Netzwerk. Achten Sie darauf, dass Sie bei jedem Herstellen einer Remoteverbindung mit der Docker-Engine der VM mit IoT Edge für Linux unter Windows die richtige IP-Adresse verwenden.

    Dies ist ein Beispiel für eine Ausgabe:

    PS C:\> Get-EflowVmAddr
[03/15/2022 15:22:30] Querying IP and MAC addresses from virtual machine (DESKTOP-J1842A1-EFLOW)
 - Virtual machine MAC: 00:15:5d:6f:da:78
 - Virtual machine IP : 172.31.24.105 retrieved directly from virtual machine
00:15:5d:6f:da:78
172.31.24.105

  2. Stellen Sie eine Verbindung mit der Docker-Engine der VM mit IoT Edge für Linux unter Windows her, und führen Sie den Beispielcontainer hello-world aus. Ersetzen Sie <EFLOW-VM-IP> durch die IP-Adresse der VM mit IoT Edge für Linux unter Windows, die Sie im vorherigen Schritt abgerufen haben.

    docker -H tcp://<EFLOW-VM-IP>:2375 run --rm hello-world

    Nach Abschluss des Downloads des Containers wird dieser ausgeführt und generiert folgende Ausgabe:

    PS C:\> docker -H tcp://172.31.24.105:2375 run --rm hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
2db29710123e: Pull complete
Digest: sha256:4c5f3db4f8a54eb1e017c385f683a2de6e06f75be442dc32698c9bbe6c861edd
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you're currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Erstellen eines Azure IoT Edge-Projekts

Die IoT Edge-Projektvorlage in Visual Studio erstellt eine Projektmappe, die Sie auf IoT Edge-Geräten bereitstellen können. Führen Sie die folgenden Schritte aus, um eine Azure IoT Edge-Projektmappe zu erstellen und dann das erste Modul in dieser Projektmappe zu generieren. Jede IoT Edge-Lösung kann mehrere Module enthalten.

Wichtig

Die von Visual Studio erstellte Struktur eines IoT Edge-Projekts ist mit der in Visual Studio Code nicht identisch.

Derzeit unterstützt die IoT Edge Dev Tool-CLI das Erstellen des Visual Studio-Projekttyps nicht. Sie müssen die Azure IoT Edge Tools-Erweiterung verwenden, um das Visual Studio-Projekt zu erstellen.

  1. Erstellen Sie in Visual Studio ein neues Projekt, indem Sie auf der Startseite Neues Projekt erstellen oder auf der Symbolleiste die Schaltfläche Neues Projekt auswählen.

  2. Suchen Sie auf der Seite Neues Projekt erstellen nach Azure IoT Edge. Wählen Sie das Projekt aus, das der Plattform (Linux IoT Edge-Modul) und Architektur für Ihr IoT Edge-Gerät entspricht, und wählen Sie dann Weiter aus.

  3. Geben Sie auf der Seite Neues Projekt konfigurieren einen Namen und den Speicherort für Ihr Projekt ein, und wählen Sie dann Erstellen aus.

  4. Wählen Sie im Dialogfeld Modul hinzufügen den Typ des Moduls aus, das Sie entwickeln möchten. Sie können auch Vorhandenes Modul auswählen, um Ihrer Bereitstellung ein vorhandenes IoT Edge-Modul hinzuzufügen.

  5. Geben Sie in Modulname einen Namen für Ihr Modul ein.

  6. Geben Sie unter Repository-URL den Namen des Imagerepositorys des Moduls an. Visual Studio füllt den Modulnamen automatisch mit localhost:5000/<Name Ihres Moduls> aus. Ersetzen Sie ihn durch Ihre eigenen Registrierungsinformationen.

    Wenn Sie eine lokale Docker-Registrierung zum Testen verwenden, können Sie localhost nutzen. Nutzen Sie den Anmeldeserver aus Ihren Registrierungseinstellungen, wenn Sie Azure Container Registry verwenden. Der Anmeldeserver hat die Form <Registrierungsname>.azurecr.io. Ersetzen Sie nur den Teil localhost:5000 der Zeichenfolge, damit das endgültige Ergebnis die folgende Form hat: <Registrierungsname>.azurecr.io/<Name Ihres Moduls>.

  7. Wählen Sie Hinzufügen aus, um Ihr Modul dem Projekt hinzuzufügen.

    Screenshot der Auswahlmöglichkeiten zum Hinzufügen einer Anwendung und eines Moduls zu einer Visual Studio-Projektmappe

    Hinweis

    Wenn Sie bereits ein IoT Edge-Projekt haben, können Sie die Repository-URL ändern, indem Sie die Datei module.json öffnen. Sie finden die Repository-URL in der repository.Eigenschaft der JSON-Datei.

Nun enthält Ihre Visual Studio-Projektmappe ein IoT Edge-Projekt und ein IoT Edge-Modul.

Projektstruktur

In Ihrer Projektmappe gibt es zwei Ordner auf Projektebene: einen Hauptprojektordner und einen Modulordner. Beispielsweise verfügen Sie möglicherweise über einen Hauptprojektordner namens AzureIotEdgeApp1 und einen Modulordner mit dem Namen IotEdgeModule1.

Der Hauptprojektordner enthält Ihr Bereitstellungsmanifest. Das Bereitstellungsmanifest ist ein JSON-Dokument, in dem die Module beschrieben werden, die auf dem IoT Edge-Zielgerät konfiguriert werden sollen.

Der Modulordner enthält eine Datei für den Modulcode. Je nach ausgewählter Sprache heißt sie entweder Program.cs oder main.c. Dieser Ordner enthält auch eine Datei mit dem Namen module.json, die die Metadaten Ihres Moduls beschreibt. Verschiedene Docker-Dateien stellen die Informationen bereit, die zum Erstellen Ihres Moduls als Windows- oder Linux-Container erforderlich sind.

Bereitstellungsmanifest Ihres Projekts

Das Bereitstellungsmanifest, das Sie bearbeiten, heißt deployment.debug.template.json. Diese Datei ist eine Vorlage eines IoT Edge-Bereitstellungsmanifests, das alle Module definiert, die auf einem Gerät ausgeführt werden. In der Datei wird auch definiert, wie die Module miteinander kommunizieren. Weitere Informationen zu Bereitstellungsmanifesten finden Sie unter Bereitstellen von Modulen und Einrichten von Routen in IoT Edge.

Die Bereitstellungsvorlage enthält Folgendes:

  • Die beiden Runtimemodule edgeAgent und edgeHub
  • Das benutzerdefinierte Modul, das Sie in diesem Visual Studio-Projekt erstellt haben
  • Ein Modul namens SimulatedTemperatureSensor. Dieses Standardmodul generiert simulierte Daten, mit denen Sie Ihre Module testen können (oder die Sie löschen können, wenn sie nicht erforderlich sind). Der Quellcode „SimulatedTemperatureSensor.csproj“ veranschaulicht die Funktionsweise des simulierten Temperatursensors.

Festlegen der Version der IoT Edge-Runtime

Zurzeit ist Version 1.4 die neueste stabile Runtimeversion. Aktualisieren Sie die IoT Edge-Runtimeversion auf das neueste stabile Release oder die Zielversion für Ihre Geräte:

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Namen Ihres Hauptprojekts, und wählen Sie IoT Edge-Runtimeversion festlegen aus.

    Screenshot der Auswahlmöglichkeiten zum Festlegen einer IoT Edge-Runtimeversion

  2. Verwenden Sie das Dropdownmenü, um die Runtimeversion auszuwählen, die auf Ihren IoT Edge-Geräten ausgeführt wird. Wählen Sie anschließend OK aus, um Ihre Änderungen zu speichern. Wenn Sie keine Änderungen vorgenommen haben, wählen Sie Abbrechen aus.

    Derzeit enthält die Erweiterung keine Auswahl für die neuesten Runtimeversionen. Wenn Sie die Runtimeversion auf eine höhere Version als 1.2 festlegen möchten, öffnen Sie die Bereitstellungsmanifestdatei deployment.debug.template.json. Ändern Sie die Runtimeversion für die Systemruntime-Modulimages edgeAgent und edgeHub. Wenn Sie beispielsweise die IoT Edge-Runtimeversion 1.4 verwenden möchten, ändern Sie in der Bereitstellungsmanifestdatei die folgenden Zeilen:

    "systemModules": {
   "edgeAgent": {
    //...
      "image": "mcr.microsoft.com/azureiotedge-agent:1.4"
    //...
   "edgeHub": {
   //...
      "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
   //...

  3. Wenn Sie die Version geändert haben, generieren Sie Ihr Bereitstellungsmanifest erneut, indem Sie mit der rechten Maustaste auf den Namen Ihres Projekts klicken und Bereitstellung für IoT Edge generieren auswählen. Mit diesem Schritt wird ein Bereitstellungsmanifest basierend auf Ihrer Bereitstellungsvorlage generiert. Das Manifest wird im Ordner config Ihres Visual Studio-Projekts gespeichert.

  1. Öffnen Sie die Bereitstellungsmanifestdatei deployment.debug.template.json.

  2. Ändern Sie die Runtimeversion für die Systemruntime-Modulimages edgeAgent und edgeHub. Wenn Sie z. B. die IoT Edge-Runtimeversion 1.4 verwenden möchten, ändern Sie in der Bereitstellungsmanifestdatei die folgenden Zeilen:

    "systemModules": {
    "edgeAgent": {
    //...
        "image": "mcr.microsoft.com/azureiotedge-agent:1.4",
    //...
    "edgeHub": {
    //...
        "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
    //...

Einrichten einer Visual Studio 2022-Remoteinstanz der Docker-Engine

Konfigurieren Sie die Azure IoT Edge Tools-Erweiterung für die Verwendung der Remote-Docker-Engine, die auf der VM mit IoT Edge für Linux unter Windows ausgeführt wird:

  1. Wählen Sie Extras >Azure IoT Edge Tools>IoT Edge-Tooleinstellungen aus.

  2. Ersetzen Sie den localhost-Wert DOCKER_HOST durch die IP-Adresse der VM mit IoT Edge für Linux unter Windows. Wenn Sie die IP-Adresse nicht zur Hand haben, verwenden Sie auf der VM mit IoT Edge für Linux unter Windows das PowerShell-Cmdlet Get-EflowVmAddr, um sie abzurufen. Wenn die IP-Adresse der VM mit IoT Edge für Linux unter Windows beispielsweise 172.20.1.100 ist, sollte der neue Wert tcp://172.20.1.100:2375 lauten.

    Screenshot der Einstellungen für IoT Edge Tools

  3. Wählen Sie OK aus.

Entwickeln Ihres Moduls

Wenn Sie ein neues Modul hinzufügen, enthält es Standardcode, der sofort genutzt und auf einem Gerät bereitgestellt werden kann, sodass Sie mit dem Testen beginnen können, ohne Code zu bearbeiten. Der Modulcode befindet sich im Modulordner in einer Datei mit dem Namen Program.cs (für C#) oder main.c (für C).

In der Standardprojektmappe werden die simulierten Daten aus dem SimulatedTemperatureSensor-Modul an Ihr Modul weitergeleitet. Das Modul übernimmt die Eingabe und sendet sie dann an Azure IoT Hub.

Wenn Sie bereit sind, die Modulvorlage mit Ihrem eigenen Code anzupassen, erstellen Sie mit den Azure IoT Hub SDKs weitere Module, die die wesentlichen Anforderungen für IoT-Lösungen berücksichtigen. Zu diesen Anforderungen können z. B. Sicherheit, Geräteverwaltung und Zuverlässigkeit gehören.

Erstellen und Pushen eines einzelnen Moduls

In der Regel möchten Sie jedes Modul testen und debuggen, bevor Sie es in einer Gesamtlösung mit mehreren Modulen ausführen. Da die Lösung mithilfe der Docker-Engine erstellt oder debuggt wird, die auf der VM mit IoT Edge für Linux unter Windows ausgeführt wird, besteht der erste Schritt darin, das Modul zu erstellen und zu veröffentlichen, um das Remotedebuggen zu ermöglichen:

  1. Wählen Sie im Projektmappen-Explorer den Modulprojektordner aus (z. B. myIotEdgeModule).

  2. Legen Sie das benutzerdefinierte Modul als Startprojekt fest. Wählen Sie im Menü Projekt>Als Startprojekt festlegen aus.

  3. Zum Debuggen des C#-Linux-Moduls müssen Sie die Datei Dockerfile.amd64.debug aktualisieren, um den SSH-Dienst zu aktivieren. Aktualisieren Sie die Datei Dockerfile.amd64.debug, um die folgende Vorlage zu verwenden: Dockerfile for Azure IoT Edge AMD64 C# Module with Remote Debug Support.

    Hinweis

    Bei der Auswahl von Debuggen verwendet Visual Studio Dockerfile.(amd64|windows-amd64).debug zum Erstellen von Docker-Images. Diese Datei schließt den .NET Core-Befehlszeilendebugger VSDBG beim Erstellen in Ihr Containerimage ein. Wir empfehlen Ihnen, für produktionsbereite IoT Edge-Module die Konfiguration Version zu verwenden, die Dockerfile.(amd64|windows-amd64) ohne VSDBG verwendet.

    Stellen Sie sicher, dass die letzte Zeile der Vorlage ENTRYPOINT ["dotnet", "IotEdgeModule1.dll"] der Name der DLL mit dem Namen Ihres IoT Edge-Modulprojekts übereinstimmt.

  4. Um eine SSH-Verbindung mit dem Linux-Modul herzustellen, müssen Sie einen RSA-Schlüssel erstellen. Öffnen Sie eine PowerShell-Sitzung mit erhöhten Rechten, und führen Sie die folgenden Befehle aus, um einen neuen RSA-Schlüssel zu erstellen. Speichern Sie den RSA-Schlüssel im selben IoT Edge-Modulordner, und stellen Sie sicher, dass der Name des Schlüssels id_rsa lautet.

    ssh-keygen -t RSA -b 4096 -m PEM

    Screenshot des PowerShell-Befehls zum Erstellen eines SSH-Schlüssels

  5. Wenn Sie eine private Registrierung wie Azure Container Registry verwenden, melden Sie sich dort mit dem folgenden Docker-Befehl an. Sie erhalten den Benutzernamen und das Kennwort über die Seite Zugriffsschlüssel der Registrierung im Azure-Portal. Wenn Sie eine lokale Registrierung verwenden, können Sie eine lokale Registrierung durchführen.

    docker -H tcp://<EFLOW-VM-IP>:2375 login -u <Container Registry username> -p <Container Registry password> <Container Registry login server>

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektordner, und wählen Sie IoT Edge-Module erstellen und pushen aus. Dieser Befehl erstellt und pusht das Docker-Image für jedes Modul.

  2. Wenn Sie eine private Registrierung wie Azure Container Registry verwenden, müssen Sie Ihre Anmeldeinformationen für die Registrierung den Laufzeiteinstellungen hinzufügen, die in der Datei deployment.template.json enthalten sind. Ersetzen Sie die Platzhalter durch Ihren tatsächlichen Benutzernamen, das Kennwort und den Registrierungsnamen des Container Registry-Administrators.

          "settings": {
        "minDockerVersion": "v1.25",
        "loggingOptions": "",
        "registryCredentials": {
          "registry1": {
            "username": "<username>",
            "password": "<password>",
            "address": "<registry name>.azurecr.io"
          }
        }
      }

    Hinweis

    In diesem Artikel werden die Administratoranmeldeinformationen für Azure Container Registry verwendet, die für Entwicklungs- und Testszenarien geeignet sind. Wenn Sie für die Produktionsszenarien bereit sind, empfehlen wir Ihnen, eine Authentifizierungsoption mit den geringstmöglichen Rechten, z. B. Dienstprinzipale, auszuwählen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf Ihre Azure Container Registry.

  3. Es ist für den Zugriff auf den SSH-Dienst des Moduls erforderlich, Port 22 verfügbar zu machen. In diesem Tutorial wird 10022 als Hostport verwendet, Sie können jedoch einen anderen Port angeben. Der von Ihnen angegebene Port wird als SSH-Port verwendet, um eine Verbindung mit dem Linux-C#-Modul herzustellen. Sie müssen die SSH-Portinformationen unter createOptions für diese Linux-Moduleinstellung in der Datei deployment.debug.template.json hinzufügen:

         "createOptions": {
        "HostConfig": {
           "Privileged": true,
           "PortBindings": {
                 "22/tcp": [
                    {
                       "HostPort": "10022"
                    }
                 ]
           }
        }
     }

  4. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektordner, und wählen Sie Bereitstellung für IoT Edge generieren aus, um die neue JSON-Datei für die IoT Edge-Bereitstellung zu erstellen.

  5. Wählen Sie Ansicht>Cloud-Explorer. Vergewissern Sie sich, dass Sie bei Visual Studio 2019 angemeldet sind.

  6. Erweitern Sie in Cloud-Explorer Ihr Abonnement, suchen Sie Ihre Azure IoT Hub-Instanz und das Azure IoT Edge-Gerät, das Sie bereitstellen möchten.

  7. Klicken Sie mit der rechten Maustaste auf das IoT Edge-Gerät, und wählen Sie Bereitstellung erstellen aus. Navigieren Sie zum Debugbereitstellungsmanifest, das für Ihre Plattform konfiguriert wurde. Es befindet sich im Ordner config in Ihrer Visual Studio-Projektmappe (z. B. deployment.amd64.json).

Erstellen des Docker-Images des Moduls

Nachdem Sie Ihr Modul entwickelt haben, können Sie das Modulimage erstellen, um es in einer Containerregistrierung zu speichern, damit es auf Ihrem IoT Edge-Gerät bereitgestellt werden kann.

Verwenden Sie das Dockerfile des Moduls, um das Docker-Modulimage zu erstellen:

docker build --rm -f "<DockerFilePath>" -t <ImageNameAndTag> "<ContextPath>"

Angenommen, Ihre Befehlsshell befindet sich in Ihrem Projektverzeichnis, und der Modulname lautet IotEdgeModule1. Verwenden Sie die folgenden Befehle, um das Image für die lokale Registrierung oder eine Azure-Containerregistrierung zu erstellen:

# Build the image for the local registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t localhost:5000/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Or build the image for an Azure container registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

Pushen des Docker-Images des Moduls

Pushen Sie Ihr Modulimage in die lokale Registrierung oder eine Containerregistrierung:

docker push <ImageName>

Zum Beispiel:

# Push the Docker image to the local registry

docker push localhost:5000/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure container registry
az acr login --name myacr
docker push myacr.azurecr.io/iotedgemodule1:0.0.1-amd64

Bereitstellen des Moduls auf dem IoT Edge-Gerät

Öffnen Sie in Visual Studio die Bereitstellungsmanifestdatei deployment.debug.template.json im Hauptprojekt.

Vor der Bereitstellung müssen Sie Ihre Azure Container Registry-Anmeldeinformationen, die Modulimages und die richtigen createOptions-Werte aktualisieren. Weitere Informationen zu createOption-Werten finden Sie unter Konfigurieren von Erstellungsoptionen für Container für IoT Edge-Module.

  1. Wenn Sie Azure Container Registry zum Speichern Ihres Modulimages verwenden, fügen Sie Ihre Anmeldeinformationen in den edgeAgent-Einstellungen unter deployment.debug.template.json hinzu. Zum Beispiel:

    "modulesContent": {
"$edgeAgent": {
  "properties.desired": {
    "schemaVersion": "1.1",
    "runtime": {
      "type": "docker",
      "settings": {
        "minDockerVersion": "v1.25",
        "loggingOptions": "",
        "registryCredentials": {
          "myacr": {
            "username": "myacr",
            "password": "<your_acr_password>",
            "address": "myacr.azurecr.io"
          }
        }
      }
    },
//...

  2. Ersetzen Sie den Wert der image-Eigenschaft durch den Namen des Modulimages, das Sie an die Registrierung gepusht haben. Wenn Sie beispielsweise ein Image mit dem Tag myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 für das benutzerdefinierte Modul IotEdgeModule1 gepusht haben, ersetzen Sie den wert der image-Eigenschaft durch den Tagwert.

  3. Fügen Sie den Wert createOptions für jedes System und jedes benutzerdefinierte Modul in der Bereitstellungsvorlage hinzu, oder ersetzen Sie diesen Wert durch den Zeichenfolgeninhalt.

    Die Einstellungen image und createOptions für IotEdgeModule1 können z. B. dem folgenden Beispiel ähneln:

    "IotEdgeModule1": {
"version": "1.0.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
    "image": "myacr.azurecr.io/iotedgemodule1:0.0.1-amd64",
    "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
}

  4. Verwenden Sie den Azure CLI-Befehl für IoT Edge set-modules zum Bereitstellen der Module für Azure IoT Hub. Wenn Sie beispielsweise die in der Datei deployment.debug.amd64.json definierten Module auf dem IoT-Hub my-iot-hub für das IoT Edge-Gerät my-device bereitstellen möchten, verwenden Sie den folgenden Befehl:

    az iot edge set-modules --hub-name my-iot-hub --device-id my-device --content ./deployment.debug.template.json --login "HostName=my-iot-hub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"

    Tipp

    Sie finden Ihre IoT Hub-Verbindungszeichenfolge im Azure-Portal unter Azure IoT Hub>Sicherheitseinstellungen>SAS-Richtlinien.

  5. Klicken Sie im Cloud-Explorer mit der rechten Maustaste auf Ihr Edgegerät, und führen Sie eine Aktualisierung aus, um zu bestätigen, dass das neue Modul zusammen mit den Modulen $edgeAgent und $edgeHub ausgeführt wird.

Debuggen der Lösung

  1. Führen Sie die folgenden Befehle in einer PowerShell-Sitzung mit erhöhten Rechten aus:

    1. Rufen Sie den Wert von moduleId anhand des Namens für das Linux-C#-Modul ab. Ersetzen Sie den Platzhalter <iot-edge-module-name> durch den Namen Ihres Moduls.

      $moduleId = Invoke-EflowVmCommand "sudo docker ps -aqf name=<iot-edge-module-name>"

    2. Überprüfen Sie, ob $moduleId richtig ist. Wenn die Variable leer ist, vergewissern Sie sich, dass Sie den richtigen Modulnamen verwenden.

    3. Starten des SSH-Diensts innerhalb des Linux-Containers:

      Invoke-EflowVmCommand "sudo docker exec -it -d $moduleId service ssh start"

    4. Öffnen Sie den SSH-Port des Moduls auf der VM mit IoT Edge für Linux unter Windows. (In diesem Tutorial wird Port 10022 verwendet.)

      Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 10022 -j ACCEPT"

    Warnung

    Aus Sicherheitsgründen wird bei jedem Neustart der VM mit IoT Edge für Linux unter Windows die IP-Tabellenregel gelöscht und auf die ursprünglichen Einstellungen zurückgesetzt. Außerdem muss der SSH-Dienst des Moduls manuell neugestartet werden.

  2. Wählen Sie nach dem erfolgreichen Start des SSH-Diensts Debuggen>An Prozess anfügen aus, und legen Sie Verbindungstyp auf SSH und Verbindungsziel auf die IP-Adresse Ihrer VM mit IoT Edge für Linux unter Windows fest. Wenn Sie die IP-Adresse Ihrer VM mit IoT Edge für Linux unter Windows nicht kennen, können Sie das PowerShell-Cmdlet Get-EflowVmAddr verwenden.

    Geben Sie die IP-Adresse ein, und drücken Sie dann die EINGABETASTE. Nehmen Sie im Popupfenster die folgenden Einstellungen vor:

    Feld Wert
    Hostname IP-Adresse für die VM mit IoT Edge für Linux unter Windows
    Port 10022 (oder der Port aus der Bereitstellungskonfiguration)
    Benutzername root
    Authentifizierungstyp Privater Schlüssel
    Private Schlüsseldatei Vollständiger Pfad zum Wert id_rsa, den Sie in einem vorherigen Schritt erstellt haben
    Passphrase Passphrase zu dem in einem vorherigen Schritt erstellten Schlüssel

  3. Nachdem Sie erfolgreich eine SSH-Verbindung mit dem Modul hergestellt haben, können Sie den Prozess und dann Anfügen auswählen. Für das C#-Modul müssen Sie die Verarbeitung von dotnet und dann Anfügen an Verwaltet (CoreCLR) auswählen. Dies kann beim ersten Mal 10 bis 20 Sekunden dauern.

  4. Legen Sie einen Haltepunkt fest, um das Modul zu überprüfen:

    • Legen Sie bei der Entwicklung in C# in ModuleBackgroundService.cs einen Haltepunkt in der PipeMessage()-Funktion fest.
    • Wenn Sie C verwenden, legen Sie in main.c einen Haltepunkt in der InputQueue1Callback()-Funktion fest.

  5. Die Ausgabe von SimulatedTemperatureSensor sollte an input1 des benutzerdefinierten Linux-C#-Moduls umgeleitet werden. Es sollte ein Breakpoint ausgelöst werden. Sie können Variablen in Visual Studio im Fenster Lokal ansehen.

    Screenshot des Debuggens eines einzelnen Moduls

  6. Drücken Sie zum Beenden des Debuggens STRG+F5, oder wählen Sie die Schaltfläche Beenden aus.

Bereinigen von Ressourcen

Falls Sie mit dem nächsten empfohlenen Artikel fortfahren möchten, können Sie die erstellten Ressourcen und Konfigurationen beibehalten und wiederverwenden. Sie können auch dasselbe IoT Edge-Gerät als Testgerät weiter nutzen.

Andernfalls löschen Sie die in diesem Artikel verwendeten lokalen Konfigurationen und die Azure-Ressourcen, um Kosten zu vermeiden.

Löschen von Azure-Ressourcen

Das Löschen von Azure-Ressourcen und -Ressourcengruppen kann nicht rückgängig gemacht werden. Achten Sie daher darauf, dass Sie nicht versehentlich die falsche Ressourcengruppe oder die falschen Ressourcen löschen. Wenn Sie den IoT-Hub in einer bereits vorhandenen Ressourcengruppe erstellt haben, die Ressourcen enthält, die Sie behalten möchten, löschen Sie nicht die Ressourcengruppe, sondern nur die IoT-Hub-Ressource.

So löschen Sie die Ressourcen:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie anschließend Ressourcengruppen aus.

  2. Wählen Sie den Namen der Ressourcengruppe aus, die Ihre IoT Edge-Testressourcen enthält.

  3. Überprüfen Sie die Liste der Ressourcen, die Ihre Ressourcengruppe enthält. Wenn Sie alle löschen möchten, klicken Sie auf Ressourcengruppe löschen. Wenn Sie nur einige Ressourcen löschen möchten, wählen Sie die jeweiligen Ressourcen aus, um sie einzeln zu löschen.

Nächster Schritt

In diesem Tutorial haben Sie Visual Studio auf Ihrem Entwicklungscomputer eingerichtet und damit Ihr erstes IoT Edge-Modul bereitgestellt und debuggt. Nachdem Sie sich nun mit den grundlegenden Konzepten vertraut gemacht haben, können Sie versuchen, einem Modul Funktionen hinzuzufügen, damit es den Datenfluss analysieren kann:

Tutorial: Entwickeln von Azure IoT Edge-Modulen mithilfe von Visual Studio Code