Prise en main de la gestion d’appareils (.NET)

Article
10/01/2024

Les applications back-end peuvent utiliser des primitives Azure IoT Hub, par exemple les jumeaux d’appareil et les méthodes directes, pour effectuer le démarrage et le monitoring à distance des actions de gestion des appareils sur les appareils. Cet article illustre la manière dont une application back-end et une application pour périphérique fonctionnent conjointement afin de lancer et d’analyser le redémarrage à distance d’un appareil à l’aide de IoT Hub.

Notes

Les fonctionnalités décrites dans cet article sont uniquement disponibles au niveau Standard d’IoT Hub. Pour plus d’informations sur les niveaux de base et standard/gratuit d’IoT Hub, consultez Choisir le niveau IoT Hub correspondant à votre solution.

Utilisez une méthode directe pour lancer des actions de gestion d’appareils (redémarrage, réinitialisation des paramètres d’usine et mise à jour du microprogramme) à partir d’une application principale dans le cloud. L’appareil est chargé de :

Gérer la requête de méthode envoyée à partir d’IoT Hub.
Démarrer l’action correspondante spécifique à l’appareil sur l’appareil.
Fournir à IoT Hub des mises à jour de l’état via des propriétés signalées.

Vous pouvez utiliser une application principale dans le cloud pour exécuter des requêtes sur la représentation d’appareil afin d’indiquer la progression des actions de gestion de votre appareil.

Cet article explique comment créer :

SimulateManagedDevice : une application d’appareil simulée avec une méthode directe qui redémarre l’appareil et signale la dernière heure de redémarrage. Les méthodes directes sont appelées à partir du cloud.
TriggerReboot : une application console .NET qui appelle une méthode directe sur l’application d’appareil simulé via votre IoT Hub. Il affiche la réponse et les propriétés signalées mises à jour.

Prérequis

Visual Studio.
Un hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans Créer un hub IoT.
Un appareil inscrit dans votre hub IoT. Si vous n’avez pas d’appareil dans votre hub IoT, suivez les étapes décrites dans Inscrire un appareil.
Vérifiez que le port 8883 est ouvert dans votre pare-feu. L’exemple d’appareil décrit dans cet article utilise le protocole MQTT, qui communique via le port 8883. Ce port peut être bloqué dans certains environnements réseau professionnels et scolaires. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).

Créer une application d’appareil avec une méthode directe

Dans cette section, vous allez :

Créer une application console .NET qui répond à une méthode directe appelée par le cloud.
Déclencher un redémarrage d’appareil simulé.
Utiliser les propriétés signalées pour activer les requêtes sur le jumeau d’appareil afin d’identifier les appareils et l’heure de leur dernier redémarrage.

Important

Cet article comprend les étapes à suivre pour connecter un appareil en utilisant une signature d’accès partagé, également appelée « authentification par clé symétrique ». Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification d’un appareil en utilisant des certificats X.509 est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité des connexions.

Pour créer l’application d’appareil simulé, procédez comme suit :

Ouvrez Visual Studio et sélectionnez Créer un nouveau projet, puis trouvez et sélectionnez le modèle de projet Console App (.NET Framework), puis sélectionnez Suivant.
Dans Configurer votre nouveau projet, nommez le projet SimulateManagedDevice, puis sélectionnez Suivant.
Conservez la version de l’infrastructure .NET Framework par défaut, puis sélectionnez Créer.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nouveau projet SimulateManagedDevice, puis sélectionnez Gérer les packages NuGet.
Sélectionnez Parcourir, puis recherchez et sélectionnez Microsoft.Azure.Devices.Client. Sélectionnez Installer.

Cette étape télécharge, installe et ajoute une référence au package NuGet Azure IoT device SDK et à ses dépendances.

Ajoutez les instructions using suivantes en haut du fichier Program.cs :

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Ajoutez les champs suivants à la classe Program . Remplacez la valeur d’espace réservé {device connection string} par la chaîne de connexion de l’appareil affichée lorsque vous avez inscrit un appareil dans IoT Hub :
```
static string DeviceConnectionString = "{device connection string}";
static DeviceClient Client = null;
```

Ajoutez le code suivant pour implémenter la méthode directe sur l’appareil :

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
    // In a production device, you would trigger a reboot 
    //   scheduled to start after this method returns.
    // For this sample, we simulate the reboot by writing to the console
    //   and updating the reported properties.
    try
    {
        Console.WriteLine("Rebooting!");

        // Update device twin with reboot time. 
        TwinCollection reportedProperties, reboot, lastReboot;
        lastReboot = new TwinCollection();
        reboot = new TwinCollection();
        reportedProperties = new TwinCollection();
        lastReboot["lastReboot"] = DateTime.Now;
        reboot["reboot"] = lastReboot;
        reportedProperties["iothubDM"] = reboot;
        Client.UpdateReportedPropertiesAsync(reportedProperties).Wait();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }

    string result = @"{""result"":""Reboot started.""}";
    return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Enfin, ajoutez le code suivant à la méthode Main pour ouvrir la connexion à votre IoT Hub et initialiser l’écouteur de la méthode :

try
{
    Console.WriteLine("Connecting to hub");
    Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
      TransportType.Mqtt);

    // setup callback for "reboot" method
    Client.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
    Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
    Console.ReadLine();

    Console.WriteLine("Exiting...");

    // as a good practice, remove the "reboot" handler
    Client.SetMethodHandlerAsync("reboot", null, null).Wait();
    Client.CloseAsync().Wait();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur votre solution, puis sélectionnez Définir les projets de démarrage.
Sous Propriétés communes>Projet de démarrage, sélectionnez Projet de démarrage unique, puis sélectionnez le projet SimulateManagedDevice. Sélectionnez OK pour enregistrer vos modifications.
Sélectionnez Générer>Générer la solution.

Notes

Pour simplifier les choses, cet article n’implémente aucune stratégie de nouvelles tentatives. Dans le code de production, vous devez implémenter des stratégies de nouvelle tentative (par exemple, un backoff exponentiel) comme indiqué dans Gestion des erreurs temporaires.

Obtenir la chaîne de connexion du hub IoT

Dans cet article, vous créez un service principal qui invoque une méthode directe sur un appareil. Pour invoquer une méthode directe sur un appareil via l’IoT Hub, votre service a besoin de l'autorisation de connexion de service. Par défaut, chaque IoT Hub est créé avec une stratégie d’accès partagé nommée service qui accorde cette autorisation.

Pour obtenir la chaîne de connexion IoT Hub pour la stratégie service, procédez comme suit :

Dans le portail Azure, sélectionnez Groupes de ressources. Sélectionnez le groupe de ressources dans lequel se trouve votre hub, puis sélectionnez votre hub dans la liste des ressources.
Dans le volet de gauche de votre IoT Hub, sélectionnez Stratégies d’accès partagé.
Dans la liste des stratégies, sélectionnez la stratégie service.
Copiez la Chaîne de connexion principale, puis enregistrez la valeur.

Pour plus d’informations sur les autorisations et les stratégies d’accès partagé IoT Hub, consultez Contrôle d’accès et autorisations.

Créer une application de service pour déclencher un redémarrage

Dans cette section, vous créez une application console .NET (à l’aide de C#) qui lance un redémarrage à distance sur un appareil avec une méthode directe. L’application utilise des requêtes du jumeau d’appareil pour déterminer l’heure du dernier redémarrage de cet appareil.

Important

Cet article comprend les étapes à suivre pour se connecter à un service à l’aide d’une signature d’accès partagé. Cette méthode d’authentification est pratique pour les tests et les évaluations, mais l’authentification à un service avec Microsoft Entra ID ou des identités managées est une approche plus sécurisée. Pour plus d’informations, consultez Meilleures pratiques de sécurité > Sécurité du cloud.

Ouvrez Visual Studio et sélectionnez Créer un projet.
Sous Créer un projet, recherchez et sélectionnez le modèle de projet Application console (.NET Framework) , puis sélectionnez suivant.
Dans Configurer votre nouveau projet, nommez le projet TriggerReboot et sélectionnez Suivant.
Acceptez la version par défaut de .NET Framework, puis sélectionnez Créer pour créer le projet.
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet TriggerReboot, puis sélectionnez Gérer les packages NuGet.
Sélectionnez Parcourir, puis recherchez et sélectionnez Microsoft.Azure.Devices. Sélectionnez Installer pour installer le package Microsoft.Azure.Devices.

Cette étape lance le téléchargement et l’installation et ajoute une référence au package Azure IoT Service SDK NuGet et ses dépendances.

Ajoutez les instructions using suivantes en haut du fichier Program.cs :

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

Ajoutez les champs suivants à la classe Program . Remplacez la valeur de l’espace réservé {iot hub connection string} par la chaîne de connexion IoT Hub que vous avez copiée dans Obtenir la chaîne de connexion du hub IoT.
```
static RegistryManager registryManager;
static string connString = "{iot hub connection string}";
static ServiceClient client;
static string targetDevice = "myDeviceId";
```

Ajoutez la méthode suivante à la classe Program. Ce code obtient la représentation d’appareil pour le redémarrage de l’appareil et renvoie les propriétés signalées.

public static async Task QueryTwinRebootReported()
{
    Twin twin = await registryManager.GetTwinAsync(targetDevice);
    Console.WriteLine(twin.Properties.Reported.ToJson());
}

Ajoutez la méthode suivante à la classe Program. Ce code lance un redémarrage à distance sur l’appareil à l’aide d’une méthode directe.

public static async Task StartReboot()
{
    client = ServiceClient.CreateFromConnectionString(connString);
    CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
    method.ResponseTimeout = TimeSpan.FromSeconds(30);

    CloudToDeviceMethodResult result = await 
      client.InvokeDeviceMethodAsync(targetDevice, method);

    Console.WriteLine("Invoked firmware update on device.");
}

Enfin, ajoutez les lignes suivantes à la méthode Main :

registryManager = RegistryManager.CreateFromConnectionString(connString);
StartReboot().Wait();
QueryTwinRebootReported().Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

Sélectionnez Générer>Générer la solution.

Notes

Cet article n'effectue qu’une seule requête pour les propriétés indiquées de l’appareil. Dans le code de production, nous recommandons d’effectuer une interrogation pour détecter les modifications apportées aux propriétés indiquées.

Exécuter les applications

Vous êtes maintenant prêt à exécuter les applications.

Pour exécuter l’application d’appareil .NET SimulateManagedDevice, dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet SimulateManagedDevice, sélectionnez Déboguer, puis sélectionnez Démarrer une nouvelle instance. L’application doit commencer à écouter les appels de méthode provenant de votre hub IoT.
Une fois que l’appareil est connecté et en attente d’appels de méthode, cliquez avec le bouton droit sur le projet TriggerReboot, sélectionnez Déboguer, puis sélectionnez Démarrer une nouvelle instance.

Vous devriez voir Redémarrage en cours sur la console SimulatedManagedDevice et les propriétés signalées de l’appareil, dont l’heure du dernier redémarrage, sur la console TriggerReboot.

Personnaliser et étendre les actions de gestion d’appareils

Vos solutions IoT peuvent étendre l’ensemble défini de modèles de gestion d’appareils ou activer des modèles personnalisés en utilisant les primitives de la méthode cloud-à-appareil et du jumeau d’appareil. La réinitialisation des paramètres d’usine, la mise à jour du microprogramme, la mise à jour logicielle, la gestion de l’alimentation, la gestion du réseau et de la connectivité, et le chiffrement des données sont d’autres exemples d’actions de gestion des appareils.

Fenêtres de maintenance d’appareil

En règle générale, vous configurez des appareils pour effectuer des actions à un moment qui minimise les interruptions et les temps d’arrêt. Les fenêtres de maintenance d’appareil constituent un modèle couramment utilisé pour définir l’heure à laquelle un appareil doit mettre à jour sa configuration. Vos solutions principales peuvent utiliser les propriétés souhaitées de la représentation d’appareil pour définir et activer une stratégie sur votre appareil qui permet d’obtenir une fenêtre de maintenance. Lorsqu’un appareil reçoit la stratégie de fenêtre de maintenance, il peut utiliser la propriété signalée de la représentation d’appareil pour indiquer l’état de la stratégie. L’application principale peut ensuite utiliser des requêtes de représentation d’appareil pour certifier la conformité des appareils et de chaque stratégie.

Étapes suivantes

Dans cet article, vous avez utilisé une méthode directe pour déclencher un redémarrage à distance sur un appareil. Vous avez utilisé les propriétés signalées pour indiquer le moment du dernier redémarrage de l’appareil et vous avez interrogé le jumeau d’appareil pour découvrir l’heure du dernier redémarrage de l’appareil à partir du cloud.

Pour approfondir vos connaissances sur IoT Hub et les modèles de gestion des appareils, comme la mise à jour de bout en bout basée sur une image, consultez Mise à jour des appareils pour Azure IoT Hub à l’aide de l’image de référence Raspberry Pi 3 B+.

Pour savoir comment étendre votre solution IoT et planifier des appels de méthode sur plusieurs appareils, consultez Planifier et diffuser des travaux.

Partager via

Prise en main de la gestion d’appareils (.NET)

Prérequis

Créer une application d’appareil avec une méthode directe

Obtenir la chaîne de connexion du hub IoT

Créer une application de service pour déclencher un redémarrage

Exécuter les applications

Personnaliser et étendre les actions de gestion d’appareils

Fenêtres de maintenance d’appareil

Étapes suivantes

Commentaires

Ressources supplémentaires