Condividi tramite

Esercitazione: Sviluppare moduli IoT Edge con Visual Studio Code

  • Articolo

Si applica a: Segno di spunta IoT Edge 1.5 IoT Edge 1.5 Segno di spunta IoT Edge 1.4 IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS sono versioni supportate. IoT Edge 1.4 LTS raggiungerà il fine vita il 12 novembre 2024. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

Questa esercitazione illustra come sviluppare e distribuire codice personalizzato in un dispositivo IoT Edge. È possibile usare i moduli di Azure IoT Edge per distribuire codice che implementa la logica di business direttamente nei dispositivi di IoT Edge. Nella guida introduttiva Distribuire il codice in un dispositivo Linux è stato creato un dispositivo IoT Edge ed è stato distribuito un modulo da Azure Marketplace.

Questo articolo include i passaggi per due strumenti di sviluppo di IoT Edge.

  • Riga di comando dello strumento di sviluppo di Azure IoT Edge. Questo strumento è preferibile per lo sviluppo.
  • Estensione Azure IoT Edge Tools per Visual Studio Code. L'estensione è in modalità manutenzione.

Usare il pulsante del selettore dello strumento all'inizio di questo articolo per selezionare la versione dello strumento.

In questa esercitazione apprenderai a:

  • Configurare il computer di sviluppo.
  • Usare gli strumenti di IoT Edge per creare un nuovo progetto.
  • Compilare il progetto come contenitore Docker e archiviarlo in un registro contenitori di Azure.
  • Distribuire il codice in un dispositivo IoT Edge.

Il modulo di IoT Edge creato in questa esercitazione filtra i dati relativi alla temperatura generati dal dispositivo. Invia messaggi upstream solo quando la temperatura è superiore a una soglia specificata. Questo tipo di analisi alla rete perimetrale è utile per ridurre la quantità di dati comunicati e archiviati nel cloud.

Prerequisiti

Un computer di sviluppo:

  • Usare il proprio computer o una macchina virtuale.
  • Il computer di sviluppo deve supportare la virtualizzazione annidata per l'esecuzione di un motore contenitore.
  • Per lo sviluppo di moduli IoT Edge per dispositivi Linux, è possibile usare la maggior parte dei sistemi operativi in grado di eseguire un motore per i contenitori. Questa esercitazione usa un computer Windows, ma vengono evidenziate le differenze note in macOS o Linux.
  • Installare Visual Studio Code
  • Installare l'interfaccia della riga di comando di Azure.

Un dispositivo Azure IoT Edge:

Risorse cloud:

  • Un hub IoT di livello Gratuito o Standard in Azure.

Se non si ha una sottoscrizione di Azure, creare un account Azure gratuito prima di iniziare.

Suggerimento

Per indicazioni sul debug interattivo in Visual Studio Code o Visual Studio 2022:

Questa esercitazione illustra i passaggi di sviluppo per Visual Studio Code.

Concetti chiave

Questa esercitazione illustra in modo dettagliato le fasi di sviluppo di un modulo IoT Edge. Un modulo IoT Edge è un contenitore con codice eseguibile. È possibile distribuire uno o più moduli in un dispositivo IoT Edge. I moduli eseguono attività specifiche, ad esempio l'inserimento di dati provenienti dai sensori, l'esecuzione di operazioni di analisi e pulizia dei dati oppure l'invio di messaggi a un hub IoT. Per altre informazioni, vedere Informazioni sui moduli Azure IoT Edge.

Quando si sviluppano moduli IoT Edge, è importante comprendere la differenza tra il computer di sviluppo e il dispositivo IoT Edge di destinazione in cui il modulo viene distribuito. Il contenitore creato per inserire il codice dei moduli deve corrispondere al sistema operativo del dispositivo di destinazione. Ad esempio, lo scenario più comune è quello in cui si sviluppa in un computer Windows un modulo destinato a un dispositivo Linux che esegue IoT Edge. In tal caso, il sistema operativo del contenitore è Linux. Mentre si procede con questa esercitazione, tenere presente la differenza tra sistema operativo del computer di sviluppo e sistema operativo del contenitore.

Suggerimento

Se si usa IoT Edge per Linux in Windows, il dispositivo di destinazione nello scenario è la macchina virtuale Linux, non l'host Windows.

Questa esercitazione è destinata ai dispositivi che eseguono IoT Edge con contenitori Linux. È possibile usare il sistema operativo preferito, purché il computer di sviluppo esegua i contenitori Linux. È consigliabile usare Visual Studio Code per sviluppare con contenitori Linux, in modo da usare questa esercitazione. È possibile usare anche Visual Studio, ma esistono alcune differenze in termini di supporto tra i due strumenti.

La tabella seguente elenca gli scenari di sviluppo supportati per i contenitori Linux in Visual Studio Code e Visual Studio.

Visual Studio Code Visual Studio 2019/2022
Architettura dei dispositivi Linux Linux AMD64
Linux ARM32v7
Linux ARM64		 Linux AMD64
Linux ARM32
Linux ARM64
Servizi di Azure Funzioni di Azure
Analisi di flusso di Azure
Azure Machine Learning
Lingue C
C#
Java
Node.js
Python		 C
C#
Ulteriori informazioni Azure IoT Edge per Visual Studio Code Azure IoT Edge Tools per Visual Studio 2019
Azure IoT Edge Tools per Visual Studio 2022

Installare il motore per i contenitori

I moduli IoT Edge vengono inseriti in un pacchetto come contenitori, quindi è necessario un sistema di gestione contenitori compatibile con Docker nel computer di sviluppo per compilarli e gestirli. È consigliabile usare Docker Desktop per lo sviluppo grazie al supporto e alla popolarità delle relative funzionalità. Con Docker Desktop in Windows è possibile passare tra contenitori Linux e contenitori Windows, per sviluppare moduli per i diversi tipi di dispositivi IoT Edge.

Usare la documentazione di Docker per eseguire l'installazione nel computer di sviluppo:

  • Installare Docker Desktop per Windows

    • Quando si installa Docker Desktop per Windows, viene chiesto se si vuole usare i contenitori Linux o Windows. È possibile modificare questa decisione in qualsiasi momento. Per questa esercitazione si usano i contenitori Linux perché i moduli sono destinati a dispositivi Linux. Per altre informazioni, vedere Switch between Windows and Linux containers (Passare tra contenitori Windows e Linux).

  • Install Docker Desktop for Mac (Installare Docker Desktop per Mac)

  • Leggere l'articolo About Docker CE (Informazioni su Docker CE) per informazioni sull'installazione in diverse piattaforme Linux.

    • Per il sottosistema Windows per Linux (WSL), installare Docker Desktop per Windows.

Configurare gli strumenti

Installare lo strumento di sviluppo Azure IoT Edge basato su Python per creare la soluzione IoT Edge. Sono disponibili due opzioni:

Importante

L'estensione Azure IoT Edge Tools per Visual Studio Code è in modalità manutenzione. Lo strumento di sviluppo preferito è la riga di comando (CLI) Azure IoT Edge Dev Tool.

Usare le estensioni IoT per Visual Studio Code per sviluppare moduli IoT Edge. Queste estensioni offrono modelli di progetto, automatizzano la creazione del manifesto della distribuzione e consentono di monitorare e gestire i dispositivi IoT Edge. In questa sezione si installano Visual Studio Code e l'estensione IoT, quindi si configura l'account di Azure per gestire le risorse dell'hub IoT da Visual Studio Code.

  1. Installare l’estensione Azure IoT Edge.

  2. Installare l'estensione hub IoT di Azure.

  3. Dopo aver installato le estensioni, aprire il riquadro comandi selezionando Visualizza>Riquadro comandi.

  4. Nel riquadro comandi cercare e selezionare hub IoT di Azure: selezionare Hub IoT. Seguire le istruzioni per selezionare la sottoscrizione di Azure e l'hub IoT.

  5. Aprire la sezione Explorer di Visual Studio Code selezionando l'icona sulla barra delle attività a sinistra oppure selezionando Visualizza>Explorer.

  6. Nella parte inferiore della sezione di esplorazione espandere il menu compresso Azure IoT Hub Devices (Dispositivi hub IoT di Azure). Dovrebbero venire visualizzati i dispositivi e i dispositivi IoT Edge associati all'hub IoT selezionato tramite il riquadro comandi.

Installare strumenti specifici del linguaggio

Installare strumenti specifici per il linguaggio in cui si sta sviluppando:

Creare un registro contenitori

In questa esercitazione si usano le estensioni Azure IoT Edge e Hub IoT di Azure per creare un modulo e creare un'immagine del contenitore dai file. Eseguire quindi il push dell'immagine in un registro che archivia e gestisce le immagini. Distribuire infine l'immagine dal registro nel dispositivo IoT Edge.

Importante

L'estensione Azure IoT Edge per Visual Studio Code è in modalità di manutenzione.

È possibile usare qualsiasi registro compatibile con Docker per inserire le immagini dei contenitori. Due servizi di registro Docker molto diffusi sono Registro Azure Container e Hub Docker. Questa esercitazione usa Registro Azure Container.

Se non è ancora disponibile alcun registro contenitori, seguire questa procedura per crearne uno nuovo in Azure:

  1. Nel portale di Azure selezionare Crea una risorsa>Contenitori>Registro Container.

  2. Specificare i valori necessari seguenti per creare il registro contenitori:

    Campo Valore
    Subscription Selezionare una sottoscrizione nell'elenco a discesa.
    Gruppo di risorse Usare lo stesso gruppo di risorse per tutte le risorse di test create durante le esercitazioni e le guide introduttive di IoT Edge. Ad esempio, IoTEdgeResources.
    Nome registro Specificare un nome univoco.
    Ufficio Scegliere una località vicina.
    SKU Selezionare Basic.

  3. Selezionare Rivedi + crea, quindi Crea.

  4. Selezionare il nuovo registro contenitori nella sezione Risorse della home page del portale di Azure per aprirlo.

  5. Nel riquadro sinistro del registro contenitori selezionare Chiavi di accesso dal menu disponibile in Impostazioni.

    Screenshot del percorso del menu Chiavi di accesso.

  6. Abilitare l'utente amministratore con l'interruttore e visualizzare il nome utente e la password per il registro contenitori.

  7. Copiare i valori di Server di accesso, Nome utente e Password e conservarli in una posizione pratica. Questi valori verranno usati durante l'esercitazione per fornire l'accesso al registro contenitori.

Creare un nuovo progetto di modulo

L'estensione Azure IoT Edge offre modelli di progetto per tutti i linguaggi dei moduli IoT Edge supportati in Visual Studio Code. Questi modelli includono il codice e tutti i file necessari per distribuire un modulo funzionante per testare IoT Edge oppure offrono un punto di partenza per personalizzare il modello con la propria logica di business.

Creare un modello di progetto

Lo strumento di sviluppo IoT Edge semplifica lo sviluppo di Azure IoT Edge ai comandi basati sulle variabili di ambiente. Viene avviato lo sviluppo di IoT Edge con lo scaffolding del contenitore di sviluppo IoT Edge e dello scaffolding della soluzione IoT Edge con un modulo predefinito e tutti i file di configurazione necessari.

  1. Creare una directory per la soluzione con il percorso desiderato. Passare alla directory iotedgesolution.

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

  2. Usare il comando init della soluzione iotedgedev per creare una soluzione e configurare l'hub IoT di Azure nel linguaggio di sviluppo preferito.

    iotedgedev solution init --template csharp

Lo script init della soluzione iotedgedev richiede di completare diversi passaggi, tra cui:

  • Autenticazione con Azure
  • Scegliere una sottoscrizione Azure
  • Scegliere o creare un gruppo di risorse
  • Scegliere o creare un hub IoT di Azure
  • Scegliere o creare un dispositivo Azure IoT Edge

Usare Visual Studio Code e l'estensione Azure IoT Edge. Per iniziare, si crea una soluzione e si genera quindi il primo modulo all'interno della soluzione. Ogni soluzione può contenere più moduli.

  1. Selezionare Visualizza>Riquadro comandi.
  2. Nel riquadro comandi immettere ed eseguire il comando Azure IoT Edge: New IoT Edge solution (Azure IoT Edge: Nuova soluzione IoT Edge).
  3. Passare alla cartella in cui si vuole creare la nuova soluzione e poi selezionare Seleziona cartella.
  4. Immettere un nome per la soluzione.
  5. Selezionare un modello di modulo per fare in modo che il linguaggio di sviluppo preferito sia il primo modulo nella soluzione.
  6. Immettere un nome per il modulo. Scegliere un nome univoco all'interno del registro contenitori.
  7. Specificare il nome del repository di immagini del modulo. Visual Studio Code popola automaticamente il nome del modulo con il valore localhost:5000/<nome del modulo>. Sostituire tale valore con le proprie informazioni di registro. Usare localhost se si usa un registro Docker locale per i test. Se si usa Registro Azure Container, usare il server di accesso indicato nelle impostazioni del registro. Il server di accesso ha un nome simile a <nome registro>.azurecr.io. Sostituire la parte della stringa localhost:5000, in modo che il risultato finale sia simile a <nome registro>.azurecr.io/<nome del modulo>.

Visual Studio Code usa le informazioni specificate per creare una soluzione IoT Edge e quindi la carica in una nuova finestra.

Dopo la creazione della soluzione, questi file principali si trovano nella soluzione:

  • .Una cartella vscode contiene il file di configurazione launch.json.

  • Una cartella moduli contenente le sottocartelle di ogni modulo. All'interno della sottocartella per ogni modulo, il file module.json controlla come vengono compilati e distribuiti i moduli.

  • Un file con estensione env in cui sono elencate le variabili di ambiente. La variabile di ambiente per il registro contenitori è localhost:5000 per impostazione predefinita.

  • Due file di distribuzione dei moduli denominati deployment.template.json e deployment.debug.template.json elencare i moduli da distribuire nel dispositivo. Per impostazione predefinita, l'elenco include i moduli di sistema IoT Edge (edgeAgent e edgeHub) e i moduli di esempio, ad esempio:

    Nota

    I moduli esatti installati possono dipendere dalla lingua scelta.

Impostare la versione del runtime di IoT Edge

La versione più recente del modulo di sistema IoT Edge stabile è la 1.5. Impostare i moduli di sistema sulla versione 1.5.

  1. In Visual Studio Code aprire il file manifesto della distribuzione deployment.template.json. Il manifesto di distribuzione è un documento JSON che descrive i moduli da configurare nel dispositivo IoT Edge di destinazione.

  2. Modificare la versione di runtime per le immagini del modulo di runtime di sistema edgeAgent e edgeHub. Ad esempio, se si vuole usare il runtime di IoT Edge versione 1.5, modificare le righe seguenti nel file manifesto della distribuzione:

    "systemModules": {
    "edgeAgent": {

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

    "edgeHub": {

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

Fornire le credenziali del registro all'agente IoT Edge

Il file dell'ambiente archivia le credenziali per il registro contenitori e le condivide con il runtime IoT Edge. Il runtime necessita di queste credenziali per eseguire il pull delle immagini dei contenitori nel dispositivo IoT Edge.

L'estensione IoT Edge cerca di eseguire il pull delle credenziali del Registro Container da Azure, per inserirle nel file di ambiente.

Nota

Il file dell'ambiente viene creato solo se si specifica un repository di immagini per il modulo. Se sono state accettate le impostazioni predefinite di localhost per testare ed eseguire il debug in locale, non è necessario dichiarare le variabili di ambiente.

Verificare se le credenziali esistono. In caso contrario, aggiungerle:

  1. Se Registro Azure Container è il registro, impostare un nome utente e una password per Registro Azure Container. Ottenere questi valori dal menu Impostazioni del registro contenitori>Chiavi di accesso nel portale di Azure.

  2. Aprire il file con estensione env nella soluzione del modulo.

  3. Aggiungere i valori di username e password copiati dal Registro Azure Container. Ad esempio:

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

  4. Salvare le modifiche al file .env.

Nota

Questa esercitazione usa le credenziali di accesso dell'amministratore per Registro Azure Container che sono utili per scenari di sviluppo e test. Quando si è pronti per gli scenari di produzione, è consigliabile usare un'opzione di autenticazione con privilegi minimi, ad esempio entità servizio o token con ambito repository. Per altre informazioni, vedere Gestire l'accesso al registro contenitori.

Architettura di destinazione

È necessario selezionare l'architettura di destinazione per ogni soluzione, perché ciò influisce sul modo in cui il contenitore viene compilato ed eseguito. L'impostazione predefinita è Linux AMD64. Per questa esercitazione si usa una macchina virtuale Ubuntu come dispositivo IoT Edge, e si manterrà il valore predefinito amd64.

Se è necessario modificare l'architettura di destinazione per la soluzione, seguire questa procedura.

  1. Aprire il riquadro comandi e cercare Azure IoT Edge: Impostare la piattaforma di destinazione predefinita per la soluzione Edgeoppure selezionare l'icona di scelta rapida nella barra laterale nella parte inferiore della finestra.

  2. Nel riquadro comandi selezionare l'architettura di destinazione nell'elenco di opzioni.

L'architettura di destinazione viene impostata quando si crea l'immagine del contenitore in un passaggio successivo.

Aggiornare il modulo con il codice personalizzato

In ogni modello è incluso il codice di esempio, che accetta i dati del sensore simulato dal modulo SimulatedTemperatureSensor e li indirizza all'hub IoT. Questo modulo di esempio riceve i messaggi e quindi li invia. La funzionalità di pipeline illustra un concetto importante in IoT Edge, ovvero come i moduli comunicano tra loro.

Per ogni modulo nel codice possono essere dichiarate più code di input e output. L'hub di IoT Edge in esecuzione nel dispositivo instrada i messaggi dall'output di un modulo all'input di uno o più moduli. Il codice specifico per la dichiarazione di input e output varia a seconda dei linguaggi, ma il concetto è lo stesso per tutti i moduli. Per altre informazioni sul routing tra moduli, vedere Dichiarare le route.

L'esempio di codice C# disponibile con il modello di progetto usa la classe ModuleClient da IoT Hub SDK per .NET.

  1. Nello strumento di esplorazione di Visual Studio Code aprire i moduli>filtermodule>ModuleBackgroundService.cs.

  2. Prima dello spazio dei nomi filtermodule, aggiungere tre istruzioni using per i tipi usati in un secondo momento:

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

  3. Aggiungere la variabile temperatureThreshold alla classe ModuleBackgroundService. Questa variabile imposta il valore che la temperatura misurata deve superare per inviare i dati all'hub IoT.

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

  4. Aggiungere le classi MessageBody, Machine e Ambient. Queste classi definiscono lo schema previsto per il corpo dei messaggi in arrivo.

    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. Trovare la funzione ExecuteAsync. Questa funzione crea e configura l'oggetto ModuleClient, che consente al modulo di connettersi al runtime locale di Azure IoT Edge per inviare e ricevere messaggi. Dopo la creazione di ModuleClient, il codice legge il valore temperatureThreshold dalle proprietà desiderate del modulo gemello. Il codice registra un callback per la ricezione di messaggi da un hub IoT Edge tramite un endpoint denominato input1.

    Sostituire la chiamata al metodo ProcessMessageAsync con un nuovo metodo che aggiorna il nome dell'endpoint e il metodo chiamato all'arrivo dell'input. Aggiungere inoltre un metodo SetDesiredPropertyUpdateCallbackAsync per gli aggiornamenti alle proprietà desiderate. Per apportare questa modifica, sostituire l'ultima riga del metodo ExecuteAsync con il codice seguente:

    // 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. Aggiungere il metodo onDesiredPropertiesUpdate alla classe ModuleBackgroundService. Questo metodo riceve gli aggiornamenti della proprieta desiderata dal modulo gemello e aggiorna la variabile temperatureThreshold. Tutti i moduli hanno un modulo gemello che consente di configurare il codice in esecuzione all'interno di un modulo direttamente dal 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. Aggiungere il metodo FilterMessages. Questo metodo viene chiamato ogni volta che l'hub di IoT Edge invia un messaggio al modulo. Filtra i messaggi con un valore della temperatura inferiore alla soglia relativa alla temperatura configurata tramite il modulo gemello. Aggiunge inoltre la proprietà MessageType al messaggio con il valore impostato su Avviso.

    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. Salvare il file ModuleBackgroundService.cs.

  9. Nello strumento di esplorazione di Visual Studio Code aprire il file deployment.template.json nell'area di lavoro della soluzione IoT Edge.

  10. Poiché è stato modificato il nome dell'endpoint su cui il modulo è in ascolto, è anche necessario aggiornare le route nel manifesto della distribuzione in modo che edgeHub invii messaggi al nuovo endpoint.

    Trovare la sezione route nel modulo gemello $edgeHub. Aggiornare la route sensorTofiltermodule per sostituire input1 con inputFromSensor:

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

  11. Aggiungere il modulo gemello filtermodule al manifesto della distribuzione. Inserire il contenuto JSON seguente alla fine della sezione modulesContent dopo il modulo gemello $edgeHub:

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

  12. Salvare il file deployment.template.json.

Compilare ed eseguire il push della soluzione

Sono stati aggiornati il codice dei moduli e il modello di distribuzione per comprendere alcuni concetti chiave relativi alla distribuzione. Ora è possibile compilare l'immagine del contenitore del modulo ed eseguirne il push nel Registro Container.

In Visual Studio Code aprire il file manifesto della distribuzione deployment.template.json. Il manifesto della distribuzione descrive i moduli da configurare nel dispositivo IoT Edge di destinazione. Prima della distribuzione, è necessario aggiornare le credenziali di Registro Azure Container e le immagini del modulo con i valori createOptions appropriati. Per altre informazioni sui valori createOption, vedere Come configurare le opzioni di creazione di contenitori per i moduli IoT Edge.

Se si usa un Registro Azure Container per archiviare l'immagine del modulo, aggiungere le credenziali ai moduli della sezione Content>edgeAgent>impostazioni>registryCredentials in deployment.template.json. Sostituire myacr con il proprio nome del Registro di sistema e specificare la password e l'indirizzo del server di accesso. Ad esempio:

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

Aggiungere o sostituire il contenuto stringato seguente al valore createOptions per ogni sistema (edgeHub e edgeAgent) e al modulo personalizzato (filtermodule e tempSensor) elencati. Modificare i valori, se necessario.

"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

Ad esempio, la configurazione del modulo di filtro (filtermodule) dovrebbe essere simile alla seguente:

"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\"}]}}}"
}

Immagine Docker del modulo di compilazione

Aprire il terminale integrato di Visual Studio Code selezionando Visualizza>Nuovo terminale.

Usare il comando dotnet publish per compilare l'immagine del contenitore per l'architettura Linux e amd64. Passare alla directory filtermodule nel progetto ed eseguire il comando dotnet publish.

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

Attualmente, il modello di strumento iotedgedev è destinato a .NET 7.0. Se si vuole impostare come destinazione una versione diversa di .NET, è possibile modificare il file filtermodule.csproj e modificare i valori TargetFramework e PackageReference. Ad esempio, per impostare come destinazione .NET 8.0, il file filtermodule.csproj dovrebbe essere simile al seguente:

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

Contrassegnare l'immagine Docker con le informazioni, la versione e l'architettura del registro contenitori. Sostituire myacr con il proprio nome del Registro di sistema.

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

Immagine Docker del modulo push

Fornire a Docker le credenziali del Registro Container, per consentire il push dell'immagine del contenitore da archiviare nel registro.

  1. Accedere a Docker con le credenziali del Registro Azure Container.

    docker login -u <ACR username> -p <ACR password> <ACR login server>

    Potrebbe venire visualizzato un avviso di sicurezza in cui si consiglia l'uso di --password-stdin. Sebbene si tratti di una procedura consigliata per gli scenari di produzione, esula dell'ambito di questa esercitazione. Per altri dettagli, vedere le informazioni di riferimento sull'accesso a Docker.

  2. Accedere al Registro Azure Container. È necessario installare l'interfaccia della riga di comando di Azure per usare il comando az. Questo comando richiede il nome utente e la password trovati nel registro contenitori in Impostazioni>Chiavi di accesso.

    az acr login -n <ACR registry name>

    Suggerimento

    Se si è disconnessi in qualsiasi momento di questa esercitazione, ripetere i passaggi di accesso a Docker e Registro Azure Container per continuare.

  3. Eseguire il push dell'immagine del modulo nel registro locale o in un registro contenitori.

    docker push <ImageName>

    Ad esempio:

    # 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

Aggiornare il modello di distribuzione

Aggiornare il modello di distribuzione deployment.template.json con il percorso dell'immagine del registro contenitori. Ad esempio, se si usa un registro Azure Container myacr.azurecr.io e l'immagine è filtermodule:0.0.1-amd64, aggiornare la configurazione filtermodule in:

"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\"}]}}}"
    }
}

Nello strumento di esplorazione di Visual Studio Code fare clic con il pulsante destro del mouse sul file deployment.template.json e scegliere Build and Push IoT Edge Solution (Compila ed esegui il push della soluzione IoT Edge).

Il comando di creazione e push avvia tre operazioni. Prima di tutto, crea una nuova cartella nella soluzione denominata config che contiene il manifesto completo della distribuzione, basato sulle informazioni del modello di distribuzione e di altri file della soluzione. In secondo luogo, esegue docker build per creare l'immagine del contenitore in base al documento dockerfile appropriato per l'architettura di destinazione. Infine, esegue docker push per eseguire il push del repository di immagini nel registro contenitori.

Questo processo può richiedere alcuni minuti quando viene eseguito per la prima volta, ma alla successiva esecuzione dei comandi avviene più rapidamente.

Facoltativo: aggiornare il modulo e l'immagine

Se si apportano modifiche al codice del modulo, è necessario ricompilare ed eseguire il push dell'immagine del modulo nel registro contenitori. Usare la procedura descritta in questa sezione per aggiornare l'immagine di compilazione e contenitore. È possibile ignorare questa sezione se non sono state apportate modifiche al codice del modulo.

Aprire il file deployment.amd64.json nella nuova cartella config creata. Il nome del file riflette l'architettura di destinazione, quindi è diverso se si sceglie un'architettura diversa.

Si noti che i due parametri contenenti i segnaposto contengono ora i valori appropriati. La sezione registryCredentials contiene nome utente e password del registro di cui è stato eseguito il pull dal file con estensione .env. Filtermodule contiene il repository di immagini completo, con tag di architettura, nome e versione indicati nel file module.json.

  1. Aprire il file module.json nella cartella filtermodule.

  2. Modificare il numero di versione per l'immagine del modulo. Incrementare ad esempio il numero di versione della patch a "version": "0.0.2", come se fosse stata apportata una piccola correzione nel codice del modulo.

    Suggerimento

    Le versioni dei moduli consentono di usare il controllo della versione e di testare le modifiche in un piccolo set di dispositivi prima di distribuire gli aggiornamenti nell'ambiente di produzione. Se non si incrementa la versione del modulo prima della compilazione e del push, si sovrascrive il repository nel Registro Container.

  3. Salvare le modifiche nel file module.json.

Compilare ed eseguire il push dell'immagine aggiornata con un tag di versione 0.0.2. Ad esempio, per compilare ed eseguire il push dell'immagine per il registro locale o un registro Azure Container, usare i comandi seguenti:


# 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

Fare di nuovo clic con il pulsante destro del mouse sul file deployment.template.json e scegliere di nuovo Build and push IoT Edge solution (Compila ed esegui il push della soluzione IoT Edge).

Aprire di nuovo il file deployment.amd64.json. Si noti che il sistema di compilazione non crea un nuovo file quando si esegue di nuovo il comando di compilazione e push. Invece, lo stesso file viene aggiornato per riflettere le modifiche. L'immagine filtermodule ora punta alla versione 0.0.2 del contenitore.

Per verificare ulteriormente il risultato del comando di compilazione e push, aprire il portale di Azure e passare al Registro Container.

Nel Registro Container selezionare Repository e quindi filtermodule. Verificare che venga eseguito il push di entrambe le versioni dell'immagine nel registro.

Screenshot della posizione in cui visualizzare entrambe le versioni delle immagini nel registro contenitori.

Risoluzione dei problemi

Se si verificano errori durante la compilazione e il push dell'immagine del modulo, spesso il problema è legato alla configurazione di Docker nel computer di sviluppo. Usare le indicazioni seguenti per esaminare la configurazione:

  • È stato eseguito il comando docker login usando le credenziali copiate dal Registro Container? Queste credenziali sono diverse rispetto a quelle usate per accedere ad Azure.
  • Il repository di contenitori è corretto? Il nome del Registro Container e quello del modulo sono corretti? Aprire il file module.json nella cartella filtermodule da controllare. Il valore del repository deve essere simile a <nome registro>.azurecr.io/filtermodule.
  • Se è stato usato un nome diverso da filterModule per il modulo, il nome è coerente in tutta la soluzione?
  • Il computer esegue contenitori dello stesso tipo di quelli che si stanno compilando? Questa esercitazione è relativa ai dispositivi IoT Edge Linux, quindi in Visual Studio Code deve essere presente l'indicazione amd64 o arm32v7 sulla barra laterale e Docker Desktop deve eseguire contenitori Linux.

Distribuire i moduli nel dispositivo

Si è verificato che le immagini dei contenitori di cui è stata eseguita la compilazione sono archiviate nel Registro Container, quindi è possibile eseguirne la distribuzione in un dispositivo. Assicurarsi che il dispositivo IoT Edge sia in esecuzione.

Usare il comando set-modules dell'interfaccia della riga di comando di Azure di IoT Edge per distribuire i moduli nell'hub IoT di Azure. Ad esempio, per distribuire i moduli definiti nel file deployment.template.json nell'hub IoT my-iot-hub per il dispositivo IoT Edge my-device, usare il comando seguente. Sostituire i valori della stringa di connessione dell'hub IoT hub-name, device-id e account di accesso con i propri.

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

Suggerimento

È possibile trovare la stringa di connessione dell'hub IoT, inclusa la chiave di accesso condiviso nel portale di Azure. Passare alle >impostazioni di sicurezza>Criteri di accesso condiviso>iothubowner dell'hub IoT.

  1. Nello strumento di esplorazione di Visual Studio Code espandere Dispositivi nella sezione Azure IoT Hub (Hub IoT di Azure) per visualizzare l'elenco dei dispositivi IoT.

  2. Fare clic con il pulsante destro del mouse sul dispositivo IoT Edge in cui si vuole eseguire la distribuzione, quindi scegliere Create Deployment for Single Device (Crea la distribuzione per un unico dispositivo).

  3. In Esplora file passare alla cartella config e quindi selezionare il file deployment.amd64.json.

    Non usare il file deployment.template.json, nel quale non sono presenti le credenziali del Registro Container o i valori delle immagini dei moduli. Se si usa un dispositivo Linux ARM32, il nome del manifesto della distribuzione è deployment.arm32v7.json.

  4. Nel dispositivo espandere Moduli per visualizzare un elenco dei moduli distribuiti e in esecuzione. Selezionare il pulsante Aggiorna. Verranno visualizzati i nuovi moduli tempSensor e filtermodule in esecuzione nel dispositivo.

    L'avvio dei moduli potrebbe richiedere alcuni minuti. Il runtime IoT Edge deve ricevere il nuovo manifesto della distribuzione, eseguire il pull delle immagini dei moduli dal runtime del contenitore e quindi avviare ogni nuovo modulo.

Visualizzare i messaggi dal dispositivo

Il codice del modulo di esempio riceve i messaggi tramite la coda di input e li passa attraverso la coda di output. Il manifesto della distribuzione ha dichiarato route che hanno passato messaggi a filtermodule da tempSensor e quindi messaggi inoltrati da filtermodule all'hub IoT. Le estensioni Azure IoT Edge e Hub IoT di Azure consentono di visualizzare i messaggi quando arrivano all'hub IoT dai singoli dispositivi.

  1. Nella finestra di esplorazione di Visual Studio Code fare clic con il pulsante destro del mouse sul dispositivo IoT Edge da monitorare e quindi scegliere Start Monitoring Built-in Event Endpoint (Avvia monitoraggio endpoint eventi predefinito).

  2. Esaminare la finestra di output in Visual Studio Code per vedere i messaggi in arrivo nell'hub IoT.

    Screenshot che mostra dove visualizzare i messaggi del dispositivo in ingresso nel cloud.

Visualizzare le modifiche nel dispositivo

Se si vuole vedere cosa accade nel dispositivo, usare i comandi in questa sezione per controllare il runtime IoT Edge e i moduli in esecuzione nel dispositivo.

I comandi in questa sezione sono destinati al dispositivo IoT Edge, non al computer di sviluppo. Se si usa una macchina virtuale per il dispositivo IoT Edge, connettersi ora. In Azure passare alla pagina di panoramica della macchina virtuale e selezionare Connetti per accedere alla connessione shell sicura.

  • Visualizzare tutti i moduli distribuiti nel dispositivo e controllarne lo stato:

    iotedge list

    Dovrebbero essere presenti quattro moduli: i due moduli del runtime IoT Edge, tempSensor e filtermodule. Verranno visualizzati tutti e quattro gli elementi elencati come in esecuzione.

  • Esaminare i log per un modulo specifico:

    iotedge logs <module name>

    I moduli IoT Edge fanno distinzione tra maiuscole e minuscole.

    I log di tempSensor e filtermodule devono visualizzare i messaggi in corso di elaborazione. Il modulo edgeAgent è responsabile dell'avvio degli altri moduli, quindi i relativi log contengono le informazioni sull'implementazione del manifesto della distribuzione. Se un modulo non è elencato o non è in esecuzione, è probabile che i log edgeAgent presentino gli errori. Il modulo edgeHub è responsabile delle comunicazioni tra i moduli e l'hub IoT. Se i moduli sono in esecuzione, ma i messaggi non arrivano all'hub IoT, i log di edgeHub conterranno probabilmente degli errori.

Pulire le risorse

Se si intende continuare con il prossimo articolo consigliato, è possibile conservare le risorse e le configurazioni create e riutilizzarle. È anche possibile continuare a usare lo stesso dispositivo IoT Edge come dispositivo di test.

In caso contrario, è possibile eliminare le configurazioni locali e le risorse di Azure usate in questo articolo per evitare addebiti.

Eliminare le risorse di Azure

L'eliminazione delle risorse e dei gruppi di risorse di Azure è irreversibile. Assicurarsi di non eliminare accidentalmente il gruppo di risorse sbagliato o le risorse errate. Se l'hub IoT è stato creato all'interno di un gruppo di risorse esistente che contiene risorse che si vogliono conservare, eliminare solo la risorsa hub IoT stessa, invece dell'intero gruppo.

Per eliminare le risorse:

  1. Accedere al portale di Azure e selezionare Gruppi di risorse.

  2. Selezionare il nome del gruppo di risorse contenente le risorse di test di IoT Edge.

  3. Esaminare l'elenco delle risorse contenute nel gruppo di risorse. Per eliminarle tutte, è possibile selezionare Elimina gruppo di risorse. Se se ne vogliono eliminare solo alcune, è possibile selezionare ogni risorsa per eliminarle singolarmente.

Passaggi successivi

In questa esercitazione si configura Visual Studio Code nel computer di sviluppo e si è distribuito il primo modulo IoT Edge che contiene il codice per filtrare i dati non elaborati generati dal dispositivo IoT Edge.

Continuare con le esercitazioni successive per informazioni sul modo in cui Azure IoT Edge semplifica la distribuzione di servizi cloud di Azure per elaborare e analizzare i dati nei dispositivi perimetrali.

Eseguire il debug di moduli Azure IoT EdgeFunzioniAnalisi di flussoServizio Visione personalizzata