Partager via

Déboguer des modules Azure IoT Edge à l’aide de Visual Studio Code

S'applique à :IoT Edge 1.5 cocher IoT Edge 1.5

Important

IoT Edge 1.5 LTS est la version prise en charge. IoT Edge 1,4 LTS a atteint la fin de vie le 12 novembre 2024. Si vous utilisez une version antérieure, consultez Update IoT Edge.

Cet article explique comment utiliser Visual Studio Code pour déboguer des modules IoT Edge dans plusieurs langages. Sur votre ordinateur de développement, utilisez Visual Studio Code pour attacher et déboguer votre module dans un conteneur de module local ou distant.

Cet article comprend des étapes pour deux outils de développement IoT Edge.

  • Azure IoT Edge Dev Tool, outil en ligne de commande (CLI). Cet outil est préféré pour le développement.
  • outils Azure IoT Edge pour l’extension Visual Studio Code. L’extension est en mode maintenance.

Sélectionnez la version de l’outil à l’aide du bouton sélecteur d’outils au début de cet article.

Visual Studio Code prend en charge l’écriture de modules IoT Edge dans les langages de programmation suivants :

  • C# et Fonctions Azure C#
  • C
  • Python
  • Node.js
  • Java

Azure IoT Edge fonctionne avec ces architectures d’appareil :

  • AMD64
  • ARM32v7
  • ARM64

Pour plus d’informations sur les systèmes d’exploitation, les langages et les architectures pris en charge, consultez Prise en charge des langages et architectures.

Lorsque vous utilisez l’extension Visual Studio Code IoT Edge, vous pouvez également lancer et déboguer votre code de module dans le simulateur IoT Edge.

Vous pouvez également utiliser un ordinateur de développement Windows et déboguer des modules dans un conteneur Linux à l’aide de IoT Edge pour Linux sur Windows (EFLOW). Pour plus d’informations sur l’utilisation d’EFLOW pour le développement de modules, consultez Tutorial : Développer des modules IoT Edge avec des conteneurs Linux à l’aide de IoT Edge pour Linux sur Windows.

Si vous débutez avec les fonctionnalités de débogage de Visual Studio Code, consultez Visual Studio Code débogage.

Prérequis

Vous pouvez utiliser un ordinateur ou une machine virtuelle exécutant Windows, macOS ou Linux comme machine de développement. Sur Windows ordinateurs, vous pouvez développer des modules Windows ou Linux. Pour développer des modules Linux, utilisez un ordinateur Windows qui répond aux requirements pour Docker Desktop.

Pour installer les outils requis pour le développement et le débogage, suivez le didacticiel Develop Azure IoT Edge à l’aide de Visual Studio Code tutoriel.

Installez Visual Studio Code.

Ajoutez ces extensions :

Pour déboguer votre module sur un appareil, vous avez besoin des éléments suivants :

Déboguer sans conteneur à l’aide du simulateur IoT Edge

Le simulateur IoT Edge est un outil qui s’exécute sur votre ordinateur de développement et simule le comportement d’un seul appareil IoT Edge. Vous pouvez utiliser le simulateur de IoT Edge pour développer et tester vos modules de IoT Edge sans appareil physique ou un runtime complet d’appareil IoT Edge.

Les étapes de débogage suivantes supposent que vous avez déjà créé un module personnalisé. Si vous n'avez pas créé de module personnalisé, suivez les étapes décrites dans le didacticiel Develop Azure IoT Edge à l'aide de Visual Studio Code didacticiel.

Le débogage d'un module sans conteneur n'est pas disponible lors de l'utilisation de C ou Python.

Déboguer en mode attachement à l’aide du simulateur IoT Edge

Le débogage en mode attachement n'est pas disponible pour C ou Python.

Déboguer un module avec le runtime IoT Edge

Chaque dossier de module contient plusieurs fichiers Docker pour différents types de conteneurs. Utilisez n’importe quel fichier se terminant par l’extension .debug pour générer votre module à des fins de test.

Lorsque vous déboguez des modules à l’aide de cette méthode, vos modules s’exécutent au-dessus du runtime IoT Edge. L’appareil IoT Edge et les Visual Studio Code peuvent s’exécuter sur le même ordinateur, mais généralement, Visual Studio Code s’exécute sur l’ordinateur de développement pendant que le runtime et les modules IoT Edge s’exécutent sur un autre ordinateur physique. Pour déboguer à partir de Visual Studio Code :

  • Configurez votre appareil IoT Edge, générez vos modules IoT Edge avec le Dockerfile .debug, puis déployez sur l’appareil IoT Edge.
  • Mettez à jour launch.json afin que Visual Studio Code puisse joindre le processus dans un conteneur sur l’ordinateur distant. Vous pouvez trouver ce fichier dans le dossier .vscode de votre espace de travail. Il est mis à jour chaque fois que vous ajoutez un module qui prend en charge le débogage.
  • Utilisez le débogage SSH distant pour procéder à l’attachement au conteneur sur l’ordinateur distant.

Générer et déployer votre module sur un appareil IoT Edge

Dans Visual Studio Code, ouvrez le fichier manifeste de déploiement deployment.debug.template.json. Le manifeste deployment décrit les modules à configurer sur l’appareil IoT Edge ciblé. Avant le déploiement, mettez à jour vos informations d’identification Azure Container Registry et les images de module avec les valeurs createOptions appropriées. Pour plus d’informations sur les valeurs d'option de création, consultez Comment configurer les options de création de conteneur pour les modules IoT Edge.

  1. Si vous utilisez un Azure Container Registry pour stocker votre image de module, ajoutez vos informations d'identification au edgeAgent>settings>registryCredentials section dans deployment.debug.template.json. Remplacez myacr par votre propre nom de registre aux deux endroits et indiquez votre mot de passe et l'adresse du serveur de connexion. Exemple :

    "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. Ajoutez ou remplacez le contenu stringifié suivant dans la valeur createOptions pour chaque système (edgeHub et edgeAgent) et module personnalisé (par exemple, filtermodule) répertoriés. Modifiez les valeurs si nécessaire.

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

    Par exemple, la configuration filtermodule doit être similaire à :

    "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. Dans la palette de commandes Visual Studio Code, exécutez la commande Azure IoT Edge : générer et envoyer (push) IoT Edge solution.
  2. Sélectionnez le fichier deployment.debug.template.json de votre solution.
  3. Dans la section Azure IoT Hub>Devices de la vue Visual Studio Code Explorer, cliquez avec le bouton droit sur le nom de l’appareil IoT Edge pour le déploiement, puis choisissez Create Deployment for Single Device.

    Conseil

    Pour vérifier que l'appareil que vous avez choisi est un appareil IoT Edge, sélectionnez-le pour développer la liste des modules et vérifier la présence de $edgeHub et $edgeAgent. Chaque appareil IoT Edge inclut ces deux modules.

  4. Accédez au dossier config de votre solution, sélectionnez le fichier deployment.debug.amd64.json, puis choisissez Sélectionner un manifeste de déploiement Edge.

Vérifiez l’état de votre conteneur à partir de votre appareil ou machine virtuelle en exécutant la docker ps commande dans un terminal. Vous devez voir votre conteneur répertorié après avoir exécuté la commande. Si Visual Studio Code et le runtime IoT Edge s’exécutent sur la même machine, vérifiez l’état dans la vue Docker Visual Studio Code.

Important

Si vous utilisez un registre privé comme Azure Container Registry pour vos images, vous devrez peut-être vous authentifier pour envoyer des images. Utilisez docker login <Azure Container Registry login server> ou az acr login --name <Azure Container Registry name> pour vous authentifier.

Se connecter à Docker

Fournissez les informations d’identification du registre de conteneurs à Docker afin qu’il puisse envoyer (push) votre image du conteneur à stocker dans le registre.

  1. Connectez-vous à Docker avec les informations d’identification Azure Container Registry que vous avez enregistrées après avoir créé le Registre.

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

    Il se peut que vous receviez un avertissement de sécurité recommandant d’utiliser --password-stdin. Bien qu’il s’agit d’une bonne pratique recommandée pour les scénarios de production, elle est en dehors de l’étendue de ce didacticiel. Pour plus d’informations, consultez la référence docker login.

  2. Connectez-vous au Azure Container Registry. Vous devrez peut-être Installer Azure CLI pour utiliser la commande az. Cette commande demande votre nom d’utilisateur et votre mot de passe trouvés dans votre registre de conteneurs dans lesclés d’accès>.

    az acr login -n <Azure Container Registry name>

Conseil

Si vous êtes déconnecté à un moment quelconque de ce didacticiel, répétez les étapes de connexion à Docker et Azure Container Registry pour continuer.

Générer l’image Docker du module

Utilisez le fichier Dockerfile du module pour générer l’image Docker.

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

Par exemple, pour générer l’image pour le registre local ou un Azure Container Registry, utilisez les commandes suivantes :

# 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"

Pousser (push) l’image Docker du module

Poussez votre image de module vers le registre local ou un registre de conteneurs.

docker push <ImageName>

Exemple :

# 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

Déployer le module sur l’appareil IoT Edge

Utilisez la commande IoT Edge Azure CLI set-modules pour déployer les modules sur le Azure IoT Hub. Par exemple, pour déployer les modules définis dans le fichier deployment.debug.template.json sur IoT Hub my-iot-hub pour l’appareil IoT Edge my-device, utilisez la commande suivante :

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>"

Conseil

Vous trouverez votre clé d’accès partagé IoT Hub dans le portail Azure dans vos paramètres de sécurité IoT Hub >Sécurité>Politiques d'accès partagé>iothubowner.

Déboguer votre module

Pour déboguer des modules sur un appareil distant, utilisez le débogage SSH distant dans Visual Studio Code.

Activez le débogage distant de Visual Studio Code en installant l'extension « Remote Development ». Pour plus d’informations sur le débogage à distance avec Visual Studio Code, consultez Développement à distance avec Visual Studio Code.

Pour plus d’informations sur l’utilisation du débogage SSH distant dans Visual Studio Code, consultez Remote Development using SSH.

Dans la vue de débogage Visual Studio Code, sélectionnez le fichier de configuration de débogage du module. Par défaut, le fichier .debug Dockerfile, les paramètres createOptions de conteneur du module et le fichier launch.json utilisent localhost.

Sélectionnez Démarrer le débogage ou F5, puis sélectionnez le processus auquel attacher. Dans la vue de débogage Visual Studio Code, vous voyez des variables dans le volet gauche.

Déboguer à l’aide de Docker remote SSH

Les moteurs Docker et Moby prennent en charge les connexions SSH aux conteneurs, ce qui vous permet de déboguer dans Visual Studio Code connecté à un appareil distant. Avant de pouvoir utiliser cette fonctionnalité, vous devez respecter les prérequis suivants.

Les prérequis de débogage SSH distants peuvent différer selon le langage que vous utilisez. Les sections suivantes décrivent la configuration de .NET. Pour plus d’informations sur d’autres langages, consultez le développement à distance à l’aide de SSH pour obtenir une vue d’ensemble. Vous trouverez plus d’informations sur la configuration du débogage à distance dans les sections de débogage de chaque langue de la documentation Visual Studio Code.

Configurer le tunneling Docker SSH

  1. Suivez les étapes de tunneling Docker SSH pour configurer le tunneling SSH sur votre ordinateur de développement. Le tunneling SSH nécessite une authentification par paire de clés publique/privée et un contexte Docker définissant le point de terminaison de l’appareil distant.

  2. La connexion à Docker nécessite des privilèges racine. Effectuez les étapes dans Gérer Docker en tant qu’utilisateur non-root pour autoriser la connexion au démon Docker sur l’appareil distant. Une fois le débogage terminé, vous pouvez supprimer votre utilisateur du groupe Docker.

  3. Dans Visual Studio Code, utilisez la palette de commandes (Ctrl+Maj+P) pour entrer la commande Docker Context : Use afin d'activer le contexte Docker qui pointe vers l’ordinateur distant. Cette commande permet à la fois Visual Studio Code et Docker CLI d’utiliser le contexte de l’ordinateur distant.

    Conseil

    Toutes les commandes Docker utilisent le contexte actuel. N’oubliez pas de revenir au contexte par défaut quand vous avez fini de déboguer.

  4. Pour vérifier que le contexte Docker distant est actif, listez les conteneurs en cours d’exécution sur l’appareil distant :

    docker ps

    La sortie répertorie les conteneurs s’exécutant sur l’appareil distant de la manière suivante :

    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. Dans le répertoire .vscode, ouvrez launch.json dans Visual Studio Code et ajoutez une nouvelle configuration. Sélectionnez Ajouter une configuration, puis choisissez le modèle d’attachement à distance correspondant pour votre module. Par exemple, la configuration suivante concerne .NET Core. Remplacez la valeur du paramètre -H dans PipeArgs par le nom DNS ou l’adresse IP de votre appareil.

    "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
},

Déboguer à distance votre module

  1. Dans la vue Débogage de Visual Studio Code, sélectionnez la configuration de débogage Remote Debug IoT Edge Module (.NET Core).

  2. Sélectionnez Démarrer le débogage ou F5. Sélectionnez le processus à attacher.

  3. Dans le volet Débogage de Visual Studio Code, vous voyez les variables dans le panneau de gauche.

  4. Dans Visual Studio Code, définissez des points d’arrêt dans votre module personnalisé.

  5. Lorsqu’un point d’arrêt est atteint, vous pouvez inspecter les variables, parcourir le code et déboguer votre module.

    Capture d'écran de Visual Studio Code connecté à un conteneur Docker sur un appareil distant en pause à un point d'arrêt.

Remarque

L’exemple précédent montre comment déboguer des modules IoT Edge sur des conteneurs distants. L’exemple ajoute un contexte Docker distant et modifie les privilèges Docker sur l’appareil distant. Une fois le débogage de vos modules terminé, définissez votre contexte Docker sur default et supprimez les privilèges de votre compte utilisateur.

Pour obtenir un exemple d’utilisation d’un appareil Raspberry Pi, consultez ce billet de blog IoT Developer.

Étapes suivantes

Après avoir construit votre module, découvrez comment déployer des modules Azure IoT Edge.

Pour développer des modules pour vos appareils IoT Edge, découvrez et utilisez des sdk Azure IoT Hub.

  • Last updated on