Usare Visual Studio 2022 per sviluppare ed eseguire il debug di moduli per Azure IoT Edge

1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul nome del progetto principale e selezionare Impostare la versione del runtime di IoT Edge.

   

2. Usare il menu a discesa per scegliere la versione di runtime in cui sono in esecuzione i dispositivi IoT Edge, quindi selezionare OK per salvare le modifiche. Se non è stata apportata alcuna modifica, selezionare Annulla per uscire.

   Attualmente, l'estensione non include una selezione per le versioni di runtime più recenti. Se si vuole impostare la versione di runtime successiva alla 1.2, aprire il file manifesto della distribuzione deployment.debug.template.json. 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",
      //...
   

3. Se è stata modificata la versione, rigenerare il manifesto della distribuzione facendo clic con il pulsante destro del mouse sul nome del progetto e scegliendo Genera distribuzione per IoT Edge. In questo modo viene generato un manifesto della distribuzione basato sul modello di distribuzione e visualizzato nella cartella config del progetto di Visual Studio.

1. Aprire il file manifesto della distribuzione deployment.debug.template.json. Un manifesto di distribuzione è un documento JSON che descrive i moduli da configurare nei dispositivi 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",
       //...
   

Eseguire il debug con il simulatore

Lo strumento di sviluppo Azure IoT EdgeHub offre un'esperienza di sviluppo e debug locale. Lo strumento consente di avviare moduli senza runtime IoT Edge, in modo da poter creare, sviluppare ed eseguire moduli e soluzioni IoT Edge in locale ed eseguirne il debug. Non è necessario eseguire il push delle immagini in un registro contenitori e distribuirli a un dispositivo per il test.

Per altre informazioni, vedere Azure IoT EdgeHub Dev Tool.

Per inizializzare lo strumento in Visual Studio:

1. Recuperare la stringa di connessione del dispositivo IoT Edge (disponibile nell'hub IoT) dal portale di Azure o dall'interfaccia della riga di comando di Azure.

   Se si usa l'interfaccia della riga di comando per recuperare la stringa di connessione, usare questo comando, sostituendo "[device_id]" e "[hub_name]" con i propri valori:

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

2. Dal menu Strumenti in Visual Studio selezionare Azure IoT Edge Tools>Configurare il simulatore IoT Edge.

3. Incollare la stringa di connessione e selezionare OK.

Compilare ed eseguire il debug 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. Lo strumento simulatore IoT Edge consente di eseguire un singolo modulo in isolamento un messaggio di invio sulla porta 53000.

1. In Esplora soluzioniselezionare ed evidenziare la cartella del progetto del modulo, ad esempio IotEdgeModule1. Impostare il modulo personalizzato come progetto di avvio. Selezionare Progetto>Imposta come progetto di avvio dal menu.

2. Premere F5 o selezionare il pulsante Esegui barra degli strumenti per avviare il simulatore IoT Edge per un singolo modulo. Inizialmente possono essere necessari da 10 a 20 secondi.

   

3. Si noterà che appare una finestra dell'app della console .NET Core se il modulo è stato inizializzato correttamente.

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 InputQueue1Callback() funzione in main.c.

5. Testare il modulo inviando un messaggio. Quando si esegue il debug di un singolo modulo, il simulatore è in ascolto sulla porta predefinita 53000 per i messaggi. Per inviare un messaggio al modulo, eseguire il comando curl seguente da una shell dei comandi come Git Bash oWSL Bash.

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

   Se viene visualizzato l'errore con parentesi graffa singola o doppia chiusa senza corrispondenza nell'URL, provare il comando seguente:

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

   

   Il punto di interruzione deve essere attivato. È possibile controllare le variabili nella finestra Locali di Visual Studio, rilevate quando il debugger è in esecuzione. Passare a Eseguire il debug>Windows>Locali.

   Nella shell o Bash dovrebbe essere visualizzata una conferma {"message":"accepted"}.

   Nella console .NET dovrebbe essere visualizzato:

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

6. Premere CTRL+F5 oppure selezionare il pulsante Arresta per arrestare il debug.

Compilare ed eseguire il debug di più moduli

Dopo aver completato lo sviluppo di un modulo singolo, è possibile eseguire ed effettuare il debug di un'intera soluzione con più moduli. Lo strumento simulatore IoT Edge consente di eseguire tutti i moduli definiti nel manifesto della distribuzione, incluso un edgeHub simulato per il routing dei messaggi. In questo esempio vengono eseguiti due moduli personalizzati e il modulo del sensore di temperatura simulato. I messaggi del modulo del sensore temperatura simulato vengono instradati a ogni modulo personalizzato.

1. In Esplora soluzioni aggiungere un secondo modulo alla soluzione facendo clic con il pulsante destro del mouse sulla cartella principale del progetto. Dal menu scegliere Aggiungi>Nuovo modulo IoT Edge.

   

2. Nella finestra Add module assegnare un nome al nuovo modulo e sostituire la parte localhost:5000 dell'URL del repository con il server di accesso del Registro Azure Container, come in precedenza.

3. Aprire il file deployment.debug.template.json per verificare che il nuovo modulo sia stato aggiunto nella sezione Moduli. È stata aggiunta anche una nuova route alla sezione route in EdgeHub per inviare messaggi dal nuovo modulo all'hub IoT. Per inviare dati dal sensore di temperatura simulata al nuovo modulo, aggiungere un'altra route con la riga seguente di JSON. Sostituire <NewModuleName> (in due posizioni) con il nome del modulo.

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

4. Fare clic con il pulsante destro del mouse sul progetto principale (ad esempio, AzureIotEdgeApp1) e selezionare Imposta come progetto di avvio. Impostando il progetto principale come progetto di avvio, vengono eseguiti tutti i moduli della soluzione. Sono inclusi entrambi i moduli aggiunti alla soluzione, il modulo del sensore di temperatura simulato e l'hub edge simulato.

5. Premere F5 o selezionare il pulsante Esegui barra degli strumenti per eseguire la soluzione. Inizialmente potrebbero essere necessari da 10 a 20 secondi. Assicurarsi di non avere altri contenitori Docker in esecuzione che si potrebbero associare alla porta necessaria per questo progetto.

6. Verranno visualizzate due finestre dell'app della console .NET Core una per ogni modulo.

7. Impostare un punto di interruzione per esaminare i moduli.

   • 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 InputQueue1Callback() funzione in main.c.

8. Creare i punti di interruzione in ofgni modulo e quindi premere F5 per eseguire ed effettuare il debug di più moduli contemporaneamente. Si dovrebbero vedere più finestre dell'app della console .NET Core, ognuna delle quali rappresenta un modulo diverso.

   

9. Premere CTRL+F5 oppure selezionare il pulsante Arresta per arrestare il debug.

Compilare ed eseguire il push di immagini nel Registro di sistema

Dopo aver sviluppato e sottoposto a debug il modulo, è possibile compilare ed eseguire il push dell'immagine del modulo nel Registro Azure Container. È possibile distribuire il modulo nel dispositivo IoT Edge.

1. Impostare il progetto IoT Edge principale come progetto di avvio, non come uno dei singoli moduli.

2. Selezionare Debug o Versione come configurazione per la compilazione delle immagini del modulo.

   Nota

   Quando si sceglie Debug, Visual Studio usa Dockerfile.(amd64|windows-amd64).debug per compilare le immagini Docker. Ciò include VSDBG, ovvero il debugger della riga di comando di .NET Core, nell'immagine del contenitore durante la compilazione. Per i moduli IoT Edge per l'ambiente di produzione, è consigliabile usare la configurazione Versione, che usa Dockerfile.(amd64|windows-amd64) senza VSDBG.

3. Se si usa un registro privato come Registro Azure Container (ACR), usare il comando Docker seguente per l'accesso. È possibile ottenere il nome utente e la password dalla pagina chiavi di accesso del registro nel portale di Azure.

   docker login <ACR login server>
   

4. Aggiungere le informazioni di accesso del Registro Azure Container alle impostazioni di runtime disponibili nel file deployment.debug.template.json. Per eseguire questa operazione è possibile procedere in due modi: È possibile aggiungere le credenziali del Registro di sistema al file .env (più sicuro) o aggiungerle direttamente al file deployment.debug.template.json.

   Aggiungere le credenziali al .env file:

   In Esplora soluzioniselezionare il pulsante della barra degli strumenti Mostra tutti i file. Viene visualizzato il file .env. Aggiungere il nome utente e la password del Registro Azure Container al file .env. Queste credenziali sono disponibili nella pagina Chiavi di accesso del Registro Azure Container nel portale di Azure.

   

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

   Aggiungere le credenziali direttamente a deployment.debug.template.json

   Se si preferisce, aggiungere le credenziali direttamente al modello di distribuzione, sostituire i segnaposto con il nome utente, la password e il nome del Registro di sistema dell'amministratore del Registro Azure Container.

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

   Nota

   Questo articolo usa le credenziali di accesso amministratore per Registro Azure Container, 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 le entità servizio. Per altre informazioni, vedere Gestire l'accesso al registro contenitori.

5. Se si usa un registro locale, è possibile eseguire un registro locale.

6. Infine, in Esplora soluzioni, fare clic con il pulsante destro del mouse sulla cartella del progetto principale e scegliere Compila ed esegui il push dei moduli IoT Edge per compilare ed eseguire il push dell'immagine Docker per ogni modulo. L'operazione potrebbe richiedere un minuto. Quando viene visualizzata Finished Build and Push IoT Edge Modules. nella console di output di Visual Studio, l'operazione è completata.

Distribuire la soluzione

Dopo aver compilato ed eseguito il push delle immagini del modulo nel Registro Azure Container, è possibile implementare la soluzione nel dispositivo IoT Edge. In questa esercitazione è già stato analizzato un modello del manifesto di distribuzione. A questo punto si genererà un manifesto della distribuzione, quindi si userà un comando dell'interfaccia della riga di comando di Azure per implementare i moduli nel dispositivo IoT Edge in Azure.

1. Fare clic con il pulsante destro del mouse sul progetto principale in Esplora soluzioni di Visual Studio e scegliere Genera distribuzione per IoT Edge.

   

2. Passare alla cartella principale del progetto di Visual Studio locale e cercare nella cartella config. Il percorso del file potrebbe essere simile al seguente: C:\Users\<YOUR-USER-NAME>\source\repos\<YOUR-IOT-EDGE-PROJECT-NAME>\config. Qui si trova il manifesto della distribuzione generato, ad esempio deployment.amd64.debug.json.

3. Controllare il file deployment.amd64.debug.json per verificare che la versione dello schema edgeHub sia impostata su 1.2.

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

   Suggerimento

   Il modello di distribuzione per Visual Studio 2022 richiede la versione dello schema 1.2. Se è necessario che sia 1.1 o 1.0, attendere fino a quando non viene generata la distribuzione (non modificarla in deployment.debug.template.json). La generazione di una distribuzione creerà uno schema 1.2 per impostazione predefinita. Tuttavia, è possibile modificare manualmente deployment.amd64.debug.json, il manifesto generato, se necessario, prima di distribuirlo in Azure.

   Importante

   Dopo aver distribuito il dispositivo IoT Edge, attualmente non verrà visualizzato correttamente nel portale di Azure con schema versione 1.2 (la versione 1.1 sarà corretta). Si tratta di un bug noto e verrà risolto a breve. Tuttavia, questo non influirà sul dispositivo, perché è ancora connesso nell'hub IoT e si può comunicare con esso in qualsiasi momento usando l'interfaccia della riga di comando di Azure.

   

4. A questo punto si implementerà il manifesto con un comando dell'interfaccia della riga di comando di Azure. Aprire il Prompt dei comandi per gli sviluppatori di Visual Studio e passare alla directory config.

       cd config
   

5. Implementare il manifesto per il dispositivo IoT Edge nell'hub IoT. Il comando configura il dispositivo per l'uso di moduli sviluppati nella soluzione. Il manifesto della distribuzione è stato creato nel passaggio precedente e archiviato nella cartella config. Dalla cartella config eseguire il comando di distribuzione seguente. Sostituire [device id], [hub name] e [file path] con i propri valori. Se l'ID dispositivo IoT Edge non esiste nell'hub IoT, deve essere creato.

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

   Ad esempio, il comando potrebbe essere simile al seguente:

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

6. Dopo aver eseguito il comando, verrà visualizzata una conferma della distribuzione stampata in JSON nel prompt dei comandi.

Immagine Docker del modulo di compilazione

Dopo aver sviluppato il modulo, è possibile compilare l'immagine del modulo da archiviare in un registro contenitori per la distribuzione nel dispositivo IoT Edge.

Usare il Dockerfile del modulo per compilare l'immagine Docker del modulo.

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

Si supponga, ad esempio, che la shell dei comandi si trova nella directory del progetto e che il nome del modulo sia IotEdgeModule1. Per compilare l'immagine per il registro locale o un registro Azure Container, usare i comandi seguenti:

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

Immagine Docker del modulo push

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

Distribuire il modulo nel dispositivo IoT Edge.

In Visual Studio aprire il file manifesto della distribuzione deployment.debug.template.json nel progetto principale. Un manifesto di distribuzione è un documento JSON che descrive i moduli da configurare nei dispositivi IoT Edge di destinazione. Prima della distribuzione, è necessario aggiornare le credenziali del Registro Azure Container, le immagini del modulo e i valori createOptions appropriati. Per altre informazioni sui valori createOption, vedere Come configurare le opzioni di creazione di contenitori per i moduli IoT Edge.

1. Se si usa un Registro Azure Container per archiviare l'immagine del modulo, è necessario aggiungere le credenziali per deployment.debug.template.json nelle impostazioni edgeAgent. ad esempio:

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

2. Sostituire il valore della proprietà immagine con il nome dell'immagine del modulo di cui è stato eseguito il push nel Registro di sistema. Ad esempio, se è stato eseguito il push di un'immagine contrassegnata myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 per il modulo personalizzato IotEdgeModule1, sostituire il valore della proprietà image con il valore del tag.

3. Aggiungere o sostituire il valore createOptions con contenuto stringato per ogni modulo di sistema e personalizzato nel modello di distribuzione.

   Ad esempio, le impostazioni immagine e createOptions di IotEdgeModule1 sono simili alle seguenti:

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

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.debug.amd64.json nell'hub IoT my-iot-hub per il dispositivo IoT Edge my-device, usare il comando seguente:

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