Freigeben über

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

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

Wichtig

IoT Edge 1.5 LTS ist das unterstützte Release. IoT Edge 1.4 LTS wurde am 12. November 2024 eingestellt. Wenn Sie ein früheres Release verwenden, finden Sie weitere Informationen unter Aktualisieren von IoT Edge.

In diesem Artikel wird erläutert, wie Visual Studio Code zum Debuggen von IoT Edge-Modulen in mehreren Sprachen verwendet wird. Verwenden Sie auf Dem Entwicklungscomputer Visual Studio Code, um Ihr Modul in einem lokalen oder Remotemodulcontainer anzufügen und zu 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.

Wählen Sie die Toolversion mit der Toolauswahlschaltfläche am Anfang dieses Artikels aus.

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 funktioniert mit diesen 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 noch nicht fertig sind, lesen Sie das Debuggen von Visual Studio Code.

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 diese Erweiterungen hinzu:

Um Ihr Modul auf einem Gerät zu debuggen, benötigen Sie Folgendes:

Debuggen ohne Container mithilfe des IoT Edge-Simulators

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

Das Debuggen im Anfügungsmodus ist für C oder Python nicht verfügbar.

Debuggen eines Moduls mit der IoT Edge-Runtime

Jeder Modulordner enthält mehrere Docker-Dateien für verschiedene Containertypen. Verwenden Sie eine beliebige Datei, die mit der Erweiterung .debug endet, 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 Visual Studio Code können auf demselben Computer ausgeführt werden. In der Regel wird Visual Studio Code jedoch auf dem Entwicklungscomputer ausgeführt, während die IoT Edge-Laufzeit und -Module auf einem anderen physischen Computer ausgeführt werden. Um mit Visual Studio Code zu debuggen:

  • 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. Aktualisieren Sie vor der Bereitstellung Ihre Azure Container Registry-Anmeldeinformationen und Modulimages mit den richtigen createOptions Werten. 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.

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

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. Obwohl es sich um eine empfohlene bewährte Methode für Produktionsszenarien handelt, liegt sie außerhalb des Umfangs dieses Lernprogramms. 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-Datei des Moduls, um das Docker-Image 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

Verwenden Sie remote SSH-Debugging in Visual Studio Code, um Module auf einem Remotegerät zu debuggen.

Aktivieren Sie das Remotedebugging von Visual Studio Code, indem Sie die Remoteentwicklungserweiterung installieren. Weitere Informationen zum Remotedebuggen von Visual Studio Code finden Sie unter Remoteentwicklung in Visual Studio Code.

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

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

Wählen Sie "Debuggen starten" oder "F5" aus, und wählen Sie dann den Prozess aus, an den sie angefügt werden soll. 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-Debugging können je nach der verwendeten Sprache variieren. 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 im Docker SSH-Tunneling aus, um SSH-Tunneling auf Ihrem Entwicklungscomputer einzurichten. 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 Stammberechtigungen 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 mit dem Debuggen fertig sind, können Sie 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. Mit diesem Befehl können Visual Studio Code und Docker CLI den Remotecomputerkontext 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

    Die Ausgabe listet die Container auf, die auf dem Remotegerät ausgeführt werden, ähnlich wie die folgenden:

    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. Öffnen Sie im .vscode-Verzeichnis launch.json in Visual Studio Code, und fügen Sie eine neue Konfiguration hinzu. Wählen Sie "Konfiguration hinzufügen" und dann die entsprechende Remoteanfügungsvorlage 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 Ihr Modul erstellt haben, erfahren Sie, wie Sie Azure IoT Edge-Module bereitstellen.

Um Module für Ihre IoT Edge-Geräte zu entwickeln, erfahren Sie mehr über azure IoT Hub SDKs und verwenden sie.

  • Last updated on