Condividi tramite

Eseguire il debug di moduli Azure IoT Edge usando Visual Studio Code

Applica a:IoT Edge 1.5 segno di spunta IoT Edge 1.5

Importante

IoT Edge 1.5 LTS è la versione supportata. IoT Edge 1,4 LTS ha raggiunto la fine della vita il 12 novembre 2024. Se si usa una versione precedente, vedere Update IoT Edge.

Questo articolo illustra come usare Visual Studio Code per eseguire il debug di moduli IoT Edge in più lingue. Nel computer di sviluppo 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 IoT Edge.

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

Selezionare la versione dello strumento usando il pulsante del selettore dello strumento all'inizio di questo articolo.

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

  • C# e C# Azure Functions
  • C
  • Python
  • Node.js
  • Java

Azure IoT Edge funziona con queste architetture di dispositivi:

  • 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 Visual Studio Code IoT Edge, è 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 Tutorial: 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 Visual Studio Code debug.

Prerequisiti

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

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

Installare Visual Studio Code.

Aggiungere queste estensioni:

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

  • Un IoT Hub attivo con almeno un dispositivo IoT Edge.
  • Un dispositivo fisico IoT Edge o un dispositivo virtuale. Creare un dispositivo virtuale in Azure seguendo la procedura descritta in quickstart per Linux.
  • Modulo di IoT Edge personalizzato. Per creare un modulo personalizzato, seguire la procedura descritta nell'esercitazione Develop Azure IoT Edge usando Visual Studio Code.

Eseguire il debug senza un contenitore usando il simulatore di 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 di IoT Edge per sviluppare e testare i moduli IoT Edge senza un dispositivo fisico o un runtime completo IoT Edge dispositivo.

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 Develop 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à di attacco usando il simulatore IoT Edge

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

Eseguire il debug di un modulo con il runtime di IoT Edge

Ogni cartella del modulo contiene diversi file Docker per diversi tipi di contenitore. Usare qualsiasi file che termina 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 Visual Studio Code possono essere eseguiti nello stesso computer, ma in genere Visual Studio Code viene eseguito nel computer di sviluppo mentre il runtime e i moduli IoT Edge vengono eseguiti in un altro computer fisico. Per eseguire il debug da Visual Studio Code:

  • Configurare il dispositivo IoT Edge, compilare i moduli IoT Edge con .debug Dockerfile e quindi distribuirlo 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 deployment descrive i moduli da configurare nel dispositivo IoT Edge di destinazione. Prima della distribuzione, aggiornare le credenziali di Azure Container Registry e le immagini del modulo con i valori createOptions appropriati. Per altre informazioni sui valori createOption, vedere Come configurare le opzioni di creazione del contenitore per i moduli IoT Edge.

  1. Se si usa un Azure Container Registry per archiviare l'immagine del modulo, aggiungere le credenziali alla edgeAgent>settings>registryCredentials sezione 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 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\"}]}}}"
}
  1. Nel riquadro comandi Visual Studio Code eseguire il comando Azure IoT Edge: Build and Push IoT Edge solution.
  2. Selezionare il file deployment.debug.template.json per la soluzione.
  3. Nella sezione Azure IoT Hub>Dispositivi della visualizzazione Visual Studio Code Explorer 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 verificare che il dispositivo scelto sia 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).

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

Importante

Se si usa un registro privato come Azure Container Registry 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 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 Azure Container Registry 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 sia una procedura consigliata per gli scenari di produzione, non rientra nell'ambito di questa esercitazione. Per ulteriori informazioni, vedere il riferimento docker login.

  2. Accedere al Azure Container Registry. Potrebbe essere necessario Installare Azure CLI 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 si è disconnessi in qualsiasi momento durante questa esercitazione, ripetere i passaggi di accesso a Docker e Azure Container Registry per continuare.

Compilare l’immagine Docker del modulo

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

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

Ad esempio, per compilare l'immagine per il registro locale o un Azure Container Registry, 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 IoT Edge Azure CLI set-modules per distribuire i moduli nel Azure IoT Hub. Ad esempio, per distribuire i moduli definiti nel file deployment.debug.template.json in IoT Hub 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 IoT Hub nel portale di Azure nel IoT Hub >Impostazioni di sicurezza>>iothubowner.

Eseguire il debug del modulo

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

Abilitare Visual Studio Code debug remoto installando l'estensione Remote Development. Per altre informazioni sul debug remoto di Visual Studio Code, vedere «Remote Development» di Visual Studio Code.

Per informazioni dettagliate sull'uso del debug SSH remoto in Visual Studio Code, vedere Remote Development using SSH.For details about using Remote SSH debugging in Visual Studio Code, see Remote Development using SSH.

Nella visualizzazione debug Visual Studio Code selezionare il file di configurazione di 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 F5 e quindi selezionare il processo a cui connettersi. Nella visualizzazione debug Visual Studio Code sono visualizzate le variabili nel pannello sinistro.

Eseguire il debug con SSH remoto Docker

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. È necessario soddisfare i prerequisiti seguenti per usare questa funzione.

I prerequisiti per il debug SSH remoto possono variare a seconda del linguaggio usato. Le sezioni seguenti descrivono la configurazione per .NET. Per informazioni su altri linguaggi, vedere Sviluppo remoto usando SSH per una panoramica. Le informazioni dettagliate su come configurare il debug remoto sono incluse 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 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 di 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, potrebbe essere necessario rimuovere l'utente dal gruppo Docker.

  3. In Visual Studio Code usare la Palette comandi (CTRL+MAIUSC+P) per eseguire il comando Docker Context: Use per attivare il contesto Docker che punta al computer remoto. Questo comando consente sia a Visual Studio Code che all'interfaccia della riga di comando di Docker di utilizzare 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 elenca i contenitori in esecuzione nel dispositivo remoto, come nel seguente esempio:

    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 aprire launch.json in Visual Studio Code e aggiungere una nuova configurazione. 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 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 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 Visual Studio Code sono visualizzate le variabili 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 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 un punto di interruzione.

Note

Nell'esempio precedente viene illustrato 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, scopri come distribuire i moduli di Azure IoT Edge.

Per sviluppare moduli per i dispositivi IoT Edge, vedere e usare Azure IoT Hub SDK.

  • Last updated on