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

  • Article

S’applique à :IoT Edge 1.4 checkmark IoT Edge 1.4

Important

IoT Edge 1.4 est la version prise en charge. Si vous utilisez une version antérieure, consultez l’article Mettre à jour 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, vous pouvez utiliser Visual Studio Code pour attacher et déboguer votre module dans un conteneur de module local ou distant.

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

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

Utilisez le bouton sélecteur d’outils au début de cet article pour sélectionner la version de l’outil.

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

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

Azure IoT Edge prend en charge les architectures d’appareil suivantes :

  • 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.

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

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

Si vous n’êtes pas familiarisé avec les fonctionnalités de débogage de Visual Studio Code, consultez Débogage dans Visual Studio Code.

Prérequis

Vous pouvez utiliser un ordinateur ou une machine virtuelle Windows, macOS ou Linux comme machine de développement. Sur les ordinateurs Windows, vous pouvez développer des modules Windows ou Linux. Pour développer des modules Linux, utilisez un ordinateur Windows qui est conforme à la configuration requise pour Docker Desktop.

Pour installer les outils requis pour le développement et le débogage, suivez le tutoriel Développer des modules Azure IoT Edge avec Visual Studio Code.

Installer Visual Studio Code

Ajoutez les extensions suivantes :

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

  • Un hub IoT actif avec au moins un appareil IoT Edge.
  • Un appareil IoT Edge physique ou un appareil virtuel. Pour créer un appareil virtuel dans Azure, effectuez les étapes du guide de démarrage rapide pour Linux.
  • Ajouter un module IoT Edge personnalisé. Pour créer un module personnalisé, suivez les étapes du tutoriel Développer des modules Azure IoT Edge avec Visual Studio Code.

Déboguer sans conteneur en utilisant le 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 IoT Edge pour développer et tester vos modules IoT Edge sans appareil physique ni runtime d’appareil IoT Edge complet.

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 du tutoriel Développer des modules Azure IoT Edge avec Visual Studio Code.

Le débogage d’un module sans conteneur n’est pas disponible si vous utilisez C ou Python.

Déboguer en mode attachement avec le simulateur IoT Edge

Le débogage en mode attachement n’est pas pris en charge pour C ou Python.

Déboguer un module avec le runtime IoT Edge

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

Quand vous déboguez des modules en utilisant cette méthode, vos modules s’exécutent par-dessus le runtime IoT Edge. L’appareil IoT Edge et Visual Studio Code peuvent se trouver sur la même machine. Cependant, Visual Studio Code s’exécute généralement sur la machine de développement, tandis que le runtime et les modules IoT Edge s’exécutent sur une autre machine physique. Pour déboguer dans Visual Studio Code, vous devez :

  • Configurer votre appareil IoT Edge, générer vos modules IoT Edge avec le Dockerfile .debug, puis déployer sur l’appareil IoT Edge.
  • Mettez à jour launch.json afin que Visual Studio Code puisse être joint au processus dans un conteneur présent sur la machine distante. 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 de déploiement qui décrit les modules à configurer sur l’appareil IoT Edge ciblé. Avant le déploiement, vous devez mettre à jour vos informations d’identification Azure Container Registry et vos images de module avec les valeurs createOptions appropriées. Pour plus d’informations sur les valeurs createOption, consultez Guide pratique pour configurer les options de création de conteneur pour les modules IoT Edge.

  1. Si vous utilisez un registre Azure Container Registry pour stocker votre image de module, ajoutez vos informations d’identification à la section registre des edgeAgent>paramètres>registryCredentials 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. Par 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 de filtermodule doit ressembler à ce qui suit :

    "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: Build and Push IoT Edge solution.
  2. Sélectionnez le fichier deployment.debug.template.json de votre solution.
  3. Dans la section Azure IoT Hub>Appareils de la vue Explorateur Visual Studio Code, cliquez avec le bouton droit sur le nom de l’appareil IoT Edge pour le déploiement, puis choisissez Créer un déploiement pour un seul appareil.

    Conseil

    Pour vous assurer que l'appareil choisi est un appareil IoT Edge, sélectionnez-le afin de développer la liste des modules et vérifiez 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.

Vous pouvez vérifier l’état de votre conteneur à partir de votre appareil ou de votre machine virtuelle en exécutant la commande docker ps 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, vous pouvez également vérifier l’état dans la vue Docker de 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 (push) des images. Utilisez docker login <Azure Container Registry login server> ou az acr login --name <Azure Container Registry name> pour l’authentification.

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 de l’Azure Container Registry que vous avez enregistré 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. Nous recommandons cette meilleure pratique pour les scénarios de production, mais elle sort de l’étendue de ce tutoriel. Pour plus d’informations, consultez les informations de référence sur docker login.

  2. Connectez-vous à Azure Container Registry. Vous devrez peut-être installer Azure CLI pour utiliser la commande az. Cette commande requiert vos nom d’utilisateur et mot de passe trouvés dans votre registre de conteneurs dans Paramètres>Clés d’accès.

    az acr login -n <Azure Container Registry name>

Conseil

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

Générer l’image Docker du module

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

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

Envoyez (push) votre image de module vers le registre local ou un registre de conteneurs.

docker push <ImageName>

Par 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 hub Azure IoT. Par exemple, pour déployer les modules définis dans le fichier deployment.debug.template.json sur le hub IoT 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 >Paramètres de sécurité>Stratégies d’accès partagé>iothubowner au niveau de votre service IoT Hub.

Déboguer votre module

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

Pour activer le débogage à distance de Visual Studio Code, installez l’extension de développement à distance. Pour plus d’informations sur le débogage à distance de Visual Studio Code, consultez Visual Studio Code Remote Development.

Pour plus d’informations sur l’utilisation du débogage SSH distant dans Visual Studio Code, consultez Développement à distance avec SSH

Dans l'affichage Débogage de Visual Studio Code, sélectionnez le fichier de configuration du débogage de votre 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. Sélectionnez le processus à attacher. Les variables apparaissent dans le volet de gauche de l'affichage Débogage de Visual Studio Code.

Déboguer avec 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 en étant 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 être différents en fonction du 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. Effectuez les étapes dans 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 de niveau root. 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 émettre la commande Docker Context: Use afin d’activer le contexte Docker pointant vers l’ordinateur distant. Cette commande oblige Visual Studio Code et Docker CLI à 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 doit lister les conteneurs en cours d’exécution sur l’appareil distant :

    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.4                            "/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.4                          "/bin/sh -c 'exec /a…"    24 hours ago   Up 6 minutes                                                                                                    
                                       edgeAgent

  5. Dans le répertoire .vscode, ajoutez une nouvelle configuration à launch.json en ouvrant le fichier dans Visual Studio Code. Sélectionnez Ajouter une configuration, puis choisissez le modèle d’attachement à distance correspondant pour votre module. Voici par exemple la configuration pour .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. En mode débogage dans 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. Les variables apparaissent dans le volet de gauche de l'affichage Débogage de Visual Studio Code.

  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.

    Screenshot of Visual Studio Code attached to a Docker container on a remote device paused at a breakpoint.

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

Une fois votre module généré, découvrez comment déployer des modules Azure IoT Edge à partir de Visual Studio Code.

Pour développer des modules pour vos appareils IoT Edge, consultez Comprendre et utiliser les kits Azure IoT Hub SDK.