Debuggen von Azure IoT Edge-Modulen mithilfe von Visual Studio Code

  • 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 Artikel wird gezeigt, wie Sie Visual Studio Code zum Debuggen von IoT Edge-Modulen in mehreren Sprachen verwenden. Auf Ihrem Entwicklungscomputer können Sie Ihr Modul mithilfe von Visual Studio Code in einem lokalen oder Remote-Modulcontainer anfügen und debuggen.

Dieser Artikel enthält Schritte für zwei IoT Edge Entwicklungstools.

  • Befehlszeilentool Azure IoT Edge Dev Tool (CLI). Dieses Tool wird für die Entwicklung bevorzugt.
  • Erweiterung Azure IoT Edge-Tools für Visual Studio Code. Die Erweiterung befindet sich im Wartungsmodus.

Verwenden Sie die Schaltfläche für die Toolauswahl am Anfang dieses Artikels, um die Toolversion auszuwählen.

Visual Studio Code unterstützt das Schreiben von IoT Edge-Modulen in den folgenden Programmiersprachen:

  • C# und C# Azure Functions
  • C
  • Python
  • Node.js
  • Java

Azure IoT Edge unterstützt die folgenden Gerätearchitekturen:

  • AMD64
  • ARM32v7
  • ARM64

Weitere Informationen zu unterstützten Betriebssystemen, Sprachen und Architekturen finden Sie unter Sprach- und Architekturunterstützung.

Wenn Sie die IoT Edge-Erweiterung für Visual Studio Code verwenden, können Sie Ihren Modulcode auch im IoT Edge-Simulator starten und debuggen.

Außerdem können Sie einen Windows-Entwicklungscomputer und Debugmodule in einem Linux-Container einsetzen, indem Sie IoT Edge für Linux unter Windows (EFLOW) verwenden. Weitere Informationen zur Verwendung von EFLOW zum Entwickeln von Modulen finden Sie im Tutorial: Entwickeln von IoT Edge-Modulen mit Linux-Containern mithilfe von IoT Edge für Linux unter Windows.

Wenn Sie mit den Debugfunktionen von Visual Studio Code nicht vertraut sind, informieren Sie sich unter Visual Studio Code-Debuggen.

Voraussetzungen

Sie können einen Computer oder virtuellen Computer unter Windows, macOS oder Linux als Entwicklungscomputer verwenden. Auf Windows-Computern können Sie entweder Windows- oder Linux-Module entwickeln. Verwenden Sie zum Entwickeln von Linux-Modulen einen Windows-Computer, der die Anforderungen für Docker Desktop erfüllt.

Arbeiten Sie zum Installieren der erforderlichen Tools für die Entwicklung und das Debuggen das Tutorial Entwickeln von Azure IoT Edge-Modulen mithilfe von Visual Studio Code durch.

Installieren Sie Visual Studio Code.

Fügen Sie die folgenden Erweiterungen hinzu:

Zum Debuggen Ihres Moduls auf einem Gerät benötigen Sie Folgendes:

  • Einen aktiven IoT Hub mit mindestens einem IoT Edge-Gerät.
  • Ein physisches IoT Edge-Gerät oder ein virtuelles Gerät. Führen Sie zum Erstellen eines virtuellen Geräts in Azure die Schritte im Schnellstart für Linux aus.
  • Ein benutzerdefiniertes IoT Edge-Modul. Führen Sie zum Erstellen eines benutzerdefinierten Moduls die Schritte im Tutorial Entwickeln von Azure IoT Edge-Modulen mithilfe von Visual Studio Code aus.

Debuggen ohne einen Container mithilfe von IoT Edge-Simulator

Der IoT Edge-Simulator ist ein Tool, das auf Ihrem Entwicklungscomputer ausgeführt wird und das Verhalten eines einzelnen IoT Edge-Geräts simuliert. Sie können den IoT Edge-Simulator verwenden, um Ihre IoT Edge-Module ohne physisches Gerät oder eine vollständige IoT Edge-Gerätelaufzeit zu entwickeln und zu testen.

Bei den folgenden Debugschritten wird davon ausgegangen, dass Sie bereits ein benutzerdefiniertes Modul erstellt haben. Wenn Sie noch kein benutzerdefiniertes Modul erstellt haben, führen Sie die Schritte im Tutorial Entwickeln von Azure IoT Edge-Modulen mithilfe von Visual Studio Code aus.

Das Debuggen eines Moduls ohne einen Container ist bei Verwendung von C oder Python nicht verfügbar.

Debuggen im Anfügemodus mithilfe von IoT Edge-Simulator

Debuggen im Anfügemodus wird für C oder Python nicht unterstützt.

Debuggen eines Moduls mit der IoT Edge-Runtime

In jedem Modulordner gibt es mehrere Docker-Dateien für unterschiedliche Containertypen. Verwenden Sie eine der Dateien mit der Erweiterung .debug, um Ihr Modul zum Testen zu erstellen.

Wenn Sie Module mithilfe dieser Methode debuggen, werden Ihre Module auf der obersten Ebene der IoT Edge-Runtime ausgeführt. Das IoT Edge-Gerät und Ihr Visual Studio Code können sich auf demselben Computer befinden. Meist befindet sich jedoch Visual Studio Code auf dem Entwicklungscomputer, und die IoT Edge-Runtime und die Module werden auf einem anderen physischen Computer ausgeführt. Für das Debuggen in Visual Studio Code müssen Sie folgende Aktionen ausführen:

  • Richten Sie Ihr IoT Edge-Gerät ein, erstellen Sie Ihre IoT Edge-Module mit der Dockerfile .debug, und stellen Sie sie dann auf dem IoT Edge-Gerät bereit.
  • Aktualisieren Sie die Datei launch.json, damit Visual Studio Code an den Prozess in einem Container des Remotecomputers angefügt werden kann. Sie finden diese Datei in Ihrem Arbeitsbereich im Ordner .vscode. Sie wird bei jedem Hinzufügen eines neuen Moduls aktualisiert, das Debuggen unterstützt.
  • Verwenden Sie Remote SSH-Debuggen zum Anfügen an den Container auf dem Remotecomputer.

Erstellen und Bereitstellen Ihres Moduls auf einem IoT Edge-Gerät

Öffnen Sie in Visual Studio Code die Bereitstellungsmanifestdatei deployment.debug.template.json. Im Bereitstellungsmanifest werden die Module beschrieben, die auf dem IoT Edge-Zielgerät konfiguriert werden sollen. Vor der Bereitstellung müssen Sie Ihre Azure Container Registry-Anmeldeinformationen und Ihre Modulimages mit den richtigen createOptions-Werten aktualisieren. Weitere Informationen zu „createOption“-Werten finden Sie unter Konfigurieren von Erstellungsoptionen für Container für IoT Edge-Module.

  1. Wenn Sie eine Azure Container Registry-Instanz zum Speichern Ihres Modulimages verwenden, fügen Sie Ihre Anmeldeinformationen im Bereich edgeAgent>settings>registryCredentials in deployment.debug.template.json hinzu. Ersetzen Sie myacr an beiden Stellen durch Ihren eigenen Registrierungsnamen, und geben Sie Ihr Kennwort und die Adresse für Ihren Anmeldeserver an. Beispiel:

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

  2. Fügen Sie dem Wert createOptions für jedes aufgelistete Systemmodul (edgeHub und edgeAgent) und benutzerdefinierte Modul (z. B. filtermodule) den folgenden Zeichenfolgeninhalt hinzu, oder ersetzen Sie ihn. Ändern Sie ggf. die Werte.

    "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

    Beispielsweise sollte die Konfiguration filtermodule ungefähr wie folgt aussehen:

    "filtermodule": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"settings": {
    "image": "myacr.azurecr.io/filtermodule:0.0.1-amd64",
    "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
}
  1. Führen Sie in der Befehlspalette von Visual Studio Code den Befehl Azure IoT Edge: Build and Push IoT Edge solution (Azure IoT Edge: IoT Edge-Projektmappe erstellen und pushen) aus.
  2. Wählen Sie die deployment.debug.template.json-Datei für Ihre Projektmappe aus.
  3. Klicken Sie im Abschnitt Azure IoT Hub>Geräte der Visual Studio Code-Explorer-Ansicht mit der rechten Maustaste auf den IoT Edge-Gerätenamen für die Bereitstellung, und wählen Sie Bereitstellung für einzelnes Gerät erstellen aus.

    Tipp

    Vergewissern Sie sich, dass es sich bei dem ausgewählten Gerät um ein IoT Edge-Gerät handelt. Wählen Sie dazu das Gerät aus, um die Liste mit den Modulen zu erweitern, und vergewissern Sie sich, dass $edgeHub und $edgeAgent vorhanden sind. Jedes IoT Edge-Gerät verfügt über diese beiden Module.

  4. Navigieren Sie zum Ordner config Ihrer Projektmappe, wählen Sie die Datei deployment.debug.amd64.json und dann Edge-Bereitstellungsmanifest auswählen aus.

Sie können den Containerstatus auf Ihrem Gerät oder Ihrer VM überprüfen, indem Sie den Befehl docker ps in einem Terminal ausführen. Der Container sollte nach der Ausführung des Befehls aufgeführt werden. Wenn Visual Studio Code und Ihre IoT Edge-Runtime auf demselben Computer ausgeführt werden, können Sie den Status auch in der Docker-Ansicht von Visual Studio Code überprüfen.

Wichtig

Wenn Sie eine private Registrierung wie Azure Container Registry für Ihre Images verwenden, müssen Sie sich möglicherweise authentifizieren, um Images zu pushen. Verwenden Sie zum Authentifizieren docker login <Azure Container Registry login server> oder az acr login --name <Azure Container Registry name>.

Anmelden bei Docker

Geben Sie Ihre Anmeldeinformationen für die Containerregistrierung für Docker an, damit Ihr Containerimage per Pushvorgang übertragen und in der Registrierung gespeichert werden kann.

  1. Melden Sie sich bei Docker mit den Anmeldeinformationen für Azure Container Registry an, die Sie nach dem Erstellen der Registrierung gespeichert haben.

    docker login -u <Azure Container Registry username> -p <Azure Container Registry password> <Azure Container Registry login server>

    Möglicherweise wird Ihnen in einem Sicherheitshinweis die Verwendung von --password-stdin empfohlen. Diese bewährte Methode wird für Produktionsszenarien empfohlen, aber sie ist nicht Gegenstand dieses Tutorials. Weitere Informationen finden Sie in der docker login-Referenz.

  2. Melden Sie sich bei Azure Container Registry an. Möglicherweise müssen Sie die Azure CLI installieren, um den Befehl az verwenden zu können. Mit diesem Befehl werden Ihr Benutzername und Kennwort in Ihrer Containerregistrierung unter Einstellungen>Zugriffsschlüssel abgefragt.

    az acr login -n <Azure Container Registry name>

Tipp

Wenn Sie an irgendeinem Punkt in diesem Tutorial abgemeldet werden, wiederholen Sie die Schritte für die Docker- und Azure Container Registry-Anmeldung, um fortzufahren.

Erstellen des Moduls „Docker-Image“

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

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

Verwenden Sie beispielsweise die folgenden Befehle, um das Image für die lokale Registrierung oder eine Azure Container Registry-Instanz zu erstellen:

# Build the image for the local registry

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

# Or build the image for an Azure Container Registry

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

Pushen des Moduls „Docker-Image“

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

docker push <ImageName>

Beispiel:

# Push the Docker image to the local registry

docker push localhost:5000/filtermodule:0.0.1-amd64

# Or push the Docker image to an Azure Container Registry
az acr login --name myacr
docker push myacr.azurecr.io/filtermodule:0.0.1-amd64

Bereitstellen des Moduls auf dem IoT Edge-Gerät

Verwenden Sie den Befehl IoT Edge Azure CLI set-modules zum Bereitstellen der Module für den Azure IoT Hub. Verwenden Sie beispielsweise den folgenden Befehl, um die in der Datei deployment.debug.template.json definierten Module in der IoT Hub-Instanz my-iot-hub für das IoT Edge-Gerät my-device bereitzustellen.

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 Ihren freigegebenen Zugriffsschlüssel für IoT Hub im Azure-Portal unter >Sicherheitseinstellungen>Freigegebene Zugriffsrichtlinien>iothubowner für Ihren IoT Hub.

Debuggen Ihres Moduls

Zum Debuggen von Modulen auf einem Remotegerät können Sie Remote-SSH-Debuggen in Visual Studio Code verwenden.

Installieren Sie zum Aktivieren des Visual Studio Code-Remotedebuggens die Erweiterung „Remoteentwicklung“. Weitere Informationen zum Remotedebuggen von Visual Studio Code finden Sie unter Remoteentwicklung in Visual Studio Code.

Ausführliche Informationen zur Verwendung des Remote-SSH-Debuggens in Visual Studio Code finden Sie unter Remoteentwicklung mithilfe von SSH.

Wählen Sie in der Visual Studio Code-Debugansicht die Debugkonfigurationsdatei für Ihr Modul aus. Standardmäßig verwenden das Dockerfile .debug, die createOptions-Einstellungen des Modulcontainers und die Datei launch.json Localhost.

Wählen Sie Debuggen starten oder F5 aus. Wählen Sie den Prozess zum Anfügen aus. In der Visual Studio Code-Debugansicht werden die Variablen im linken Bereich angezeigt.

Debuggen mithilfe von Docker Remote SSH

Die Docker- und Moby-Engines unterstützen SSH-Verbindungen mit Containern, sodass Sie in der Visual Studio Code-Instanz, die mit einem Remotegerät verbunden ist, debuggen können. Sie müssen die folgenden Voraussetzungen erfüllen, bevor Sie dieses Feature nutzen können.

Die Voraussetzungen für das Remote-SSH-Debuggen können je nach der verwendeten Sprache unterschiedlich sein. In den folgenden Abschnitten wird das Setup für .NET beschrieben. Informationen zu anderen Sprachen finden Sie unter Remoteentwicklung mithilfe von SSH. Details zum Konfigurieren des Remotedebuggens finden Sie in den Debugabschnitten für die einzelnen Sprachen in der Visual Studio Code-Dokumentation.

Konfigurieren von Docker SSH-Tunneling

  1. Führen Sie die Schritte in Docker SSH-Tunneling aus, um SSH-Tunneling auf Ihrem Entwicklungscomputer zu konfigurieren. SSH-Tunneling erfordert die Authentifizierung des öffentlichen/privaten Schlüsselpaars und einen Docker-Kontext, der den Endpunkt des Remotegeräts definiert.

  2. Für die Verbindung mit Docker sind Berechtigungen auf Stammebene erforderlich. Führen Sie die Schritte in Manage docker as a non-root user (Verwalten von Docker als Nicht-Stammbenutzer) aus, um eine Verbindung mit dem Docker-Daemon auf dem Remotegerät zu ermöglichen. Wenn Sie das Debuggen abgeschlossen haben, sollten Sie möglicherweise Ihren Benutzer aus der Docker-Gruppe entfernen.

  3. Verwenden Sie in Visual Studio Code die Befehlspalette (STRG+UMSCHALT+P), um den Befehl Docker-Kontext: Verwenden zur Aktivierung des Docker-Kontexts auszugeben, der auf den Remotecomputer verweist. Dieser Befehl bewirkt, dass sowohl Visual Studio Code als auch Docker CLI den Kontext des Remotecomputers verwenden.

    Tipp

    Alle Docker-Befehle verwenden den aktuellen Kontext. Denken Sie daran, den Kontext auf Standard zurückzuändern, wenn Sie das Debuggen abgeschlossen haben.

  4. Zur Überprüfung, ob der Remote Docker-Kontext aktiv ist, listen Sie die zurzeit ausgeführten Container auf dem Remotegerät auf:

    docker ps

    In der Ausgabe sollten diese Container ähnlich wie im folgenden Beispiel aufgelistet werden:

    PS C:\> docker ps        
CONTAINER ID   IMAGE                                                             COMMAND                   CREATED        STATUS         PORTS                                                                                                                                   NAMES
a317b8058786   myacr.azurecr.io/filtermodule:0.0.1-amd64                         "dotnet filtermodule…"    24 hours ago   Up 6 minutes                                                                                                                                           filtermodule
d4d949f8dfb9   mcr.microsoft.com/azureiotedge-hub:1.5                            "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes   0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:5671->5671/tcp, :::5671->5671/tcp, 0.0.0.0:8883->8883/tcp, :::8883->8883/tcp, 1883/tcp   edgeHub
1f0da9cfe8e8   mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0   "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes                                                                                                    
                                       tempSensor
66078969d843   mcr.microsoft.com/azureiotedge-agent:1.5                          "/bin/sh -c 'exec /a…"    24 hours ago   Up 6 minutes                                                                                                    
                                       edgeAgent

  5. Fügen Sie im Verzeichnis .vscode eine neue Konfiguration zu launch.json hinzu, indem Sie die Datei in Visual Studio Code öffnen. Wählen Sie Konfiguration hinzufügen und dann die entsprechende Vorlage zum Remoteanfügen für Ihr Modul aus. Die folgende Konfiguration beispielsweise ist für .NET Core vorgesehen. Ändern Sie den Wert für den Parameter -H in PipeArgs in Ihren Geräte-DNS-Namen oder Ihre IP-Adresse.

    "configurations": [
{
  "name": "Remote Debug IoT Edge Module (.NET Core)",
  "type": "coreclr",
  "request": "attach",
  "processId": "${command:pickRemoteProcess}",
  "pipeTransport": {
    "pipeProgram": "docker",
    "pipeArgs": [
      "-H",
      "ssh://user@my-device-vm.eastus.cloudapp.azure.com:22",
      "exec",
      "-i",
      "filtermodule",
      "sh",
      "-c"
    ],
    "debuggerPath": "~/vsdbg/vsdbg",
    "pipeCwd": "${workspaceFolder}",
    "quoteArgs": true
  },
  "sourceFileMap": {
    "/app": "${workspaceFolder}/modules/filtermodule"
  },
  "justMyCode": true
},

Remotedebuggen Ihres Moduls

  1. Wählen Sie in der Visual Studio Code-Debugansicht die Debugkonfiguration Remote Debug IoT Edge Module (.NET Core) (Remotedebuggen von IoT Edge-Modul (.NET Core)) aus.

  2. Wählen Sie Debuggen starten oder F5 aus. Wählen Sie den Prozess zum Anfügen aus.

  3. In der Visual Studio Code-Debugansicht werden die Variablen im linken Bereich angezeigt.

  4. Legen Sie in Visual Studio Code Breakpoints in Ihrem benutzerdefinierten Modul fest.

  5. Wenn ein Breakpoint erreicht wird, können Sie Variablen überprüfen, Code schrittweise durchlaufen und Ihr Modul debuggen.

    Screenshot der Unterbrechung beim Anfügen von Visual Studio Code an einen Docker-Container an einem Breakpoint

Hinweis

Im vorstehenden Beispiel wird gezeigt, wie IoT Edge-Module in Remotecontainern debuggt werden. Im Beispiel werden ein Remote-Docker-Kontext und Änderungen an den Docker-Berechtigungen auf dem Remotegerät hinzugefügt. Nachdem Sie das Debuggen Ihrer Module abgeschlossen haben, legen Sie Ihren Docker-Kontext auf Standard fest, und entfernen Sie Berechtigungen aus Ihrem Benutzerkonto.

In diesem IoT Developer-Blogeintrag finden Sie ein Beispiel zur Verwendung eines Raspberry Pi-Geräts.

Nächste Schritte

Nachdem Sie das Modul erstellt haben, informieren Sie sich darüber, wie Sie Azure IoT Edge-Module bereitstellen.

Weitere Informationen zum Entwickeln von Modulen für Ihre IoT Edge-Geräte finden Sie unter Azure IoT Hub SDKs.