Freigeben über

Debuggen von Azure IoT Edge Modulen mithilfe von Visual Studio Code

Gilt für:IoT Edge 1,5 Häkchen IoT Edge 1,5

Wichtig

IoT Edge 1.5 LTS ist die unterstützte Version. IoT Edge 1.4 LTS erreichte am 12. November 2024 das Ende des Lebens. Wenn Sie eine frühere Version verwenden, lesen Sie Update IoT Edge.

In diesem Artikel wird erläutert, wie Sie Visual Studio Code zum Debuggen von IoT Edge Modulen in mehreren Sprachen verwenden. Verwenden Sie auf Ihrem 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.

  • Azure IoT Edge Dev Tool Befehlszeilentool (CLI). Dieses Tool wird für die Entwicklung bevorzugt.
  • Azure IoT Edge tools for Visual Studio Code Erweiterung. 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 den 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 Visual Studio Code IoT Edge-Erweiterung verwenden, können Sie den Modulcode auch im IoT Edge Simulator starten und debuggen.

Sie können auch einen Windows Entwicklungscomputer und Debugmodule in einem Linux-Container verwenden, indem Sie IoT Edge für Linux auf Windows (EFLOW) verwenden. Weitere Informationen zur Verwendung von EFLOW für die Entwicklung von Modulen finden Sie unter Tutorial: Entwickeln von IoT Edge Modulen mit Linux-Containern mit IoT Edge für Linux auf Windows.

Wenn Sie mit den Debugfunktionen von Visual Studio Code noch nicht fertig sind, lesen Sie Visual Studio Code Debugging.

Voraussetzungen

Sie können einen Computer oder einen virtuellen Computer verwenden, auf dem Windows, macOS oder Linux als Entwicklungscomputer ausgeführt wird. 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.

Um die erforderlichen Tools für die Entwicklung und das Debuggen zu installieren, führen Sie das Lernprogramm Develop Azure IoT Edge Module mithilfe von Visual Studio Code aus.

Installieren Sie Visual Studio Code.

Fügen Sie diese Erweiterungen hinzu:

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

  • Ein aktives IoT Hub mit mindestens einem IoT Edge Gerät.
  • Ein physisches IoT Edge Gerät oder ein virtuelles Gerät. Erstellen Sie ein virtuelles Gerät in Azure, indem Sie die Schritte im quickstart für Linux ausführen.
  • Ein benutzerdefiniertes IoT Edge Modul. Führen Sie zum Erstellen eines benutzerdefinierten Moduls die Schritte im Lernprogramm Develop Azure IoT Edge Module mithilfe von Visual Studio Code aus.

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 kein benutzerdefiniertes Modul erstellt haben, führen Sie die Schritte im Lernprogramm Develop Azure IoT Edge Module mithilfe von Visual Studio Code aus.

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

Debuggen im Anfügungsmodus mit IoT Edge Simulator

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

Debuggen eines Moduls mit der IoT Edge Laufzeit

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 mit dieser Methode debuggen, werden Ihre Module auf der IoT Edge-Laufzeit ausgeführt. Das IoT Edge Gerät und Visual Studio Code können auf demselben Computer ausgeführt werden, aber in der Regel wird Visual Studio Code auf dem Entwicklungscomputer ausgeführt, während die IoT Edge Laufzeit und Module auf einem anderen physischen Computer ausgeführt werden. So debuggen Sie aus Visual Studio Code:

  • Richten Sie Ihr IoT Edge Gerät ein, erstellen Sie Ihre IoT Edge Module mit dem .debug Dockerfile, und stellen Sie dann auf dem IoT Edge Gerät bereit.
  • Aktualisieren Sie launch.json, damit Visual Studio Code den Prozess in einem Container auf dem Remotecomputer verbinden 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-Debugging, um sich mit dem Container auf dem Remote-Computer zu verbinden.

Erstellen und bereitstellen Ihres Moduls auf einem IoT Edge Gerät

Öffnen Sie in Visual Studio Code die deployment.debug.template.json Bereitstellungsmanifestdatei. Das manifest deployment beschreibt die Module, die auf dem Zielgerät IoT Edge 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 How to configure container create options for IoT Edge modules.

  1. Wenn Sie ein Azure Container Registry verwenden, um Ihr Modulbild zu speichern, Fügen Sie Ihre Anmeldeinformationen zum edgeAgent>settings>registryCredentials Abschnitt 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\"}]}}}"

    Die Filtermodule-Konfiguration sollte z. B. ähnlich sein wie:

    "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 im Befehlsmenü von Visual Studio Code den Befehl Azure IoT Edge: Erstellen und Lösung übertragen aus.
  2. Wählen Sie die deployment.debug.template.json-Datei für Ihre Lösung aus.
  3. Klicken Sie im Abschnitt Azure IoT Hub>Devices in der Visual Studio Code Explorer-Ansicht mit der rechten Maustaste auf den namen des IoT Edge Geräts für die Bereitstellung, und wählen Sie dann Create Deployment for Single Device aus.

    Tipp

    Um zu bestätigen, dass das ausgewählte Gerät ein IoT Edge Gerät ist, wählen Sie es aus, um die Liste der Module zu erweitern und das Vorhandensein von $edgeHub und $edgeAgent zu überprüfen. Jedes IoT Edge Gerät enthält 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. Du solltest deinen Container nach der Ausführung des Befehls aufgelistet sehen. Wenn Visual Studio Code und die IoT Edge Laufzeit auf demselben Computer ausgeführt werden, überprüfen Sie den Status in der Visual Studio Code Docker-Ansicht.

Wichtig

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

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 Azure Container Registry Anmeldeinformationen 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-Anmeldereferenz .

  2. Melden Sie sich beim Azure Container Registry an. Möglicherweise müssen Sie Install Azure CLI verwenden, um den Befehl az zu verwenden. Dieser Befehl fordert Ihren Benutzernamen und Ihr Kennwort an, die Sie in Ihrer Containerregistrierung unter Einstellungen>Zugriffsschlüssel finden.

    az acr login -n <Azure Container Registry name>

Tipp

Wenn Sie sich an einem beliebigen Punkt in diesem Lernprogramm abgemeldet haben, wiederholen Sie die Schritte zum Anmelden von Docker und Azure Container Registry, um den Vorgang fortzusetzen.

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 ein Azure Container Registry 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"

Docker-Image des Moduls pushen

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

Das Modul auf dem IoT Edge-Gerät bereitstellen

Verwenden Sie den Befehl IoT Edge Azure CLI set-modules, um die Module für die Azure IoT Hub bereitzustellen. Um beispielsweise die module bereitzustellen, die in der Datei deployment.debug.template.json in IoT Hub my-iot-hub für das IoT Edge Gerät my-device definiert sind, 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 Ihren IoT Hub freigegebenen Zugriffsschlüssel im Azure Portal in Ihrem IoT Hub >Security settings>Shared Access policies>iothubowner.

Debuggen Ihres Moduls

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

Aktivieren Sie Visual Studio Code Remotedebugging, indem Sie die Erweiterung Remote Development installieren. Weitere Informationen zum Visual Studio Code Remotedebugging finden Sie unter Visual Studio Code Remote Development.

Ausführliche Informationen zur Verwendung des Remote-SSH-Debuggings in Visual Studio Code finden Sie unter Remote Development using SSH.

Wählen Sie in der Visual Studio Code Debugansicht die Debugkonfigurationsdatei für das Modul aus. Standardmäßig verwenden das Dockerfile .debug, die Container-Einstellungen des Moduls createOptions 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 Variablen im linken Bereich angezeigt.

Debuggen mithilfe von Docker-Remote-SSH

Die Docker- und Moby-Engines unterstützen SSH-Verbindungen mit Containern, mit denen Sie in Visual Studio Code debuggen können, die mit einem Remotegerät verbunden sind. 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 für eine Übersicht. Details zum Konfigurieren des Remotedebuggings finden Sie in den Debugabschnitten für jede Sprache in der dokumentation Visual Studio Code.

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 Docker-Kontext auszugeben: Verwenden Sie den Befehl, um den Docker-Kontext zu aktivieren, der auf den Remotecomputer zeigt. Mit diesem Befehl können sowohl Visual Studio Code als auch die 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 Verzeichnis .vscodelaunch.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 ist beispielsweise 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 Visual Studio Code Debugansicht die Debugkonfiguration Remote Debug IoT Edge Modul (.NET Core) aus.

  2. Wählen Sie Debuggen starten oder F5 aus. Wählen Sie den Prozess zum Anhängen aus.

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

  4. Legen Sie in Visual Studio Code Haltepunkte 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 von Visual Studio Code an einen Docker-Container auf einem Remotegerät angehalten an einem Haltepunkt.

Hinweis

Im vorherigen Beispiel wird gezeigt, wie IoT Edge Module in Remotecontainern gedebuggt 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.

  • Last updated on