Déboguer des modules Azure IoT Edge à l’aide de Visual Studio Code
S’applique à : IoT Edge 1.5
IoT Edge 1.4
Important
IoT Edge 1.5 LTS et IoT Edge 1.4 LTS sont des versions prises en charge. IoT Edge 1.4 LTS sera en fin de vie le 12 novembre 2024. 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 :
- Extension Azure IoT Edge. L’extension Outils Azure IoT Edge pour Visual Studio Code est en mode maintenance.
- Extension Azure IoT Hub.
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.
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" } } } }, ...
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\"}]}}}" }
- Dans la palette de commandes Visual Studio Code, exécutez la commande Azure IoT Edge: Build and Push IoT Edge solution.
- Sélectionnez le fichier
deployment.debug.template.json
de votre solution. - 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.
- 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.
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.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
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.
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.
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.
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.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
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://[email protected]: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
En mode débogage dans Visual Studio Code, sélectionnez la configuration de débogage Remote Debug IoT Edge Module (.NET Core).
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.
Dans Visual Studio Code, définissez des points d’arrêt dans votre module personnalisé.
Lorsqu’un point d’arrêt est atteint, vous pouvez inspecter les variables, parcourir le code et déboguer votre module.
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.
Pour développer des modules pour vos appareils IoT Edge, consultez Comprendre et utiliser les kits Azure IoT Hub SDK.