Eseguire il debug di moduli Azure 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.

Questo articolo mostra come usare Visual Studio Code per eseguire il debug di moduli IoT Edge in più linguaggi. Nel computer di sviluppo è possibile usare Visual Studio Code per collegare ed eseguire il debug di un modulo in un contenitore di moduli locale o remoto.

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

  • Interfaccia della 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.

Visual Studio Code supporta la scrittura di moduli IoT Edge nei linguaggi di programmazione seguenti:

  • C# e C# Funzioni di Azure
  • A
  • Python
  • Node.js
  • Java

Azure IoT Edge supporta le architetture dei dispositivi seguenti:

  • AMD64
  • ARM32v7
  • ARM64

Per altre informazioni sui sistemi operativi, i linguaggi e le architetture supportate, vedere Supporto di linguaggi e architetture.

Quando si usa l'estensione IoT Edge di Visual Studio Code, è anche possibile avviare ed eseguire il debug del codice del modulo nel simulatore IoT Edge.

È anche possibile usare un computer di sviluppo Windows ed eseguire il debug di moduli in un contenitore Linux usando IoT Edge per Linux in Windows (EFLOW). Per altre informazioni sull'uso di EFLOW per lo sviluppo di moduli, vedere Esercitazione: Sviluppare moduli IoT Edge con contenitori Linux usando IoT Edge per Linux in Windows.

Se non si ha familiarità con le funzionalità di debug di Visual Studio Code, vedere Debug di Visual Studio Code.

Prerequisiti

È possibile usare un computer o una macchina virtuale Windows, macOS o Linux come computer di sviluppo. Nei computer Windows è possibile sviluppare moduli Windows o Linux. Per sviluppare moduli Linux, usare un computer Windows che soddisfi i requisiti per Docker Desktop.

Per installare gli strumenti necessari per lo sviluppo e il debug, completare l'esercitazione Sviluppare moduli Azure IoT Edge usando Visual Studio Code.

Installare Visual Studio Code

Aggiungere le estensioni seguenti:

Per eseguire il debug di un modulo in un dispositivo, è necessario:

  • Un hub IoT attivo con almeno un dispositivo IoT Edge.
  • Un dispositivo IoT Edge fisico o un dispositivo virtuale. Per creare un dispositivo virtuale in Azure, seguire la procedura descritta nell'avvio rapido per Linux.
  • Un modulo IoT Edge personalizzato. Per creare un modulo personalizzato, seguire la procedura descritta nell'esercitazione Sviluppare moduli Azure IoT Edge usando Visual Studio Code.

Eseguire il debug senza un contenitore usando il simulatore IoT Edge

Il simulatore IoT Edge è uno strumento che viene eseguito nel computer di sviluppo e simula il comportamento di un singolo dispositivo IoT Edge. È possibile usare il simulatore IoT Edge per sviluppare e testare i moduli IoT Edge senza un dispositivo fisico o un runtime completo del dispositivo IoT Edge.

I passaggi di debug seguenti presuppongono che sia già stato creato un modulo personalizzato. Se non è stato creato un modulo personalizzato, seguire la procedura descritta nell'esercitazione Sviluppare moduli Azure IoT Edge usando Visual Studio Code.

Il debug di un modulo senza un contenitore non è disponibile quando si usa C o Python.

Eseguire il debug in modalità collegamento usando il simulatore IoT Edge

Il debug in modalità collegamento non è supportato per C o Python.

Eseguire il debug di un modulo con il runtime IoT Edge

In ogni cartella di modulo sono presenti diversi file Docker per tipi di contenitore differenti. Usare uno dei file che terminano con l'estensione debug per compilare il modulo per il test.

Durante il debug dei moduli con questo metodo, i moduli sono in esecuzione sul runtime di IoT Edge. Il dispositivo IoT Edge e il Visual Studio Code possono essere nello stesso computer o, più probabilmente, Visual Studio Code è nel computer di sviluppo mentre il runtime di IoT Edge e i moduli sono in esecuzione in altro computer fisico. Per eseguire il debug da Visual Studio Code, è necessario:

  • Configurare il dispositivo IoT Edge, compilare i moduli di IoT Edge con il Dockerfile .debug ed eseguire la distribuzione nel dispositivo IoT Edge.
  • Aggiornare launch.json in modo che Visual Studio Code possa collegarsi al processo in un contenitore nel computer remoto. Questo file si trova nella cartella .vscode dell'area di lavoro e viene aggiornato ogni volta che si aggiunge un nuovo modulo che supporta il debug.
  • Usare il debug SSH remoto per connettersi al contenitore nel computer remoto.

Compilare e distribuire il modulo in un dispositivo IoT Edge

In Visual Studio Code, aprire il file manifesto della distribuzione deployment.debug.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 opzioni di creazione di contenitori per moduli IoT Edge.

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

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

  2. Aggiungere o sostituire il contenuto stringified seguente al valore createOptions per ogni sistema (edgeHub ed edgeAgent) e modulo personalizzato (ad esempio filtermodule) 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 filtermodule deve essere simile a:

    "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\"}]}}}"
}
  1. Nel riquadro comandi di Visual Studio Code, eseguire il comando Azure IoT Edge: compila ed esegui il push della soluzione IoT Edge.
  2. Selezionare il file deployment.debug.template.json per la soluzione.
  3. Nella sezione Hub IoT di Azure>Dispositivi della vista Explorer di Visual Studio Code, fare clic con il pulsante destro del mouse sul nome del dispositivo IoT Edge per la distribuzione, quindi scegliere Crea distribuzione per singolo dispositivo.

    Suggerimento

    Per controllare di aver scelto un dispositivo IoT Edge, selezionarlo per espandere l'elenco dei moduli e verificare la presenza di $edgeHub e $edgeAgent. Ogni dispositivo IoT Edge include questi due moduli.

  4. Passare alla cartella config della soluzione, selezionare il file deployment.debug.amd64.json, quindi selezionare Select Edge Deployment Manifest (Seleziona manifesto della distribuzione di Edge).

È possibile controllare lo stato del contenitore dal dispositivo o dalla macchina virtuale eseguendo il comando docker ps in un terminale. Il contenitore è visibile nell’elenco dopo l'esecuzione del comando. Se Visual Studio Code e il runtime IoT Edge risultano in esecuzione nello stesso computer, controllare lo stato nella visualizzazione Docker in Visual Studio Code.

Importante

Se si usa un registro privato come Registro Azure Container per le immagini, potrebbe essere necessario eseguire l'autenticazione per eseguire il push delle immagini. Usare docker login <Azure Container Registry login server> o az acr login --name <Azure Container Registry name> per eseguire l'autenticazione.

Accedere a Docker

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 di Registro Azure Container salvate dopo la creazione del registro.

    docker login -u <Azure Container Registry username> -p <Azure Container Registry password> <Azure Container Registry login server>

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

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

    az acr login -n <Azure Container Registry name>

Suggerimento

Se ci si è disconnessi a un certo punto di questa esercitazione, ripetere i passaggi di accesso a Docker e Registro Azure Container per continuare.

Compilare l’immagine Docker del modulo

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

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

Ad esempio, 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 "./modules/filtermodule/Dockerfile.amd64.debug" -t localhost:5000/filtermodule:0.0.1-amd64 "./modules/filtermodule"

# Or build the image for an Azure Container Registry

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

Eseguire il push dell’immagine Docker del modulo

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
az acr login --name myacr
docker push myacr.azurecr.io/filtermodule:0.0.1-amd64

Distribuire il modulo nel dispositivo IoT Edge

Usare il comando set-modules dell'interfaccia della riga di comando di Azure IoT Edge per distribuire i moduli nell'hub IoT di Azure. Ad esempio, per distribuire i moduli definiti nel file deployment.debug.template.json nell’hub IoT my-iot-hub per il dispositivo IoT Edgemy-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>"

Suggerimento

È possibile trovare la chiave di accesso condivisa dell'hub IoT nel portale di Azure nell’hub IoT >Impostazioni di sicurezza>Criteri di accesso condiviso>iothubowner.

Eseguire il debug del modulo

Per eseguire il debug di moduli in un dispositivo remoto, è possibile usare il debug SSH remoto in Visual Studio Code.

Per abilitare il debug remoto di Visual Studio Code, installare l’estensione di sviluppo remoto. Per altre informazioni sul debug remoto di Visual Studio Code, vedere Sviluppo remoto di Visual Studio Code.

Per informazioni dettagliate su come usare il debug SSH remoto in Visual Studio Code, vedere Sviluppo remoto usando SSH

Nella visualizzazione Debug di Visual Studio Code selezionare il file di configurazione del debug per il modulo. Per impostazione predefinita, il Dockerfile .debug, le impostazioni createOptions del contenitore del modulo e il file launch.json usano localhost.

Selezionare Avvia debug o premere F5. Selezionare il processo a cui collegarsi. Nella vista Debug di Visual Studio Code, è possibile vedere le variabili nel pannello a sinistra.

Eseguire il debug usando Docker Remote SSH

I motori Docker e Moby supportano connessioni SSH ai contenitori, consentendo di eseguire il debug in Visual Studio Code connesso a un dispositivo remoto. È necessario soddisfare i prerequisiti seguenti per usare questa funzione.

I prerequisiti di debug SSH remoto possono essere diversi a seconda del linguaggio in uso. Le sezioni seguenti descrivono la configurazione per .NET. Per informazioni su altri linguaggi, vedere Sviluppo remoto usando SSH per una panoramica. I dettagli su come configurare il debug remoto sono inclusi nelle sezioni di debug per ogni linguaggio nella documentazione di Visual Studio Code.

Configurare il tunneling SSH di Docker

  1. Seguire la procedura descritta in Tunneling SSH di Doker per configurare il tunneling SSH nel computer di sviluppo. Il tunneling SSH richiede l'autenticazione di una coppia di chiavi pubblica/privata e un contesto Docker che definisce l'endpoint del dispositivo remoto.

  2. La connessione a Docker richiede privilegi a livello root. Seguire la procedura descritta in Gestire Docker come utente non root per consentire la connessione al daemon Docker nel dispositivo remoto. Al termine del debug, è possibile rimuovere l'utente dal gruppo Docker.

  3. In Visual Studio Code, usare il riquadro comandi (Ctrl+Maiusc+P) per emettere il comando Contesto Docker: usa per attivare il contesto Docker che punta al computer remoto. Con questo comando, Visual Studio Code e l'interfaccia della riga di comando di Docker usano il contesto del computer remoto.

    Suggerimento

    Tutti i comandi Docker usano il contesto corrente. Ricordarsi di tornare al contesto in predefinito al termine del debug.

  4. Per verificare che il contesto Docker remoto sia attivo, elencare i contenitori in esecuzione nel dispositivo remoto:

    docker ps

    L'output deve elencare i contenitori in esecuzione nel dispositivo remoto in modo simile:

    PS C:\> docker ps        
CONTAINER ID   IMAGE                                                             COMMAND                   CREATED        STATUS         PORTS                                                                                                                                   NAMES
a317b8058786   myacr.azurecr.io/filtermodule:0.0.1-amd64                         "dotnet filtermodule…"    24 hours ago   Up 6 minutes                                                                                                                                           filtermodule
d4d949f8dfb9   mcr.microsoft.com/azureiotedge-hub:1.5                            "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes   0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:5671->5671/tcp, :::5671->5671/tcp, 0.0.0.0:8883->8883/tcp, :::8883->8883/tcp, 1883/tcp   edgeHub
1f0da9cfe8e8   mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0   "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes                                                                                                    
                                       tempSensor
66078969d843   mcr.microsoft.com/azureiotedge-agent:1.5                          "/bin/sh -c 'exec /a…"    24 hours ago   Up 6 minutes                                                                                                    
                                       edgeAgent

  5. Nella directory .vscode, aggiungere una nuova configurazione a launch.json aprendo il file in Visual Studio Code. Selezionare Aggiungi configurazione e scegliere il modello di collegamento remoto corrispondente per il modulo. Ad esempio, la configurazione seguente è per .NET Core. Modificare il valore per il parametro -H in PipeArgs nell’indirizzo IP o nel nome DNS del dispositivo.

    "configurations": [
{
  "name": "Remote Debug IoT Edge Module (.NET Core)",
  "type": "coreclr",
  "request": "attach",
  "processId": "${command:pickRemoteProcess}",
  "pipeTransport": {
    "pipeProgram": "docker",
    "pipeArgs": [
      "-H",
      "ssh://user@my-device-vm.eastus.cloudapp.azure.com:22",
      "exec",
      "-i",
      "filtermodule",
      "sh",
      "-c"
    ],
    "debuggerPath": "~/vsdbg/vsdbg",
    "pipeCwd": "${workspaceFolder}",
    "quoteArgs": true
  },
  "sourceFileMap": {
    "/app": "${workspaceFolder}/modules/filtermodule"
  },
  "justMyCode": true
},

Eseguire il debug remoto di un modulo

  1. Nella vista Debug di Visual Studio Code, selezionare la configurazione di debug Modulo IoT Edge debug remoto (.NET Core).

  2. Selezionare Avvia debug o premere F5. Selezionare il processo a cui collegarsi.

  3. Nella vista Debug di Visual Studio Code, è possibile vedere le variabili nel pannello a sinistra.

  4. In Visual Studio Code, impostare punti di interruzione nel modulo personalizzato.

  5. Quando viene raggiunto un punto di interruzione, è possibile ispezionare le variabili, scorrere il codice ed eseguire il debug del modulo.

    Screenshot di Visual Studio Code collegato a un contenitore Docker in un dispositivo remoto sospeso in corrispondenza di un punto di interruzione.

Nota

L'esempio precedente illustra come eseguire il debug di moduli IoT Edge in contenitori remoti. L'esempio aggiunge un contesto Docker remoto e modifiche ai privilegi Docker nel dispositivo remoto. Dopo aver completato il debug dei moduli, impostare il contesto Docker su predefinito e rimuovere i privilegi dall'account utente.

Per un esempio usando un dispositivo Raspberry Pi, vedere questo post del blog per sviluppatori IoT.

Passaggi successivi

Dopo aver compilato il modulo, informazioni su come distribuire i moduli di Azure IoT Edge.

Per sviluppare moduli per i dispositivi IoT Edge, apprendere l’uso degli SDK di Hub IoT di Azure.