Utiliser Visual Studio 2022 pour développer et déboguer des modules pour Azure IoT Edge

1. Dans l’Explorateur de solutions, cliquez avec le bouton de droite sur le nom de votre projet principal, puis sélectionnez Définir la version du runtime IoT Edge.

   

2. Utilisez le menu déroulant pour choisir la version du runtime que vos appareils IoT Edge exécutent, puis sélectionnez OK pour enregistrer vos modifications. Si aucune modification n’a été apportée, sélectionnez Annuler pour quitter.

   Actuellement, l’extension n’inclut pas de sélection pour les dernières versions du runtime. Si vous souhaitez définir la version du runtime supérieure à 1.2, ouvrez le fichier manifeste de déploiement deployment.debug.template.json . Modifiez la version du runtime pour les images de module du runtime système edgeAgent et edgeHub. Par exemple, si vous souhaitez utiliser la version 1.5 du runtime IoT Edge, modifiez les lignes suivantes dans le fichier manifeste de déploiement :

   "systemModules": {
      "edgeAgent": {
       //...
         "image": "mcr.microsoft.com/azureiotedge-agent:1.5"
       //...
      "edgeHub": {
      //...
         "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
      //...
   

3. Si vous avez modifié la version, générez à nouveau votre manifeste de déploiement en cliquant avec le bouton droit sur le nom de votre projet, puis sélectionnez Générer le déploiement pour IoT Edge. Cela génère un manifeste de déploiement basé sur votre modèle de déploiement, qui apparaît dans le dossier config de votre projet Visual Studio.

1. Ouvrez le fichier manifeste de déploiement deployment.debug.template.json. Le manifeste de déploiement est un document JSON qui décrit les modules devant être configurés sur l’appareil IoT Edge ciblé.

2. Modifiez la version du runtime pour les images de module du runtime système edgeAgent et edgeHub. Par exemple, si vous souhaitez utiliser la version 1.5 du runtime IoT Edge, modifiez les lignes suivantes dans le fichier manifeste de déploiement :

   "systemModules": {
       "edgeAgent": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
       //...
       "edgeHub": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
       //...
   

Déboguer à l’aide du simulateur

L’outil de développement hub Azure IoT Edge fournit une expérience de développement et débogage locale. L’outil aide à démarrer des modules IoT Edge sans le runtime IoT Edge de façon à pouvoir créer, développer, tester, exécuter et déboguer des modules et solutions IoT Edge localement. Vous n’êtes pas obligé d’envoyer des images à un registre de conteneurs et de les déployer sur un appareil à des fins de test.

Pour plus d’informations, consultez Azure IoT EdgeHub Dev Tool.

Pour initialiser l’outil dans Visual Studio :

1. Récupérez la chaîne de connexion de votre appareil IoT Edge (disponible dans votre IoT Hub) à partir du portail Azure ou d’Azure CLI.

   Si vous utilisez l’interface CLI pour récupérer votre chaîne de connexion, utilisez cette commande, en remplaçant « [device_id] » et « [hub_name] » par vos propres valeurs :

   az iot hub device-identity connection-string show --device-id [device_id] --hub-name [hub_name]
   

2. Dans le menu Outils dans Visual Studio, sélectionnez Azure IoT Edge Tools>Configurer un simulateur IoT Edge.

3. Collez la chaîne de connexion, puis sélectionnez OK.

Générer et déboguer un seul module

En général, il est préférable de tester et de déboguer chaque module avant de l’exécuter au sein d’une solution entière avec plusieurs modules. L’outil de simulateur IoT Edge vous permet d’exécuter un seul module de manière isolée et d’envoyer des messages sur le port 53000.

1. Dans Explorateur de solutions, sélectionnez et mettez en surbrillance le dossier du projet de module (par exemple, IotEdgeModule1). Définissez le module personnalisé comme projet de démarrage. SélectionnezProjet> Définir comme projet de démarrage dans le menu.

2. Appuyez sur F5 ou sélectionnez le bouton Exécuter la barre d’outils pour démarrer le simulateur de IoT Edge pour un seul module. Cela peut prendre 10 à 20 secondes au départ.

   

3. Si le module a été initialisé avec succès, vous devriez voir apparaître une fenêtre d’application console .NET Core.

4. Définissez un point d’arrêt pour inspecter le module.

   • Si vous développez en C#, définissez un point d’arrêt dans la fonction PipeMessage() dans ModuleBackgroundService.cs.
   • Si vous utilisez C, définissez un point d’arrêt dans la fonction InputQueue1Callback() dans InputQueue1Callback().

5. Testez le module en envoyant un message. Lorsque vous déboguez un seul module, le simulateur écoute les messages sur le port par défaut 53000. Pour envoyer un message à votre module, exécutez la commande curl suivante à partir d’un interpréteur de commandes comme Git Bash ou WSL Bash.

   curl --header "Content-Type: application/json" --request POST --data '{"inputName": "input1","data":"hello world"}' http://localhost:53000/api/v1/messages
   

   Si vous obtenez l’erreur Accolade/crochet fermant sans correspondance dans l’URL, essayez à la place la commande suivante :

   curl --header "Content-Type: application/json" --request POST --data "{\"inputName\": \"input1\", \"data\", \"hello world\"}"  http://localhost:53000/api/v1/messages
   

   

   Le point d’arrêt doit être déclenché. Vous pouvez observer les variables dans la fenêtre Variables locales de Visual Studio, disponible lorsque le débogueur est en cours d’exécution. Accédez à Déboguer >Windows>Local.

   Dans votre interpréteur de commandes Bash ou shell, vous devriez voir une confirmation {"message":"accepted"}.

   Dans votre console .NET, vous devriez voir :

   IoT Hub module client initialized.
   Received message: 1, Body: [hello world]
   

6. Appuyez sur Ctrl+F5 ou sélectionnez le bouton Arrêter pour arrêter le débogage.

Générer et déboguer plusieurs modules

Une fois que nous avons fini de développer un module, nous pouvons exécuter et déboguer une solution entière avec plusieurs modules. L’outil de simulateur IoT Edge vous permet d’exécuter tous les modules définis dans le manifeste de déploiement, y compris un edgeHub simulé pour le routage des messages. Dans cet exemple, vous exécutez deux modules personnalisés et le module capteur de température simulé. Les messages du module de capteur de température simulé sont routés vers chaque module personnalisé.

1. Dans Explorateur de solutions, ajoutez un deuxième module à la solution en cliquant avec le bouton droit sur le dossier du projet principal. Dans le menu, sélectionnez Ajouter>Nouveau module IoT Edge.

   

2. Dans la fenêtre Add module, donnez un nom à votre nouveau module et remplacez la partie localhost:5000 de l’URL du référentiel par votre serveur de connexion Azure Container Registry, comme vous l’avez fait précédemment.

3. Ouvrez le fichier deployment.debug.template.json et constatez que le nouveau module a été ajouté dans la section modules. Un nouvel itinéraire a également été ajouté à la section routes dans EdgeHub pour envoyer des messages du nouveau module à IoT Hub. Pour envoyer des données du capteur de température simulé au nouveau module, ajoutez un autre itinéraire comme dans avec la ligne suivante de JSON. Remplacez <NewModuleName> (à deux emplacements) par votre propre nom de module.

   "sensorTo<NewModuleName>": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/<NewModuleName>/inputs/input1\")"
   

4. Cliquez avec le bouton droit sur le projet principal (par exemple AzureIotEdgeApp1) et sélectionnez Définir en tant que projet de démarrage. En définissant le projet principal comme projet de démarrage, tous les modules de la solution s’exécutent. Cela inclut les deux modules que vous avez ajoutés à la solution, le module capteur de température simulé et le hub Edge simulé.

5. Appuyez sur F5 ou sélectionnez le bouton Exécuter de la barre d’outils pour exécuter la solution. Cela peut prendre 10 à 20 secondes au départ. Assurez-vous que vous n’avez pas d’autres conteneurs Docker en cours d’exécution qui peuvent lier le port dont vous avez besoin pour ce projet.

6. Deux fenêtres d’application console .NET Core doivent apparaître une pour chaque module.

7. Définissez un point d’arrêt pour inspecter les modules.

   • Si vous développez en C#, définissez un point d’arrêt dans la fonction PipeMessage() dans ModuleBackgroundService.cs.
   • Si vous utilisez C, définissez un point d’arrêt dans la fonction InputQueue1Callback() dans InputQueue1Callback().

8. Créez des points d’arrêt dans chaque module, puis appuyez sur F5 pour exécuter et déboguer plusieurs modules simultanément. Vous devriez voir plusieurs fenêtres d’applications console .NET Core, chacune d’elles représentant un module différent.

   

9. Appuyez sur Ctrl+F5 ou sélectionnez le bouton Arrêter pour arrêter le débogage.

Générer et envoyer (push) des images au registre

Une fois que vous avez développé et débogué votre module, vous pouvez générer et envoyer (push) l’image du module à votre Azure Container Registry. Vous pouvez ensuite déployer le module sur votre appareil IoT Edge.

1. Définir le projet principal de IoT Edge est le projet de démarrage, pas l’un des modules individuels.

2. Sélectionnez Déboguer ou Publier comme configuration pour générer vos images de module.

   Remarque

   Lorsque vous choisissez Déboguer, Visual Studio utilise Dockerfile.(amd64|windows-amd64).debug pour générer des images Docker. Ceci inclut le débogueur en ligne de commande .NET Core (VSDBG) dans votre image conteneur lors de sa génération. Pour obtenir des modules IoT Edge prêts pour la production, nous vous recommandons d’utiliser la configuration Publier qui utilise Dockerfile.(amd64|windows-amd64) sans VSDBG.

3. Si vous utilisez un registre privé tel qu’Azure Container Registry (ACR), servez-vous de la commande Docker suivante pour vous y connecter. Vous pouvez récupérer le nom d’utilisateur et le mot de passe à partir de la page Clés d’accès de votre registre dans le Portail Azure.

   docker login <ACR login server>
   

4. Ajoutons les informations de connexion Azure Container Registry aux paramètres d’exécution trouvés dans le fichier deployment.debug.template.json. Il existe deux façons d'effectuer cette opération. Vous pouvez ajouter vos informations d’identification à votre fichier .env (plus sûr) ou les ajouter directement à votre fichier deployment.debug.template.json.

   Ajoutez les informations d’identification à votre fichier .env :

   Dans l’Explorateur de solutions, sélectionnez le bouton Afficher tous les fichiers. Le fichier .env s’affiche. Ajoutez votre nom d’utilisateur et votre mot de passe Azure Container Registry à votre fichier .env. Ces informations d’identification sont disponibles sur la page Clés d’accès d’Azure Container Registry dans le portail Azure.

   

       DEFAULT_RT_IMAGE=1.2
       CONTAINER_REGISTRY_USERNAME_myregistry=<my-registry-name>
       CONTAINER_REGISTRY_PASSWORD_myregistry=<my-registry-password>
   

   Ajouter les informations d’identification directement dans deployment.debug.template.json

   Si vous préférez ajouter vos informations d’identification directement à votre modèle de déploiement, remplacez les espaces réservés par votre nom d’utilisateur administrateur ACR, votre mot de passe et votre nom de registre.

         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "registry1": {
               "username": "<username>",
               "password": "<password>",
               "address": "<registry name>.azurecr.io"
             }
           }
         }
   

   Remarque

   Cet article utilise les informations d’identification de l’administrateur pour Azure Container Registry, qui conviennent pour des scénarios de développement et de test. Lorsque vous êtes prêt pour les scénarios de production, nous vous recommandons d’utiliser l’option d’authentification de moindre privilège, comme les principaux de service. Pour plus d’informations, consultez Gérer l’accès au registre de conteneurs.

5. Si vous utilisez un registre local, vous pouvez exécuter un registre local.

6. Enfin, dans Explorateur de solutions, cliquez avec le bouton droit sur le projet de dossier principal, puis sélectionnez Générer et envoyer (push) les modules IoT Edge afin de générer et envoyer l’image Docker pour chaque module. Cette opération peut prendre une minute. Lorsque vous voyez Finished Build and Push IoT Edge Modules. dans la console de sortie de Visual Studio, vous avez terminé.

Déployer la solution

Maintenant que vous avez créé et poussé vos images de module vers votre Azure Container Registry, vous pouvez déployer la solution sur votre appareil IoT Edge. Vous disposez déjà d’un modèle de manifeste de déploiement que vous avez observé tout au long de ce tutoriel. Nous allons générer un manifeste de déploiement à partir de celui-ci, puis utiliser une commande Azure CLI pour déployer vos modules sur votre appareil IoT Edge dans Azure.

1. Cliquez avec le bouton droit sur votre projet principal dans l’Explorateur de solutions Visual Studio et choisissez Générer le déploiement pour IoT Edge.

   

2. Accédez à votre dossier de projet principal Visual Studio local et recherchez le dossier config. Le chemin d’accès du fichier peut se présenter de la façon suivante : C:\Users\<YOUR-USER-NAME>\source\repos\<YOUR-IOT-EDGE-PROJECT-NAME>\config. Ici figure le manifeste de déploiement généré, par exemple deployment.amd64.debug.json.

3. Vérifiez votre fichier deployment.amd64.debug.json pour confirmer que la version du schéma edgeHub est définie sur 1.2.

    "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.2",
          "routes": {
            "IotEdgeModule2022ToIoTHub": "FROM /messages/modules/IotEdgeModule2022/outputs/* INTO $upstream",
            "sensorToIotEdgeModule2022": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/IotEdgeModule2022/inputs/input1\")",
            "IotEdgeModule2022bToIoTHub": "FROM /messages/modules/IotEdgeModule2022b/outputs/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      }
   

   Conseil

   Le modèle de déploiement pour Visual Studio 2022 nécessite la version de schéma 1.2. Si vous avez besoin de la version 1.1 ou 1.0, attendez jusqu’à ce que le déploiement soit généré (ne le modifiez pas dans deployment.debug.template.json). La génération d’un déploiement crée par défaut un schéma 1.2. Toutefois, vous pouvez modifier manuellement deployment.amd64.debug.json, le manifeste généré, si nécessaire avant de le déployer sur Azure.

   Important

   Une fois que votre appareil IoT Edge est déployé, il ne s’affiche pas correctement dans le portail Azure avec la version de schéma 1.2 (la version 1.1 n’aura pas ce problème). Il s’agit d’un bogue connu qui sera bientôt corrigé. Toutefois, cela n’affecte pas votre appareil, car il est toujours connecté dans IoT Hub et peut communiquer à tout moment à l’aide d’Azure CLI.

   

4. Nous allons maintenant déployer notre manifeste avec une commande Azure CLI. Ouvrez l’Invite de commandes développeur de Visual Studio et accédez au répertoire config.

       cd config
   

5. Déployez le manifeste pour votre appareil IoT Edge sur IoT Hub. La commande configure l’appareil pour utiliser les modules développés dans votre solution. Le manifeste de déploiement a été créé à l’étape précédente et est stocké dans le dossier config. À partir de votre dossier config, exécutez la commande de déploiement suivante. Remplacez [device id], [hub name] et [file path] par vos valeurs. Si l’ID d’appareil IoT Edge n’existe pas dans le hub IoT, il doit être créé.

       az iot edge set-modules --device-id [device id] --hub-name [hub name] --content [file path]
   

   Par exemple, votre commande peut se présenter comme suit :

   az iot edge set-modules --device-id my-device-name --hub-name my-iot-hub-name --content deployment.amd64.debug.json
   

6. Après avoir exécuté la commande, vous verrez une confirmation du déploiement imprimé dans JSON dans votre invite de commandes.

Générer l’image Docker du module

Une fois que vous avez développé votre module, vous pouvez générer l’image de module à stocker dans un registre de conteneurs pour le déploiement sur votre appareil IoT Edge.

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

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

Par exemple, supposons que votre interpréteur de commandes se trouve dans le répertoire de votre projet et que le nom de votre module est IotEdgeModule1. Pour générer l’image pour le registre local ou un registre de conteneurs Azure, utilisez les commandes suivantes :

# Build the image for the local registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t localhost:5000/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Or build the image for an Azure Container Registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

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/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure Container Registry
az acr login --name myacr
docker push myacr.azurecr.io/iotedgemodule1:0.0.1-amd64

Déployer le module sur l’appareil IoT Edge

Dans Visual Studio, ouvrez le fichier manifeste de déploiement deployment.debug.template.json dans le projet principal. Le manifeste de déploiement est un document JSON qui décrit les modules devant être configurés 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 Azure Container Registry pour stocker votre image de module, vous devez ajouter vos informations d’identification à deployment.debug.template.json dans les paramètres edgeAgent. Par exemple,

   "modulesContent": {
   "$edgeAgent": {
     "properties.desired": {
       "schemaVersion": "1.1",
       "runtime": {
         "type": "docker",
         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "myacr": {
               "username": "myacr",
               "password": "<your_acr_password>",
               "address": "myacr.azurecr.io"
             }
           }
         }
       },
   //...
   

2. Remplacez la valeur de la propriété image par le nom de l’image de module que vous avez envoyée au registre. Par exemple, si vous avez envoyé (push) une image marquée myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 pour le module personnalisé IotEdgeModule1, remplacez la valeur de la propriété image par la valeur de balise.

3. Ajoutez ou remplacez la valeur createOptions par du contenu en chaîne pour chaque système et module personnalisé dans le modèle de déploiement.

   Par exemple, les paramètres image etcreateOptions de iotEdgeModule1 sont similaires à ce qui suit :

   "IotEdgeModule1": {
   "version": "1.0.0",
   "type": "docker",
   "status": "running",
   "restartPolicy": "always",
   "settings": {
       "image": "myacr.azurecr.io/iotedgemodule1:0.0.1-amd64",
       "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
   }
   

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