Esercitazione: Sviluppare moduli IoT Edge con contenitori Linux usando IoT Edge per Linux in Windows

Applica a: IoT Edge 1.5

Questa esercitazione illustra come sviluppare, eseguire il debug e distribuire codice personalizzato in un dispositivo Azure IoT Edge usando IoT Edge per Linux in Windows e Visual Studio 2022. Si apprenderà lo scenario di sviluppo più comune per le soluzioni IoT Edge distribuendo un modulo C# in un dispositivo Linux. Si distribuirà ed eseguirà il debug di un modulo di IoT Edge personalizzato in esecuzione in un contenitore Linux in Windows. Anche se si prevede di usare un linguaggio diverso o distribuire un servizio Azure, questa esercitazione è comunque utile per apprendere gli strumenti e i concetti di sviluppo.

Questa esercitazione include i passaggi per due strumenti di sviluppo IoT Edge:

• L'interfaccia a riga di comando (CLI) di Azure IoT Edge Dev Tool, che è lo strumento preferito per lo sviluppo.
• Estensione Azure IoT Edge Tools per Visual Studio, disponibile in modalità maintenance

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

In questa esercitazione verranno illustrate le procedure per:

Prerequisiti

Questa esercitazione presuppone l'uso di un computer che esegue Windows come computer di sviluppo. Nei computer Windows è possibile sviluppare moduli Windows o Linux. Questa esercitazione illustra lo sviluppo di contenitori Linux usando IoT Edge per Linux in Windows per la compilazione e la distribuzione dei moduli.

Prima di iniziare:

• Installare IoT Edge per Linux in Windows.

• Leggere la guida introduttiva Distribuire il primo modulo IoT Edge in un dispositivo Windows.

• Scarica .NET Core SDK.

• Installare o modificare Visual Studio 2022 nel computer di sviluppo. Scegliere le opzioni di workload Sviluppo di Azure e Sviluppo desktop con C++.

• Dopo aver pronto l'installazione di Visual Studio 2022, scaricare e installare Azure IoT Edge Tools da Visual Studio Marketplace.

  È possibile usare l'estensione Azure IoT Edge Tools per creare e compilare la soluzione IoT Edge. Lo strumento di sviluppo preferito è l'interfaccia della riga di comando di Azure IoT Edge Dev Tool. L'estensione include i modelli di progetto Azure IoT Edge usati per creare il progetto Visual Studio. Attualmente, è necessario installare l'estensione indipendentemente dallo strumento di sviluppo usato.

  Suggerimento

  Se si usa Visual Studio 2019, scaricare e installare Azure IoT Edge Tools per Visual Studio 2019 da Visual Studio Marketplace.

• Creare un hub IoT nel livello gratuito o standard in Azure come risorsa cloud.

Se non si ha un account Azure, creare un account free prima di iniziare.

Concetti chiave

Questa esercitazione illustra lo 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 ulteriori informazioni, vedere Comprendere i moduli di Azure IoT Edge.

Quando si sviluppano moduli IoT Edge, è importante comprendere la differenza tra il computer di sviluppo e il dispositivo di destinazione IoT Edge in cui verrà distribuito il modulo. Il contenitore compilato per contenere il codice del modulo deve corrispondere al sistema operativo del dispositivo di destinazione.

Ad esempio, lo scenario più comune è uno sviluppatore di un modulo in un computer Windows che intende usare come destinazione 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. Per questa esercitazione si userà l'host Windows per lo sviluppo e il IoT Edge per Linux in Windows macchina virtuale (VM) per la compilazione e la distribuzione dei moduli.

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. Raccomandiamo di usare Visual Studio per sviluppare con i contenitori Linux, quindi è ciò che questa esercitazione utilizza. È anche possibile usare Visual Studio Code, anche se esistono differenze di supporto tra i due strumenti. Per altre informazioni, vedere Develop Azure IoT Edge modules using Visual Studio Code .

Configurare l'interfaccia della riga di comando Docker e il motore Docker connessione remota del motore Docker

I moduli IoT Edge sono impacchettati come contenitori, quindi è necessario un motore di container sul computer di sviluppo per compilarli e gestirli.

L'IoT Edge per Linux su VM Windows contiene già un'istanza del Docker engine. Questa esercitazione illustra come connettersi in remoto dalla macchina di sviluppo Windows all'istanza Docker della VM di IoT Edge per Linux su Windows. Usando questa connessione remota, si rimuove la dipendenza da Docker Desktop per Windows.

Configurare l'interfaccia della riga di comando di Docker

Il primo passaggio consiste nel configurare l'interfaccia della riga di comando di Docker nel computer di sviluppo Windows per potersi connettere al motore Docker remoto:

1. Scaricare la versione precompilata docker.exe dell'interfaccia della riga di comando di Docker da Chocolatey. È anche possibile scaricare il progetto ufficiale cli da GitHub e compilarlo seguendo le istruzioni del repository.

2. Estrarre docker.exe in una directory nel computer di sviluppo, ad esempio C:\Docker\bin.

3. Apri Informazioni sul tuo PC>Informazioni sul sistema>Impostazioni avanzate di sistema.

4. Selezionare Variabilidi ambiente>. In Variabili utente selezionare Percorso.

5. Modificare la variabile Path e aggiungere il percorso di docker.exe.

6. Aprire una sessione di PowerShell con privilegi elevati.

7. Verificare che l'interfaccia della riga di comando di Docker sia accessibile usando questo comando:

   docker --version
   

   Se tutti gli elementi sono stati configurati correttamente, l'output del comando dovrebbe mostrare la versione di Docker. Dovrebbe essere simile a: Docker version 20.10.12, build e91ed57.

Configurare il motore Docker

Il secondo passaggio consiste nel configurare IoT Edge per Linux su Windows nel motore Docker della macchina virtuale per accettare connessioni esterne e aggiungere le regole del firewall appropriate.

1. Aprire una sessione di PowerShell con privilegi elevati ed eseguire i comandi seguenti:

   # Configure the IoT Edge for Linux on Windows VM Docker engine to accept external connections, and add the appropriate firewall rules.
   Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   
   # Create a copy of the IoT Edge for Linux on Windows VM _docker.service_ in the system folder.
   Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   
   # Replace the service execution line to listen for external connections.
   Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g'  /etc/systemd/system/docker.service"
   
   # Reload the IoT Edge for Linux on Windows VM services configurations.
   Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   
   # Reload the Docker engine service.
   Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   
   # Check that the Docker engine is listening to external connections.
   Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   

   Ecco un output di esempio:

   PS C:\> # Configure the IoT Edge for Linux on Windows virtual machine Docker engine to accept external connections, and add the appropriate firewall rules.
   PS C:\> Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   PS C:\>
   PS C:\> # Create a copy of the IoT Edge for Linux on Windows VM docker.service in the system folder.
   PS C:\> Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Replace the service execution line to listen for external connections.
   PS C:\> Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g' /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Reload the IoT Edge for Linux on Windows VM services configurations.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   PS C:\>
   PS C:\> # Reload the Docker engine service.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   PS C:\>
   PS C:\> # Check that the Docker engine is listening to external connections.
   PS C:\> Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   tcp6       0      0 :::2375                 :::*                    LISTEN      2790/dockerd
   

Testare la connessione

Il passaggio finale del setup consiste nel testare la connessione Docker al motore Docker della VM Windows per IoT Edge per Linux.

1. Ottenere l'indirizzo IP dell'IoT Edge per Linux su Windows macchina virtuale:

   Get-EflowVmAddr
   

   Suggerimento

   Se la IoT Edge per Linux in Windows macchina virtuale è stata distribuita senza un indirizzo IP statico, l'indirizzo IP potrebbe cambiare tra i riavvii del sistema operativo host Windows o le modifiche di rete. Assicurarsi di usare l'indirizzo IP corretto per il IoT Edge per Linux in Windows macchina virtuale ogni volta che si vuole stabilire una connessione remota al motore Docker.

   Ecco un output di esempio:

   PS C:\> Get-EflowVmAddr
   [03/15/2022 15:22:30] Querying IP and MAC addresses from virtual machine (DESKTOP-J1842A1-EFLOW)
    - Virtual machine MAC: 00:15:5d:6f:da:78
    - Virtual machine IP : 172.31.24.105 retrieved directly from virtual machine
   00:15:5d:6f:da:78
   172.31.24.105 
   

2. Collegarsi al motore Docker della macchina virtuale per Linux su Windows IoT Edge ed eseguire il contenitore di esempio hello-world. Sostituire <EFLOW-VM-IP> con l'indirizzo IP della macchina virtuale di IoT Edge per Linux su Windows ottenuto nel passaggio precedente.

   docker -H tcp://<EFLOW-VM-IP>:2375 run --rm hello-world
   

   Al termine del download del contenitore, il contenitore viene eseguito e produce questo output:

   PS C:\> docker -H tcp://172.31.24.105:2375 run --rm hello-world
   Unable to find image 'hello-world:latest' locally
   latest: Pulling from library/hello-world
   2db29710123e: Pull complete
   Digest: sha256:4c5f3db4f8a54eb1e017c385f683a2de6e06f75be442dc32698c9bbe6c861edd
   Status: Downloaded newer image for hello-world:latest
   
   Hello from Docker!
   This message shows that your installation appears to be working correctly.
   
   To generate this message, Docker took the following steps:
    1. The Docker client contacted the Docker daemon.
    2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
       (amd64)
    3. The Docker daemon created a new container from that image which runs the
       executable that produces the output you're currently reading.
    4. The Docker daemon streamed that output to the Docker client, which sent it
       to your terminal.
   
   To try something more ambitious, you can run an Ubuntu container with:
    $ docker run -it ubuntu bash
   
   Share images, automate workflows, and more with a free Docker ID:
    https://hub.docker.com/
   
   For more examples and ideas, visit:
    https://docs.docker.com/get-started/
   

Creare un progetto Azure IoT Edge

Il modello di progetto IoT Edge in Visual Studio crea una soluzione che è possibile distribuire nei dispositivi IoT Edge. Usare la procedura seguente per creare una soluzione Azure IoT Edge e quindi generare il primo modulo in tale soluzione. Ogni soluzione IoT Edge può contenere più moduli.

1. In Visual Studio creare un nuovo progetto selezionando Crea un nuovo progetto nella pagina iniziale o selezionando il pulsante Nuovo progetto sulla barra degli strumenti.

2. Nella pagina Creare un nuovo progetto cercare Azure IoT Edge. Selezionare il progetto corrispondente alla piattaforma (modulo Linux IoT Edge) e all'architettura per il dispositivo IoT Edge, quindi selezionare Next.

3. Nella pagina Configura il nuovo progetto immettere un nome per il progetto e specificare il percorso e quindi selezionare Crea.

4. Nella finestra di dialogo Aggiungi modulo selezionare il tipo di modulo da sviluppare. È anche possibile selezionare Modulo esistente per aggiungere un modulo di IoT Edge esistente alla distribuzione.

5. In Nome modulo specificare il nome del modulo.

6. In URL repository specificare il nome del repository di immagini del modulo. Visual Studio popola automaticamente il nome del modulo con localhost:5000/<nome del modulo>. Sostituire tale valore con le proprie informazioni di registro.

   Utilizzare localhost se si utilizza un registro Docker locale per il testing. Se si usa Azure Container Registry, usare il server di accesso dalle impostazioni del Registro di sistema. Il server di accesso è simile a <nome del registro>.azurecr.io. Sostituire solo la parte localhost:5000 della stringa, in modo che il risultato finale sia simile a <nome del registro>.azurecr.io/<nome del modulo>.

7. Selezionare Aggiungi per aggiungere il modulo al progetto.

   

   Note

   Se si dispone di un progetto di IoT Edge esistente, è possibile modificare l'URL del repository aprendo il file module.json. L'URL del repository si trova nella proprietà repository del file JSON.

È ora disponibile un progetto IoT Edge e un modulo IoT Edge nella soluzione Visual Studio.

Struttura progetto

La soluzione ha due cartelle a livello di progetto: una cartella di progetto principale e una cartella del modulo. Ad esempio, potrebbe essere disponibile una cartella di progetto principale denominata AzureIotEdgeApp1 e una cartella del modulo denominata IotEdgeModule1.

La cartella principale del progetto contiene il manifesto della distribuzione. Il manifesto della distribuzione è un documento JSON che descrive i moduli da configurare nel dispositivo di destinazione IoT Edge.

La cartella del modulo contiene un file per il codice del modulo. Il nome Program.cs è o main.c, a seconda della lingua scelta. Questa cartella contiene anche un file denominato module.json che descrive i metadati del modulo. Vari file Docker forniscono le informazioni necessarie per compilare il modulo come contenitore Windows o Linux.

Manifesto della distribuzione del progetto

Il manifesto della distribuzione modificato è denominato deployment.debug.template.json. Questo file è un modello di un manifesto della distribuzione IoT Edge che definisce tutti i moduli eseguiti in un dispositivo. Il file definisce anche il modo in cui i moduli comunicano tra loro. Per altre informazioni sui manifesti di distribuzione, vedere Informazioni su come distribuire i moduli e stabilire route.

Il modello di distribuzione comprende:

• I due moduli di runtime edgeAgent e edgeHub.
• Il modulo personalizzato creato in questo progetto di Visual Studio.
• Modulo denominato SimulatedTemperatureSensor. Questo modulo predefinito genera dati simulati che è possibile usare per testare i moduli (o eliminare se non è necessario). Per informazioni sul funzionamento del sensore di temperatura simulato, visualizzare il codice sorgente SimulatedTemperatureSensor.csproj.

Impostare la versione di runtime IoT Edge

Attualmente, la versione più recente del runtime stabile è 1.5. Aggiornare la versione di runtime IoT Edge alla versione stabile più recente o alla versione di destinazione per i dispositivi:

Sviluppare il modulo

Quando si aggiunge un nuovo modulo, viene fornito con codice predefinito pronto per la compilazione e la distribuzione in un dispositivo in modo che sia possibile avviare il test senza toccare alcun codice. Il codice del modulo si trova all'interno della cartella del modulo in un file denominato Program.cs (per C#) o main.c (per C).

Nella soluzione predefinita i dati simulati del modulo SimulatedTemperatureSensor vengono indirizzati al modulo. Il modulo accetta l'input e quindi lo invia a Azure IoT Hub.

Quando si è pronti per personalizzare il modello di modulo con il proprio codice, usare gli SDK Azure IoT Hub per compilare altri moduli che rispondono alle esigenze principali per le soluzioni IoT. Queste esigenze possono includere sicurezza, gestione dei dispositivi e affidabilità.

Compilare ed eseguire il push di un singolo modulo

In genere, è consigliabile testare ed eseguire il debug di ogni modulo prima di eseguirlo all'interno di un'intera soluzione con più moduli. Poiché la soluzione verrà compilata o eseguita il debug usando il motore Docker in esecuzione all'interno della IoT Edge per Linux in Windows macchina virtuale, il primo passaggio consiste nel compilare e pubblicare il modulo per abilitare il debug remoto:

1. In Solution Explorer selezionare la cartella del progetto del modulo, ad esempio myIotEdgeModule).

2. Impostare il modulo personalizzato come progetto di avvio. Nel menu, selezionare Progetto>Imposta come progetto di avvio.

3. Per eseguire il debug del modulo C# Linux, è necessario aggiornare il file Dockerfile.amd64.debug per abilitare il servizio SSH. Aggiornare il file Dockerfile.amd64.debug per usare il modello seguente: Dockerfile per Azure IoT Edge modulo C# AMD64 con supporto debug remoto.

   Note

   Quando si seleziona Debug, Visual Studio usa Dockerfile.(amd64|windows-amd64).debug per compilare immagini Docker. Questo file include il debugger della riga di comando .NET Core VSDBG nell'immagine del contenitore durante la costruzione. Per i moduli IoT Edge pronti per la produzione, è consigliabile usare la configurazione Release, che usa Dockerfile.(amd64|windows-amd64) senza VSDBG.

   Assicurarsi che nell'ultima riga del modello ENTRYPOINT ["dotnet", "IotEdgeModule1.dll"] il nome della DLL corrisponda al nome del progetto del modulo IoT Edge.

4. Per stabilire una connessione SSH con il modulo Linux, è necessario creare una chiave RSA. Aprire una sessione di PowerShell con privilegi elevati ed eseguire i comandi seguenti per creare una nuova chiave RSA. Salvare la chiave RSA nella stessa cartella del modulo IoT Edge e assicurarsi che il nome della chiave sia id_rsa.

   ssh-keygen -t RSA -b 4096 -m PEM
   

   

5. Se si usa un registro privato come Azure Container Registry, usare il comando Docker seguente per accedervi. È possibile ottenere il nome utente e la password dalla pagina Chiavi di accesso del Registro di sistema nel portale di Azure. Se si usa un registro locale, è possibile eseguire un registro locale.

   docker -H tcp://<EFLOW-VM-IP>:2375 login -u <Container Registry username> -p <Container Registry password> <Container Registry login server>
   

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

# Build the image for the local registry

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

# Or build the image for an Azure Container Registry

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

# Push the Docker image to the local registry

docker push localhost:5000/iotedgemodule1:0.0.1-amd64

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

Eseguire il debug della soluzione

1. In una sessione di PowerShell con privilegi elevati, vengono eseguiti i comandi seguenti:

   1. Ottenere il valore moduleId in base al nome del modulo Linux C#. Sostituire il segnaposto <iot-edge-module-name> con il nome del modulo.

      $moduleId = Invoke-EflowVmCommand "sudo docker ps -aqf name=<iot-edge-module-name>"
      

   2. Verificare che $moduleId sia corretto. Se la variabile è vuota, assicurarsi di usare il nome del modulo corretto.

   3. Avviare il servizio SSH all'interno del contenitore Linux:

      Invoke-EflowVmCommand "sudo docker exec -it -d $moduleId service ssh start"
      

   4. Aprire la porta SSH del modulo nella IoT Edge per Linux nella macchina virtuale Windows. (In questa esercitazione viene usata la porta 10022).

      Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 10022 -j ACCEPT"
      

   Avviso

   Per motivi di sicurezza, ogni volta che il IoT Edge per Linux in Windows macchina virtuale viene riavviata, la regola della tabella IP viene eliminata e torna alle impostazioni originali. Inoltre, è necessario avviare nuovamente il servizio SSH del modulo manualmente.

2. Dopo aver avviato correttamente il servizio SSH, selezionare Debug>Collega al processo, impostare Tipo di connessione su SSH e impostare Connection target all'indirizzo IP dell'IoT Edge per Linux su VM Windows. Se non si conosce l'indirizzo IP del IoT Edge per Linux in Windows macchina virtuale, è possibile usare il cmdlet di PowerShell Get-EflowVmAddr.

   Digitare l'INDIRIZZO IP e quindi premere INVIO. Nella finestra popup immettere le configurazioni seguenti:

   Campo	valore
   Nome host	Indirizzo IP per l'IoT Edge per Linux su macchina virtuale Windows
   Porto	10022 (o quello usato nella configurazione della distribuzione)
   Nome utente	radice
   Tipo di autenticazione	Chiave privata
   File di chiave privata	Percorso completo del valore id_rsa creato in un passaggio precedente
   Passphrase	Passphrase usata per la chiave creata in un passaggio precedente

3. Dopo la connessione al modulo tramite SSH, è possibile scegliere il processo e selezionare Collega. Per il modulo C# è necessario scegliere il processo dotnet e allegare a Managed (CoreCLR). La prima volta potrebbero essere necessari da 10 a 20 secondi.

4. Impostare un punto di interruzione per esaminare il modulo:

   • Se si sviluppa in C#, impostare un punto di interruzione nella funzione PipeMessage() in ModuleBackgroundService.cs.
   • Se si usa C, impostare un punto di interruzione nella funzione InputQueue1Callback() in main.c.

5. L'output di SimulatedTemperatureSensor deve essere reindirizzato a input1 del modulo Linux C# personalizzato. Il punto di interruzione deve essere attivato. È possibile controllare le variabili nella finestra Visual Studio Locals.

   

6. Per arrestare il debug, selezionare CTRL+F5 o selezionare il pulsante Arresta .

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 di un dispositivo di test.

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

Eliminare Azure risorse

Non è possibile annullare l'eliminazione di Azure risorse e gruppi di risorse. Assicurarsi di non eliminare accidentalmente il gruppo di risorse sbagliato o le risorse errate. Se è stato creato il IoT Hub all'interno di un gruppo di risorse esistente con risorse da conservare, eliminare solo la risorsa IoT Hub stessa, non il gruppo di risorse.

Per eliminare le risorse:

1. Accedere al portale di Azure e quindi selezionare Gruppi di risorse.
2. Selezionare il nome del gruppo di risorse che contiene le risorse di test IoT Edge.
3. Esaminare l'elenco delle risorse contenute nel gruppo di risorse. Per eliminarli tutti, è possibile selezionare Elimina gruppo di risorse. Se si vogliono eliminare solo alcuni di essi, selezionare ogni risorsa per eliminarle singolarmente.

Passaggio successivo

In questa esercitazione, configuri Visual Studio sul computer di sviluppo e distribuisci e sottoponi a debug il tuo primo modulo IoT Edge da Visual Studio. Ora che sono stati appresi i concetti di base, provare ad aggiungere funzionalità a un modulo in modo che possa analizzare i dati che passano attraverso di esso: