Eseguire il debug dei moduli di Azure IoT Edge con Visual Studio Code

  • Articolo

Si applica a:IoT Edge 1.4 checkmark IoT Edge 1.4

Importante

IoT Edge 1.4 è la versione supportata. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

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

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

  • Strumento da riga di comando di Azure IoT Edge Dev Tool (CLI). Questo strumento è preferibile per lo sviluppo.
  • Estensione Azure IoT Edge Tools per Visual Studio Code . L'estensione è in modalità di 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:

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

Azure IoT Edge supporta le architetture dei dispositivi seguenti:

  • AMD64
  • ARM32v7
  • ARM64

Per altre informazioni sui sistemi operativi, le lingue e le architetture supportate, vedere Supporto per 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 con 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 di Azure IoT Edge con Visual Studio Code .

Installare Visual Studio Code

Aggiungere le estensioni seguenti:

Per eseguire il debug del 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'argomento di avvio rapido per Linux.
  • Modulo IoT Edge personalizzato. Per creare un modulo personalizzato, seguire la procedura descritta nell'esercitazione Sviluppare moduli di Azure IoT Edge con 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 dei dispositivi 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 di Azure IoT Edge con Visual Studio Code .

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

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

Il debug in modalità di 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.

Quando si esegue il debug dei moduli usando questo metodo, i moduli vengono eseguiti sopra il 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 IoT Edge con il dockerfile con estensione debug e quindi distribuirlo nel dispositivo IoT Edge.
  • Aggiornare launch.json in modo che Visual Studio Code possa connettersi al processo in un contenitore nel computer remoto. È possibile trovare questo file nella cartella nell'area .vscode 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 appropriaticreateOptions. 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, aggiungere le credenziali alla sezione registro delle impostazioni>edgeAgentCredentials> in deployment.debug.template.json. Sostituire myacr con il proprio nome del Registro di sistema 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 stringato seguente al valore createOptions per ogni sistema (edgeHub e edgeAgent) e al modulo personalizzato (ad esempio filtermodule) elencato. 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 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\"}]}}}"
}
  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 visualizzazione Esplora risorse di Visual Studio Code fare clic con il pulsante destro del mouse sul nome del dispositivo IoT Edge per la distribuzione e 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 docker ps comando in un terminale. Il contenitore dovrebbe essere elencato 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

Specificare le credenziali del registro contenitori a Docker in modo che possa eseguire il push dell'immagine del contenitore nell'archiviazione nel registro.

  1. Accedere a Docker con le credenziali Registro Azure Container salvate dopo la creazione del Registro di sistema.

    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. Sebbene si tratti di 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 az comando . Questo comando richiede il nome utente e la password trovati nel registro contenitori nelle chiavi Impostazioni> Access.

    az acr login -n <Azure Container Registry name>

Suggerimento

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

Immagine Docker del modulo di compilazione

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"

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/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 di IoT Edge per distribuire i moduli nel hub IoT di Azure. Ad esempio, per distribuire i moduli definiti nel file deployment.debug.template.json in 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>"

Suggerimento

È possibile trovare la chiave di accesso condiviso hub IoT nella portale di Azure nelle impostazioni>di sicurezza di hub IoT> 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 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 con SSH

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

Selezionare Avvia debug o premere F5. Selezionare il processo a cui collegarsi. Nella visualizzazione Debug di Visual Studio Code sono visualizzate le variabili nel pannello sinistro.

Eseguire il debug con Docker Remote SSH

I motori Docker e Moby supportano connessioni SSH ai contenitori che consentono di eseguire il debug in Visual Studio Code connesso a un dispositivo remoto. Prima di poter usare questa funzionalità, è necessario soddisfare i prerequisiti seguenti.

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 con 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 Docker SSH tunneling per configurare il tunneling SSH nel computer di sviluppo. Il tunneling SSH richiede l'autenticazione della coppia di chiavi pubblica/privata e un contesto Docker che definisce l'endpoint del dispositivo remoto.

  2. Connessione ing in Docker richiede privilegi a livello radice. Seguire la procedura descritta in Gestire Docker come utente non radice 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 rilasciare il contesto Docker: usare il comando per attivare il contesto Docker che punta al computer remoto. Questo comando fa sì che Visual Studio Code e l'interfaccia della riga di comando di Docker usino il contesto del computer remoto.

    Suggerimento

    Tutti i comandi Docker usano il contesto corrente. Ricordarsi di tornare al contesto 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 dovrebbe 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.4                            "/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.4                          "/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 quindi scegliere il modello di collegamento remoto corrispondente per il modulo. Ad esempio, la configurazione seguente è per .NET Core. Modificare il valore del parametro -H in PipeArgs impostando il nome DNS o l'indirizzo IP 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 del modulo

  1. Nella visualizzazione Debug di Visual Studio Code selezionare la configurazione di debug Remote Debug IoT Edge Module (.NET Core).

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

  3. Nella visualizzazione Debug di Visual Studio Code le variabili sono visibili nel pannello sinistro.

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

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

    Screenshot of Visual Studio Code attached to a Docker container on a remote device paused at a breakpoint.

Nota

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

Per un esempio di uso di un dispositivo Raspberry Pi, vedere questo post di blog per sviluppatori IoT.

Passaggi successivi

Dopo aver compilato il modulo, vedere le informazioni su come distribuire i moduli Azure IoT Edge da Visual Studio Code.

Per sviluppare moduli per i dispositivi IoT Edge, comprendere e usare hub IoT di Azure SDK.