Tutoriel : Développer des modules 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.

Ce tutoriel vous montre pas à pas comment développer et déployer votre propre code sur un appareil IoT Edge. Vous pouvez utiliser des modules Azure IoT Edge pour déployer un code qui implémente votre logique métier directement sur vos appareils IoT Edge. Dans le guide de démarrage rapide Déployer du code sur un appareil Linux, vous avez créé un appareil IoT Edge et déployé un module à partir de la Place de marché Azure.

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

  • Interface CLI des outils de développement Azure IoT Edge. 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.

Dans ce tutoriel, vous allez apprendre à :

  • Configurer votre machine de développement
  • Utiliser les outils IoT Edge pour créer un projet.
  • Générer votre projet sous forme de conteneur Docker et le stocker dans un registre de conteneurs Azure.
  • Déployer votre code sur un appareil IoT Edge

Le module IoT Edge que vous créez dans ce didacticiel filtre les données de température générées par votre appareil. Il envoie uniquement des messages en amont lorsque la température dépasse un seuil spécifié. Ce type d’analyse à la périphérie est utile pour réduire la quantité de données communiquées et stockées dans le cloud.

Prérequis

Une machine de développement :

  • Utilisez votre propre ordinateur ou une machine virtuelle.
  • Votre machine de développement doit prendre en charge la virtualisation imbriquée pour l’exécution d’un moteur de conteneur.
  • La plupart des systèmes d’exploitation qui exécutent un moteur de conteneur peuvent servir à développer des modules IoT Edge pour appareils Linux. Ce tutoriel utilise un ordinateur Windows, mais souligne des différences connues sur macOS ou Linux.
  • Installer Visual Studio Code
  • Installez Azure CLI.

Un appareil Azure IoT Edge :

Ressources cloud :

  • Un hub IoT de niveau gratuit ou standard dans Azure.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit Azure avant de commencer.

Conseil

Pour obtenir des conseils sur le débogage interactif dans Visual Studio Code ou Visual Studio 2022 :

Ce tutoriel décrit les étapes de développement pour Visual Studio Code.

Concepts clés

Ce tutoriel présente le développement d’un module IoT Edge. Un module IoT Edge est un conteneur avec du code exécutable. Vous pouvez déployer un ou plusieurs modules sur un appareil IoT Edge. Les modules effectuent des tâches spécifiques comme l’ingestion de données provenant de capteurs, le nettoyage et l’analyse de données ou encore l’envoi de messages à un hub IoT. Pour plus d’informations, consultez Présentation des modules Azure IoT Edge.

Lors du développement de modules IoT Edge, il est important de comprendre la différence entre la machine de développement et l’appareil IoT Edge cible où le module est déployé. Le conteneur que vous générez pour le stockage du code du module doit correspondre au système d’exploitation (OS) de l’appareil cible. Par exemple, le scénario le plus courant est le développement d’un module sur un ordinateur Windows avec l’intention de cibler un appareil Linux exécutant IoT Edge. Dans ce cas, le système d’exploitation du conteneur est Linux. À mesure que vous parcourez ce tutoriel, gardez à l’esprit la différence entre système d’exploitation de la machine de développement et système d’exploitation du conteneur.

Conseil

Si vous utilisez IoT Edge pour Linux sur Windows, l’appareil cible dans votre scénario est la machine virtuelle Linux, et non l’hôte Windows.

Ce tutoriel cible les appareils exécutant IoT Edge avec des conteneurs Linux. Vous pouvez utiliser le système d’exploitation de votre choix, à condition que votre machine de développement exécute des conteneurs Linux. Visual Studio Code étant recommandé pour développer avec des conteneurs Linux, nous l’utilisons dans le cadre de ce tutoriel. Vous pouvez aussi bien utiliser Visual Studio, bien qu’il existe des différences de prise en charge entre les deux outils.

Le tableau suivant liste les scénarios de développement pris en charge pour des conteneurs Linux dans Visual Studio Code et Visual Studio.

Visual Studio Code Visual Studio 2019/2022
Architecture d’appareil Linux Linux AMD64
Linux ARM32v7
Linux ARM64		 Linux AMD64
Linux ARM32
Linux ARM64
Services Azure Azure Functions
Azure Stream Analytics
Azure Machine Learning
Langues C
C#
Java
Node.js
Python		 C
C#
Plus d’informations Azure IoT Edge pour Visual Studio Code Outils Azure IoT Edge pour Visual Studio 2019
Outils Azure IoT Edge pour Visual Studio 2022

Installer le moteur de conteneur

Les modules IoT Edge étant empaquetés en tant que conteneurs, vous avez besoin d’un système de gestion de conteneurs compatible avec Docker sur votre ordinateur de développement pour les générer et les gérer. Nous vous recommandons d’utiliser Docker Desktop pour le développement en raison de sa prise en charge des fonctionnalités et de sa popularité. Docker Desktop sur Windows vous permet de basculer entre les conteneurs Linux et Windows, et donc de développer aisément des modules pour différents types d’appareils IoT Edge.

Utilisez la documentation Docker pour effectuer les différentes procédures d’installation sur votre machine de développement :

  • Installer Docker Desktop pour Windows

    • Quand vous installez Docker Desktop pour Windows, vous êtes invité à indiquer si vous souhaitez utiliser des conteneurs Linux ou Windows. Vous pouvez modifier cette décision à tout moment. Pour ce tutoriel, nous utilisons des conteneurs Linux, car nos modules ciblent les appareils Linux. Pour plus d’informations, consultez Switch between Windows and Linux containers.

  • Installer Docker Desktop pour Mac

  • Lisez About Docker CE pour obtenir des informations sur l’installation sur plusieurs plateformes Linux.

    • Pour le Sous-système Windows pour Linux (WSL), installez Docker Desktop pour Windows.

Configurer des outils

Installez l’outil de développement Azure IoT Edge basé sur Python pour créer votre solution IoT Edge. Nous avons deux options :

Important

L’extension Outils Azure IoT Edge pour Visual Studio Code est en mode maintenance. L’outil de développement préféré est l’interface CLI des outils de développement Azure IoT Edge.

Utilisez les extensions IoT pour Visual Studio Code pour développer des modules IoT Edge. Ces extensions offrent des modèles de projet, automatisent la création du manifeste de déploiement et vous permettent de superviser, puis de gérer des appareils IoT Edge. Dans cette section, vous installez Visual Studio Code et l’extension IoT, puis configurez votre compte Azure pour gérer les ressources IoT Hub à partir de Visual Studio Code.

  1. Installez l’extension Azure IoT Edge.

  2. Installez l’extension Azure IoT Hub.

  3. Après l’installation des extensions, ouvrez la palette de commandes en sélectionnant Affichage>palette de commandes.

  4. De nouveau dans la palette de commandes, recherchez et sélectionnez Azure IoT Hub: Select IoT Hub (Azure IoT Hub : Sélectionner IoT Hub). Suivez les invites pour sélectionner votre abonnement Azure et IoT Hub.

  5. Ouvrez la section Explorateur de Visual Studio Code en sélectionnant l’icône dans la barre d’activités sur la gauche, ou en sélectionnant Affichage>Explorateur.

  6. En bas de la section Explorateur, développez le menu Azure IoT Hub / Appareils réduit. Vous devez voir les appareils et les appareils IoT Edge associés au hub IoT Hub que vous avez sélectionné via la palette de commandes.

Installer des outils spécifiques au langage

Installez des outils spécifiques à votre langage de développement :

Créer un registre de conteneur

Dans ce tutoriel, vous utilisez les extensions Azure IoT Edge et Azure IoT Hub pour créer un module et créer une image conteneur à partir des fichiers. Puis envoyez cette image à un registre qui stocke et gère vos images. Enfin, déployez votre image à partir de votre registre de façon à l’exécuter sur votre appareil IoT Edge.

Important

L’extension Azure IoT Edge Visual Studio Code est en mode maintenance.

Vous pouvez utiliser n’importe quel registre Docker pour stocker vos images conteneur. Azure Container Registry et Docker Hub sont deux services de registre Docker connus. Ce didacticiel utilise Azure Container Registry.

Si vous ne disposez pas d’un registre de conteneurs, suivez ces étapes pour en créer un dans Azure :

  1. Dans le portail Azure, sélectionnez Créer une ressource>Conteneurs>Container Registry.

  2. Fournissez les valeurs suivantes qui sont nécessaires pour créer votre registre de conteneurs :

    Champ Valeur
    Abonnement Sélectionnez un abonnement dans la liste déroulante.
    Resource group Utilisez le même groupe de ressources pour toutes les ressources de test que vous créez dans le cadre des tutoriels et guides de démarrage rapide IoT Edge. Par exemple, utilisez IoTEdgeResources.
    Nom du registre Fournissez un nom unique.
    Location Choisissez un emplacement proche de vous.
    SKU Sélectionnez De base.

  3. Sélectionnez Review + create (Vérifier + créer), puis Create (Créer).

  4. Sélectionnez votre nouveau registre de conteneurs dans la section Ressources de la page d’accueil du Portail Azure pour l’ouvrir.

  5. Dans le volet gauche de votre registre de conteneurs, sélectionnez Clés d’accès dans le menu situé sous Paramètres.

    Screenshot of the Access Keys menu location.

  6. Activez Utilisateur administrateur à l'aide du bouton à bascule et affichez le Nom d'utilisateur et le Mot de passe de votre registre de conteneurs.

  7. Copiez les valeurs pour Serveur de connexion, Nom d’utilisateur et Mot de passe, et conservez-les dans un endroit pratique et approprié. Vous utilisez ces valeurs dans le tutoriel pour permettre l’accès au registre de conteneurs.

Créer un projet de module

L’extension Azure IoT Edge offre des modèles de projet pour tous les langages de module IoT Edge pris en charge dans Visual Studio Code. Ces modèles ont tous les fichiers et tout le code dont vous avez besoin pour déployer un module opérationnel afin de tester IoT Edge. Vous pouvez également vous servir de ces modèles comme point de départ et les personnaliser avec votre propre logique métier.

Créer un modèle de projet

L’outil de développement IoT Edge simplifie le développement Azure IoT Edge en commandes pilotées par des variables d’environnement. Il vous permet de vous lancer dans le développement IoT Edge avec le conteneur de développement IoT Edge et la génération de modèles automatique de solution IoT Edge qui contient un module par défaut et tous les fichiers de configuration nécessaires.

  1. Créez un répertoire pour votre solution avec le chemin d’accès de votre choix. Accédez à votre répertoire iotedgesolution.

    mkdir c:\dev\iotedgesolution
cd c:\dev\iotedgesolution

  2. Utilisez la commande iotedgedev solution init pour créer une solution, puis configurer votre service Azure IoT Hub dans le langage de développement de votre choix.

    iotedgedev solution init --template csharp

Le script iotedgedev solution init vous invite à effectuer plusieurs étapes, notamment :

  • Authentification auprès d’Azure
  • Choisir un abonnement Azure
  • Choisir ou créer un groupe de ressources
  • Choisir ou créer un hub IoT Azure
  • Choisir ou créer un appareil Azure IoT Edge

Utilisez Visual Studio Code et l’extension Azure IoT Edge. Vous commencez par créer une solution, puis vous y générez le premier module. Chaque solution peut contenir plusieurs modules.

  1. Sélectionnez Afficher>Palette de commandes.
  2. Dans la palette de commandes, entrez et exécutez la commande Azure IoT Edge: New IoT Edge solution (Azure IoT Edge : Nouvelle solution IoT Edge).
  3. Accédez au dossier où vous souhaitez créer la solution, puis choisissez Sélectionner le dossier.
  4. Entrez un nom pour votre solution.
  5. Sélectionnez un modèle de module correspondant à votre langage de développement préféré. Il s'agira du premier module de la solution.
  6. Entrez un nom pour votre module. Choisissez un nom qui est unique dans le registre de conteneurs.
  7. Indiquez le nom du référentiel d’images du module. Par défaut, Visual Studio Code nomme le module localhost:5000/<nom de votre module>. Remplacez-le par vos propres informations de registre. Utilisez localhost si vous utilisez un registre Docker local pour les tests. Si vous utilisez Azure Container Registry, utilisez le serveur de connexion depuis les paramètres de votre registre. Le serveur de connexion se présente comme suit : <nom du registre>.azurecr.io. Remplacez uniquement la partie localhost:5000 de la chaîne afin d’obtenir le résultat final suivant : <nom du registre>.azurecr.io/ <nom de votre module> .

À partir des informations que vous avez fournies, Visual Studio Code crée une solution IoT Edge, puis la charge dans une nouvelle fenêtre.

Après la création de la solution, les fichiers principaux suivants se trouvent dans la solution :

  • Un dossier .vscode contient le fichier config launch.json.

  • Un dossier modules qui contient des sous-dossiers pour chaque module. Dans le sous-dossier de chaque module, le fichier module.json contrôle la façon dont les modules sont générés et déployés.

  • Un fichier .env, qui liste vos variables d’environnement. La variable d’environnement du registre de conteneurs est localhost 5000 par défaut.

  • Deux fichiers de déploiement de module nommés deployment.template.json et deployment.debug.template répertorient les modules à déployer sur votre appareil. Par défaut, la liste inclut les modules système IoT Edge (edgeAgent et edgeHub) et des exemples de modules tels que les suivants :

    Notes

    Les modules installés peuvent dépendre du langage de votre choix.

Définir la version du runtime IoT Edge

La dernière version stable du module système IoT Edge est la version 1.4. Définissez vos modules système sur la version 1.4.

  1. Dans Visual Studio Code, ouvrez le fichier manifeste de déploiement deployment.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.4 du runtime IoT Edge, modifiez les lignes suivantes dans le fichier manifeste de déploiement :

    "systemModules": {
    "edgeAgent": {

        "image": "mcr.microsoft.com/azureiotedge-agent:1.4",

    "edgeHub": {

        "image": "mcr.microsoft.com/azureiotedge-hub:1.4",

Fournir vos informations d’identification de registre à l’agent IoT Edge

Le fichier d’environnement stocke les informations d’identification de votre registre de conteneurs et les partage avec le runtime IoT Edge. Le runtime a besoin de ces informations d’identification pour extraire vos images de conteneur sur l’appareil IoT Edge.

L’extension IoT Edge tente d’extraire d’Azure vos informations d’identification de registre de conteneurs et de les insérer dans le fichier d’environnement.

Notes

Le fichier d’environnement est créé uniquement si vous fournissez un référentiel d’images pour le module. Si vous avez accepté les valeurs localhost par défaut pour tester et déboguer localement, vous n’avez pas besoin de déclarer des variables d’environnement.

Vérifiez si vos informations d’identification sont présentes. Si ce n’est pas le cas, veuillez les ajouter maintenant :

  1. Si Azure Container Registry est votre registre, définissez un nom d’utilisateur et un mot de passe Azure Container Registry. Obtenez ces valeurs depuis le menu Paramètres>Clés d’accès de votre registre de conteneurs dans le Portail Azure.

  2. Ouvrez le fichier .env dans votre solution de module.

  3. Ajoutez les valeurs de nom d’utilisateur et de mot de passe que vous avez copiées à partir de votre registre de conteneurs Azure. Par exemple :

    CONTAINER_REGISTRY_SERVER="myacr.azurecr.io"
CONTAINER_REGISTRY_USERNAME="myacr"
CONTAINER_REGISTRY_PASSWORD="<registry_password>"

  4. Enregistrez les modifications apportées au fichier .env.

Notes

Ce tutoriel utilise les informations d’identification de l’administrateur pour Azure Container Registry, qui sont pratiques pour les scénarios de développement et de test. Quand vous êtes prêt pour les scénarios de production, nous vous recommandons d’utiliser l’option d’authentification avec les privilèges minimum, comme les principaux de service ou les jetons délimités au dépôt. Pour plus d’informations, consultez Gérer l’accès au registre de conteneurs.

Architecture cible

Vous devez sélectionner l’architecture que vous ciblez avec chaque solution, car cela affecte la façon dont le conteneur est généré, puis exécuté. Linux AMD64 est la valeur par défaut. Pour ce tutoriel, nous utilisons une machine virtuelle Ubuntu en tant qu’appareil IoT Edge, puis conservons la valeur par défaut amd64.

Si vous devez modifier l’architecture cible de votre solution, procédez comme suit.

  1. Ouvrez la palette de commandes et recherchez Azure IoT Edge: Set Default Target Platform for Edge Solution (Azure IoT Edge : définir la plateforme cible par défaut pour la solution Edge), ou sélectionnez l’icône de raccourci dans la barre latérale en bas de la fenêtre.

  2. Dans la palette de commandes, sélectionnez l’architecture cible dans la liste des options.

L’architecture cible est définie lorsque vous créez l’image conteneur lors d’une étape ultérieure.

Mettre à jour un module avec du code personnalisé

Chaque modèle contient un exemple de code qui utilise des simulations de données de capteur du module SimulatedTemperatureSensor, puis les achemine vers le hub IoT. Cet exemple de module reçoit des messages, puis les transfère. La fonctionnalité de pipeline illustre un concept important dans IoT Edge, à savoir la façon dont les modules communiquent entre eux.

Le code de chaque module peut déclarer plusieurs files d’attente d’entrée et de sortie. Le hub IoT Edge en cours d’exécution sur l’appareil route les messages depuis la sortie d’un module vers l’entrée d’un ou de plusieurs modules. Le code utilisé pour la déclaration des entrées et des sorties varie, mais le concept est le même pour tous les modules. Pour plus d’informations sur le routage entre des modules, consultez Déclarer des routes.

L’exemple de code C# qui est fourni avec le modèle de projet utilise la classe ModuleClient du SDK du IoT Hub pour .NET.

  1. Dans l’explorateur de Visual Studio Code, ouvrez modules>filtermodule>ModuleBackgroundService.cs.

  2. Avant l’espace de noms du filtermodule, ajoutez trois instructions using pour les types utilisés ultérieurement :

    using System.Collections.Generic;     // For KeyValuePair<>
using Microsoft.Azure.Devices.Shared; // For TwinCollection
using Newtonsoft.Json;                // For JsonConvert

  3. Ajoutez la variable temperatureThreshold à la classe ModuleBackgroundService. Cette variable définit la valeur que la température mesurée doit dépasser pour que les données soient envoyées à IoT Hub.

    static int temperatureThreshold { get; set; } = 25;

  4. Ajoutez les classes MessageBody, Machine, et Ambient. Ces classes définissent le schéma attendu pour le corps des messages entrants.

    class MessageBody
{
    public Machine machine {get;set;}
    public Ambient ambient {get; set;}
    public string timeCreated {get; set;}
}
class Machine
{
    public double temperature {get; set;}
    public double pressure {get; set;}
}
class Ambient
{
    public double temperature {get; set;}
    public int humidity {get; set;}
}

  5. Recherchez la fonction ExecuteAsync. Cette fonction crée et configurer un objet ModuleClient qui permet au module de se connecter au runtime Azure IoT Edge local pour envoyer et recevoir des messages. Après avoir créé le ModuleClient, le code lit la valeur temperatureThreshold à partir des propriétés souhaitées du jumeau de module. Le code enregistre un rappel pour recevoir des messages du hub IoT Edge via un point de terminaison appelé input1.

    Remplacez la méthode d’appel du ProcessMessageAsync par une nouvelle qui met à jour le nom du point de terminaison et la méthode appelée lorsqu’une entrée arrive. Ajoutez également une méthode SetDesiredPropertyUpdateCallbackAsync pour des mises à jour vers des propriétés désirées. Pour ce faire, remplacez la dernière ligne de la méthode ExecuteAsync par le code suivant :

    // Register a callback for messages that are received by the module.
// await _moduleClient.SetInputMessageHandlerAsync("input1", PipeMessage, cancellationToken);

// Read the TemperatureThreshold value from the module twin's desired properties
var moduleTwin = await _moduleClient.GetTwinAsync();
await OnDesiredPropertiesUpdate(moduleTwin.Properties.Desired, _moduleClient);

// Attach a callback for updates to the module twin's desired properties.
await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertiesUpdate, null);

// Register a callback for messages that are received by the module. Messages received on the inputFromSensor endpoint are sent to the FilterMessages method.
await _moduleClient.SetInputMessageHandlerAsync("inputFromSensor", FilterMessages, _moduleClient);

  6. Ajoutez la méthode onDesiredPropertiesUpdate à la classe ModuleBackgroundService. Cette méthode reçoit des mises à jour sur les propriétés souhaitées à partir du double de module et met à jour la variable temperatureThreshold en conséquence. Tous les modules ont leur propre module jumeau, ce qui vous permet de configurer le code exécuté à l’intérieur d’un module directement à partir du cloud.

    static Task OnDesiredPropertiesUpdate(TwinCollection desiredProperties, object userContext)
{
    try
    {
        Console.WriteLine("Desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));

        if (desiredProperties["TemperatureThreshold"]!=null)
            temperatureThreshold = desiredProperties["TemperatureThreshold"];

    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error when receiving desired property: {0}", exception);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error when receiving desired property: {0}", ex.Message);
    }
    return Task.CompletedTask;
}

  7. Ajoutez la méthode FilterMessages. Cette méthode est appelée chaque fois que le module reçoit un message d’IoT Edge Hub. Il filtre les messages qui signalent des températures situées sous le seuil de température défini via le double de module. Il ajoute également la propriété MessageType au message avec la valeur définie sur Alerte.

    async Task<MessageResponse> FilterMessages(Message message, object userContext)
{
    var counterValue = Interlocked.Increment(ref _counter);
    try
    {
        ModuleClient moduleClient = (ModuleClient)userContext;
        var messageBytes = message.GetBytes();
        var messageString = Encoding.UTF8.GetString(messageBytes);
        Console.WriteLine($"Received message {counterValue}: [{messageString}]");

        // Get the message body.
        var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);

        if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
        {
            Console.WriteLine($"Machine temperature {messageBody.machine.temperature} " +
                $"exceeds threshold {temperatureThreshold}");
            using (var filteredMessage = new Message(messageBytes))
            {
                foreach (KeyValuePair<string, string> prop in message.Properties)
                {
                    filteredMessage.Properties.Add(prop.Key, prop.Value);
                }

                filteredMessage.Properties.Add("MessageType", "Alert");
                await moduleClient.SendEventAsync("output1", filteredMessage);
            }
        }

        // Indicate that the message treatment is completed.
        return MessageResponse.Completed;
    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", exception);
        }
        // Indicate that the message treatment is not completed.
        var moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
        // Indicate that the message treatment is not completed.
        ModuleClient moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
}

  8. Enregistrez le fichier ModuleBackgroundService.cs.

  9. Dans l’Explorateur Visual Studio Code, ouvrez le fichier deployment.template.json dans votre espace de travail de solution IoT Edge.

  10. Étant donné que nous avons modifié le nom du point de terminaison sur lequel le module écoute, nous devons également mettre à jour les itinéraires dans le manifeste de déploiement afin que le edgeHub envoie des messages au nouveau point de terminaison.

    Recherchez la section Itinéraires dans le jumeau de module $edgeHub. Mettez à jour l’itinéraire sensorTofilterModule pour remplacer input1 par inputFromSensor :

    "sensorTofiltermodule": "FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/inputFromSensor\")"

  11. Ajoutez le jumeau de module filtermodule au manifeste de déploiement. Insérez le contenu JSON suivant en bas de la section modulesContent, après le jumeau de module $edgeHub:

       "filtermodule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }

  12. Enregistrez le fichier deployment.template.json.

Générer et envoyer (push) votre solution

Vous avez mis à jour le code du module et le modèle de déploiement pour comprendre plus facilement certains concepts de déploiement clés. Maintenant, vous êtes prêt à générer votre image conteneur module, puis à l’envoyer (push) à votre registre de conteneurs.

Dans Visual Studio Code, ouvrez le fichier manifeste de déploiement deployment.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 modulesContent>edgeAgent>settings>registryCredentials dans deployment.template.json. Remplacez myacr par votre propre nom de registre, puis indiquez votre mot de passe et l’adresse du serveur de connexion. Par exemple :

"registryCredentials": {
    "myacr": {
        "username": "myacr",
        "password": "<your_acr_password>",
        "address": "myacr.azurecr.io"
    }
}

Ajoutez ou remplacez le contenu enchaîné suivant dans la valeur createOptions pour chaque système (edgeHub et edgeAgent) et module personnalisé (filtermodule et tempSensor) 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\"}]}}}"
}

Générer l’image Docker du module

Ouvrez le terminal intégré de Visual Studio Code en choisissant Terminal>Nouveau terminal.

Utilisez la commande dotnet publish afin de générer l’image conteneur pour l’architecture Linux et amd64. Basculez vers le répertoire filtermodule dans votre projet et exécutez la commande dotnet publish.

dotnet publish --os linux --arch x64 /t:PublishContainer

Actuellement, le modèle d’outil iotedgedev cible .NET 7.0. Si vous souhaitez cibler une autre version de .NET, vous pouvez modifier le fichier filtermodule.csproj et changer les valeurs TargetFramework et PackageReference. Par exemple, pour cibler .NET 8.0, votre fichier filtermodule.csproj doit ressembler à ceci :

<Project Sdk="Microsoft.NET.Sdk.Worker">
    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.Azure.Devices.Client" Version="1.42.0" />
        <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    </ItemGroup>
</Project>

Étiquetez l’image Docker avec vos informations de registre de conteneurs, version et architecture. Remplacez myacr par le nom de votre propre registre.

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.1-amd64

Pousser (push) l’image Docker du module

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 ACR (Azure Container Registry).

    docker login -u <ACR username> -p <ACR password> <ACR 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 devez 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 <ACR 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.

  3. 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. Replace myacr with your Azure Container Registry name.

az acr login --name myacr
docker push myacr.azurecr.io/filtermodule:0.0.1-amd64

Mettre à jour le modèle de déploiement

Mettez à jour le modèle de déploiement deployment.template.json avec l’emplacement de l’image du registre de conteneurs. Par exemple, si vous utilisez une Azure Container Registry myacr.azurecr.io et que votre image est filtermodule:0.0.1-amd64, mettez à jour la configuration filtermodule pour :

"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 l’Explorateur Visual Studio Code, cliquez avec le bouton droit sur le fichier deployment.template.json et sélectionnez Build and Push IoT Edge Solution (Générer et envoyer (push) la solution IoT Edge).

La commande de génération et d’envoi (push) déclenche trois opérations. Tout d’abord, elle crée un dossier dans la solution appelé config contenant les manifestes de déploiement en entier. Il est généré à partir des informations dans le modèle de déploiement et d’autres fichiers de solution. Ensuite, elle exécute docker build pour générer l’image de conteneur basée sur le fichier docker correspondant à votre architecture cible. Puis, elle exécute docker push pour envoyer (push) le dépôt d’images vers votre registre de conteneurs.

Ce processus peut prendre plusieurs minutes la première fois, mais il est plus rapide la prochaine fois que vous exécutez les commandes.

Facultatif : Mettre à jour le module et l’image

Si vous apportez des modifications au code de votre module, vous devez reconstruire et envoyer l’image de module à votre registre de conteneurs. Suivez les étapes de cette section pour mettre à jour la build et l’image conteneur. Vous pouvez ignorer cette section si vous n’avez apporté aucune modification au code de votre module.

Ouvrez le fichier deployment.amd64.json dans le dossier config créé. Le nom de fichier, reflétant l’architecture cible, est ainsi différent si vous avez choisi une autre architecture.

Notez que les deux paramètres qui avaient des espaces réservés contiennent maintenant leurs valeurs appropriées. Dans la section registryCredentials, les nom d’utilisateur et mot de passe du registre proviennent du fichier .env. Le filtermodule a le référentiel d’images complet ; l’étiquette du nom, de la version et de l’architecture provient du fichier module.json.

  1. Ouvrez le fichier module.json dans le dossier filtermodule.

  2. Changez le numéro de version de l’image de module. Par exemple, incrémentez le numéro de version de correctif en le définissant sur "version": "0.0.2" comme si vous aviez apporté un petit correctif dans le code du module.

    Conseil

    Les versions de module activent la gestion de version, ce qui vous permet de tester les modifications sur un petit ensemble d’appareils avant de déployer des mises à jour en production. Si vous n’incrémentez pas la version du module avant d’effectuer les opérations de génération et d’envoi (push), vous remplacez le dépôt dans votre registre de conteneurs.

  3. Enregistrez les modifications apportées au fichier module.json.

Générez, puis envoyez (push) l’image mise à jour avec une balise de version 0.0.2. Par exemple, pour générer, puis envoyer (push) l’image pour le registre local ou un registre de conteneurs Azure, utilisez les commandes suivantes :


# Build the container image for Linux and amd64 architecture.

dotnet publish --os linux --arch x64

# For local registry:
# Tag the image with version 0.0.2, x64 architecture, and the local registry.

docker tag filtermodule localhost:5000/filtermodule:0.0.2-amd64

# For Azure Container Registry:
# Tag the image with version 0.0.2, x64 architecture, and your container registry information. Replace **myacr** with your own registry name.

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.2-amd64

Recliquez avec le bouton droit sur le fichier deployment.template.json et resélectionnez Build and Push IoT Edge Solution (Générer et envoyer (push) la solution IoT Edge).

Rouvrez le fichier deployment.amd64.json. Notez que le système de génération ne crée pas de fichier lorsque vous exécutez à nouveau la commande générer et envoyer (push). Le même fichier est plutôt mis à jour pour refléter les modifications. L’image filtermodule pointe désormais vers la version 0.0.2 du conteneur.

Pour vérifier davantage ce qu’a fait la commande de génération et d’envoi (push), accédez au portail Azure, puis à votre registre de conteneurs.

Dans votre registre de conteneurs, sélectionnez Dépôts, puis filtermodule. Vérifiez que les deux versions de l’image envoient au registre.

Screenshot of where to view both image versions in your container registry.

Résoudre les problèmes

Si vous rencontrez des erreurs lors de la génération et de l’envoi (push) de votre image de module, elles sont souvent liées à la configuration de Docker sur votre machine de développement. Pour passer en revue votre configuration, effectuez les vérifications suivantes :

  • Avez-vous exécuté la commande docker login en utilisant les informations d’identification que vous avez copiées à partir de votre registre de conteneurs ? Ces informations d’identification sont différentes de celles que vous utilisez pour vous connecter à Azure.
  • Votre référentiel de conteneurs est-il correct ? A-t-il les noms de registre de conteneur et de module appropriés ? Ouvrez le fichier module.json dans le dossier filtermodule pour vérifier. La valeur du dépôt doit ressembler à <nom_registre>.azurecr.io/filtermodule.
  • Si vous avez utilisé un autre nom que filtermodule pour votre module, ce nom est-il cohérent dans l’ensemble de la solution ?
  • Votre machine exécute-t-elle le même type de conteneurs que celui que vous générez ? Ce tutoriel concerne les appareils Linux IoT Edge ; Visual Studio Code doit donc indiquer amd64 ou arm32v7 dans la barre latérale, et Docker Desktop doit exécuter des conteneurs Linux.

Déployer des modules sur un appareil

Vous avez vérifié que des images de conteneur générées sont stockées dans votre registre de conteneurs, il est donc temps de les déployer sur un appareil. Vérifiez que votre appareil IoT Edge est opérationnel.

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.template.json sur le hub IoT my-iot-hub pour l’appareil IoT Edge my-device, utilisez la commande suivante. Remplacez les valeurs de hub-name, device-id et login IoT Hub chaîne de connexion par la vôtre.

az iot edge set-modules --hub-name my-iot-hub --device-id my-device --content ./deployment.template.json --login "HostName=my-iot-hub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"

Conseil

Vous pouvez trouver votre chaîne de connexion IoT Hub, y compris la clé d’accès partagé dans le Portail Azure. Accédez à votre IoT Hub >Paramètres de sécurité>Stratégies d’accès partagé>iothubowner.

  1. Dans l’Explorateur Visual Studio Code, sous la section Azure IoT Hub, développez Appareils pour voir votre liste d’appareils IoT.

  2. Cliquez avec le bouton droit sur l’appareil IoT Edge sur lequel vous souhaitez effectuer le déploiement, puis sélectionnez Create Deployment for Single Device (Créer un déploiement pour un seul appareil).

  3. Dans l’Explorateur de fichiers, accédez au dossier config, puis sélectionnez le fichier deployment.amd64.json.

    N’utilisez pas le fichier deployment.template.json qui ne contient pas les informations d’identification du registre de conteneurs ou les valeurs d’image de module. Si votre cible est un appareil Linux ARM32, le nom du manifeste de déploiement est deployment.arm32v7.json.

  4. Développez la section Modules sous votre appareil pour voir la liste des modules déployés et en cours d’exécution. Sélectionnez le bouton actualiser. Les nouveaux modules tempSensor et filtermodule doivent s’exécuter sur votre appareil.

    Le démarrage des modules peut prendre quelques minutes. Le runtime IoT Edge doit recevoir son nouveau manifeste de déploiement, extraire les images de module à partir du runtime du conteneur, puis démarrer chaque nouveau module.

Afficher les messages provenant de l’appareil

Le code échantillon de module reçoit des messages via sa file d’attente d’entrée et les transmet à sa file d’attente de sortie. Le manifeste de déploiement déclarant des routes qui ont envoyé des messages de tempSensor vers filtermodule, puis ont ensuite transféré des messages depuis filtermodule vers IoT Hub. Les extensions Azure IoT Edge et Azure IoT Hub vous permettent de voir les messages à mesure qu’ils arrivent au hub IoT en provenance de vos différents appareils.

  1. Dans l’explorateur Visual Studio Code, cliquez avec le bouton droit sur l’appareil IoT Edge que vous souhaitez superviser, puis sélectionnez Démarrer la supervision du point de terminaison d’événements intégré.

  2. Regardez la fenêtre de sortie dans Visual Studio Code pour voir les messages arrivant à votre hub IoT.

    Screenshot showing where to view incoming device to cloud messages.

Afficher les modifications sur l’appareil

Si vous souhaitez voir ce qui se passe sur votre appareil lui-même, utilisez les commandes de cette section pour inspecter le runtime IoT Edge et les modules en cours d’exécution sur votre appareil.

Les commandes de cette section concernent votre appareil IoT Edge, pas votre machine de développement. Si vous utilisez une machine virtuelle pour votre appareil IoT Edge, connectez-vous-y maintenant. Dans Azure, accédez à la page de vue d’ensemble de la machine virtuelle et sélectionnez Se connecter pour accéder à la connexion Secure Shell.

  • Affichez tous les modules déployés sur votre appareil et vérifiez leur état :

    iotedge list

    Vous devez voir quatre modules : les deux modules du runtime IoT Edge, tempSensor et filtermodule. Vous devriez voir les quatre indiqués comme étant en cours d’exécution.

  • Examinez les journaux d’activité d’un module spécifique :

    iotedge logs <module name>

    Les modules IoT Edge respectent la casse.

    Les journaux d’activité de tempSensor et filtermodule doivent afficher les messages qu’ils traitent. Le module edgeAgent étant responsable du démarrage des autres modules, ses journaux d’activité contiennent des informations concernant l’implémentation du manifeste de déploiement. Si vous constatez qu'un module n'est pas répertorié ou en cours d'exécution, les journaux d'activité d'edgeAgent contiennent probablement les erreurs. Le module edgeHub est responsable des communications entre les modules et le hub IoT. Si les modules sont opérationnels, mais que les messages n’atteignent pas votre hub IoT, les journaux d’activité edgeHub ont probablement les erreurs.

Nettoyer les ressources

Si vous envisagez de passer à l’article recommandé suivant, vous pouvez conserver les ressources et configurations que vous avez créées afin de les réutiliser. Vous pouvez également continuer à utiliser le même appareil IoT Edge comme appareil de test.

Sinon, vous pouvez supprimer les ressources Azure et les configurations locales que vous avez utilisées dans cet article pour éviter les frais.

Supprimer les ressources Azure

La suppression des ressources et des groupes de ressources Azure est irréversible. Veillez à ne pas supprimer accidentellement les mauvaises ressources ou le mauvais groupe de ressources. Si vous avez créé le hub IoT à l’intérieur d’un groupe de ressources existant qui contient des ressources que vous souhaitez conserver, supprimez uniquement la ressource du hub IoT, plutôt que le groupe de ressources.

Pour supprimer les ressources :

  1. Connectez-vous au Portail Azure, puis sélectionnez Groupes de ressources.

  2. Sélectionnez le nom du groupe de ressources contenant vos ressources de test de IoT Edge.

  3. Passez en revue la liste des ressources contenues dans votre groupe de ressources. Si vous souhaitez toutes les supprimer, vous pouvez sélectionner Supprimer le groupe de ressources. Si vous souhaitez en supprimer seulement quelques-unes, vous pouvez cliquer sur chaque ressource pour les supprimer individuellement.

Étapes suivantes

Dans ce tutoriel, vous configurez Visual Studio Code sur votre ordinateur de développement, puis déployez votre premier module IoT Edge qui contient du code pour filtrer les données brutes générées par votre appareil IoT Edge.

Vous pouvez passer aux tutoriels suivants afin de découvrir comment Azure IoT Edge peut vous aider à déployer des services cloud Azure pour traiter et analyser des données en périphérie.

Déboguer les modules Azure IoT EdgeFunctionsStream AnalyticsCustom Vision Service