Partilhar via

Debug Azure IoT Edge modules using Visual Studio Code

Aplica-se a:IoT Edge 1.5 IoT Edge 1.5

Importante

IoT Edge 1.5 LTS é a versão suportada. O IoT Edge 1.4 LTS atingiu o fim de vida útil a 12 de novembro de 2024. Se estiveres a usar uma versão anterior, vê Update IoT Edge.

Este artigo explica como usar o Visual Studio Code para depurar módulos IoT Edge em várias línguas. No seu computador de desenvolvimento, use o Visual Studio Code para anexar e depurar o seu módulo num contentor local ou remoto.

Este artigo inclui passos para duas ferramentas de desenvolvimento IoT Edge.

  • Ferramenta de Linha de Comandos Azure IoT Edge Dev Tool (CLI). Esta ferramenta é preferida para o desenvolvimento.
  • Extensão de Ferramentas Azure IoT Edge para Visual Studio Code. A extensão está em modo de manutenção.

Selecione a versão da ferramenta usando o botão seletor de ferramentas no início deste artigo.

O Visual Studio Code suporta a escrita de módulos IoT Edge nas seguintes linguagens de programação:

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

O Azure IoT Edge funciona com as seguintes arquiteturas de dispositivos:

  • AMD64
  • ARM32v7
  • ARM64

Para obter mais informações sobre sistemas operativos, idiomas e arquiteturas suportados, veja Suporte de linguagem e arquitetura.

Ao usar a extensão Visual Studio Code IoT Edge, também pode iniciar e depurar o código do seu módulo no IoT Edge Simulator.

Também pode usar um computador de desenvolvimento Windows e depurar módulos num contentor Linux usando IoT Edge for Linux no Windows (EFLOW). Para mais informações sobre o uso do EFLOW para desenvolver módulos, consulte Tutorial: Desenvolver módulos IoT Edge com contentores Linux usando IoT Edge para Linux no Windows.

Se é novo nas funcionalidades de depuração do Visual Studio Code, veja depuração do Visual Studio Code.

Pré-requisitos

Pode usar um computador ou uma máquina virtual a correr Windows, macOS ou Linux como máquina de desenvolvimento. Em computadores Windows, pode desenvolver módulos Windows ou Linux. Para desenvolver módulos Linux, utilize um computador Windows que cumpra os requisitos para o Docker Desktop.

Para instalar as ferramentas necessárias para desenvolvimento e depuração, complete o tutorial Develop Azure IoT Edge usando Visual Studio Code.

Instala Visual Studio Code.

Adicione estas extensões:

Para depurar o seu módulo num dispositivo, você precisará:

Depure sem um contentor utilizando o simulador do IoT Edge

O IoT Edge Simulator é uma ferramenta que corre no seu computador de desenvolvimento e simula o comportamento de um único dispositivo IoT Edge. Pode usar o IoT Edge Simulator para desenvolver e testar os seus módulos IoT Edge sem um dispositivo físico ou um tempo de execução completo de um dispositivo IoT Edge.

As etapas de depuração a seguir pressupõem que você já tenha criado um módulo personalizado. Se ainda não criaste um módulo personalizado, segue os passos no tutorial Desenvolver Azure IoT Edge módulos usando Visual Studio Code.

Depurar um módulo sem contentor não está disponível ao usar C ou Python.

Depurar em modo anexado usando o simulador IoT Edge

A depuração em modo attachment não está disponível para C ou Python.

Depurar um módulo com o runtime do IoT Edge

Cada pasta de módulo contém vários arquivos Docker para diferentes tipos de contêiner. Use qualquer arquivo que termine com a extensão .debug para criar seu módulo para teste.

Quando depura módulos com este método, os seus módulos estão a correr sobre o runtime do IoT Edge. O dispositivo IoT Edge e o Visual Studio Code podem correr na mesma máquina, mas normalmente, o Visual Studio Code corre na máquina de desenvolvimento enquanto o runtime e os módulos do IoT Edge correm noutra máquina física. Para depurar a partir do Visual Studio Code:

  • Configura o teu dispositivo IoT Edge, constrói os teus módulos de IoT Edge com o Dockerfile .debug e depois implementa no dispositivo IoT Edge.
  • Atualize launch.json para que Visual Studio Code possa ligar ao processo num contentor na máquina remota. Você pode encontrar esse arquivo na .vscode pasta em seu espaço de trabalho e ele é atualizado sempre que você adiciona um novo módulo que suporta depuração.
  • Utilize a depuração remota via SSH para ligar-se ao contentor na máquina remota.

Construa e implemente o seu módulo num dispositivo IoT Edge

No Visual Studio Code, abra o ficheiro de manifestos de implementação deployment.debug.template.json. O manifesto de implementação descreve os módulos a configurar no dispositivo IoT Edge destinado. Antes da implementação, atualize as suas credenciais de Azure Container Registry e as imagens dos módulos com os valores corretos de createOptions. Para mais informações sobre os valores createOption, veja Como configurar opções de criação de contentores para módulos IoT Edge.

  1. Se estiver a usar um Azure Container Registry para armazenar a imagem do seu módulo, adicione as suas credenciais à secção edgeAgent>settings>registryCredentials na secção deployment.debug.template.json. Substitua myacr pelo seu próprio nome de registo em ambos os locais e forneça a sua palavra-passe e endereço do servidor de início de sessão. Por exemplo:

    "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. Adicione ou substitua o seguinte conteúdo no formato de string no valor createOptions para cada sistema (edgeHub e edgeAgent) e módulo personalizado (por exemplo, filtermodule) listado. Altere os valores, se necessário.

    "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

    Por exemplo, a configuração do módulo de filtro deve ser semelhante 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. Na paleta de comandos do Visual Studio Code, execute o comando Azure IoT Edge: Criar e Enviar solução IoT Edge.
  2. Selecione o deployment.debug.template.json arquivo para sua solução.
  3. Na secção Azure IoT Hub>Dispositivos da vista do Explorador do Visual Studio Code, clique com o botão direito no nome do dispositivo IoT Edge para a implantação e depois escolha Criar Implantação para Dispositivo Único.

    Gorjeta

    Para confirmar que o dispositivo que escolheu é um dispositivo IoT Edge, selecione-o para expandir a lista de módulos e verificar a presença de $edgeHub e $edgeAgent. Todos os dispositivos IoT Edge incluem estes dois módulos.

  4. Navegue até a pasta config da sua solução, selecione o ficheiro deployment.debug.amd64.json, e de seguida selecione Selecionar Manifesto de Implementação de Edge.

Verifique o status do contêiner a partir do seu dispositivo ou máquina virtual executando o docker ps comando em um terminal. Você deve ver seu contêiner listado depois de executar o comando. Se o Visual Studio Code e o runtime IoT Edge correrem na mesma máquina, verifique o estado na vista Docker do Visual Studio Code.

Importante

Se estiver a usar um registo privado como o Azure Container Registry para as suas imagens, pode ser necessário autenticar para enviar imagens. Use docker login <Azure Container Registry login server> ou az acr login --name <Azure Container Registry name> para autenticar.

Faça login no Docker

Forneça suas credenciais de registro de contêiner ao Docker para que ele possa enviar sua imagem de contêiner para armazenamento no registro.

  1. Inicie sessão no Docker com as credenciais do Azure Container Registry que guardou após criar o registo.

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

    Poderá receber um aviso de segurança a recomendar a utilização do --password-stdin. Embora seja uma prática recomendada para cenários de produção, está fora do escopo deste tutorial. Para obter mais informações, consulte a referência docker login.

  2. Iniciar sessão no Azure Container Registry. Pode ser necessário Install Azure CLI para usar o comando az. Este comando solicita o seu nome de utilizador e palavra-passe encontrados no registo de contentores em Definições>Chaves de acesso.

    az acr login -n <Azure Container Registry name>

Gorjeta

Se, em algum momento deste tutorial, for desconectado, repita os passos de login do Docker e do Azure Container Registry para continuar.

Imagem Docker do módulo de construção

Use o Dockerfile do módulo para criar a imagem do Docker.

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

Por exemplo, para construir a imagem para o registo local ou para um Azure Container Registry, use os seguintes comandos:

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

Imagem do Docker do módulo Push

Envie a imagem do módulo para o registro local ou para um registro de contêiner.

docker push <ImageName>

Por exemplo:

# 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

Implante o módulo no dispositivo IoT Edge

Use o comando IoT Edge Azure CLI set-modules para implantar os módulos no Azure IoT Hub. Por exemplo, para implementar os módulos definidos no ficheiro deployment.debug.template.json para IoT Hub my-iot-hub para o dispositivo IoT Edge my-device, use o seguinte comando:

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

Gorjeta

Pode encontrar a sua chave de acesso partilhada IoT Hub no portal Azure no seu IoT Hub >Definições de segurança>Políticas de acesso partilhado>iothubowner.

Depurar seu módulo

Para depurar módulos num dispositivo remoto, utilize a funcionalidade de depuração SSH remota no Visual Studio Code.

Habilite o debugging remoto no Visual Studio Code instalando a extensão Remote Development. Para mais informações sobre a depuração remota do Visual Studio Code, veja Visual Studio Code Desenvolvimento Remoto.

Para detalhes sobre o uso da depuração remota de SSH em Visual Studio Code, veja Desenvolvimento Remoto usando SSH.

Na vista Debug do Visual Studio Code, selecione o ficheiro de configuração de debug para o módulo. Por padrão, o Dockerfile .debug , as configurações de contêiner createOptions do módulo e o launch.json arquivo usam localhost.

Selecione Iniciar Depuração ou F5 e, em seguida, selecione o processo ao qual anexar. Na vista de depuração do Visual Studio Code, vês variáveis no painel esquerdo.

Depurar usando SSH remoto do Docker

Os motores Docker e Moby suportam conexões SSH a containers, permitindo que depure usando o Visual Studio Code ligado a um dispositivo remoto. Você precisa atender aos seguintes pré-requisitos antes de poder usar esse recurso.

Os pré-requisitos de depuração SSH remota podem diferir dependendo do idioma usado. As secções seguintes descrevem a configuração para .NET. Para obter informações sobre outros idiomas, consulte Desenvolvimento remoto usando SSH para obter uma visão geral. Detalhes sobre como configurar a depuração remota estão incluídos nas secções de depuração para cada linguagem na documentação do Visual Studio Code.

Configurar o túnel SSH do Docker

  1. Siga as etapas em Túnel SSH do Docker para configurar o túnel SSH em seu computador de desenvolvimento. O túnel SSH requer autenticação de par de chaves pública/privada e um contexto do Docker que define o ponto de extremidade do dispositivo remoto.

  2. A conexão com o Docker requer privilégios de root. Siga as etapas em Gerenciar docker como um usuário não-root para permitir a conexão com o daemon do Docker no dispositivo remoto. Quando terminar a depuração, convém remover o utilizador do grupo Docker.

  3. Em Visual Studio Code, use a Paleta de Comandos (Ctrl+Shift+P) para emitir o comando Docker Context: Use para ativar o contexto Docker que aponta para a máquina remota. Este comando permite que tanto o Visual Studio Code como o Docker CLI usem o contexto remoto da máquina.

    Gorjeta

    Todos os comandos do Docker usam o contexto atual. Lembre-se de alterar o contexto de volta para padrão quando terminar a depuração.

  4. Para verificar se o contexto do Docker remoto está ativo, liste os contêineres em execução no dispositivo remoto:

    docker ps

    A saída lista os contêineres em execução no dispositivo remoto, semelhante à seguinte:

    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. No diretório .vscode, abra launch.json em Visual Studio Code e adicione uma nova configuração. Selecione Adicionar configuração e, em seguida, escolha o modelo de conexão remota correspondente para o módulo. Por exemplo, a seguinte configuração é para .NET Core. Altere o valor do parâmetro -H em PipeArgs para o nome DNS ou endereço IP do 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
},

Depurar remotamente o módulo

  1. Na vista de Depuração do Visual Studio Code, selecione a configuração de depuração Módulo de Depuração Remota IoT Edge (.NET Core).

  2. Selecione Iniciar depuração ou selecione F5. Selecione o processo ao qual anexar.

  3. Na vista Debug do Visual Studio Code, vês as variáveis no painel esquerdo.

  4. No Visual Studio Code, define pontos de interrupção no teu módulo personalizado.

  5. Quando um ponto de interrupção é atingido, pode inspecionar variáveis, avançar através do código e depurar o módulo.

    Captura de ecrã de Visual Studio Code anexada a um contentor Docker num dispositivo remoto pausada num ponto de interrupção.

Nota

O exemplo anterior mostra como depurar módulos IoT Edge em contentores remotos. O exemplo adiciona um contexto remoto do Docker e altera os privilégios do Docker no dispositivo remoto. Depois de concluir a depuração dos módulos, defina o contexto do Docker como padrão e remova os privilégios da sua conta de usuário.

Consulte esta entrada de blog do IoT Developer para obter um exemplo usando um dispositivo Raspberry Pi.

Próximos passos

Depois de construíres o teu módulo, aprende a desenvolver módulos Azure IoT Edge.

Para desenvolver módulos para os seus dispositivos IoT Edge, aprenda sobre e use o Azure IoT Hub SDKs.

  • Last updated on