Compartilhar via

Depurar módulos Azure IoT Edge usando Visual Studio Code

Aplica-se a:IoT Edge 1.5 checkmark IoT Edge 1.5

Importante

IoT Edge 1.5 LTS é a versão suportada. IoT Edge 1.4 LTS atingiu o fim da vida útil em 12 de novembro de 2024. Se você estiver usando uma versão anterior, consulte Update IoT Edge.

Este artigo explica como usar Visual Studio Code para depurar módulos IoT Edge em vários idiomas. No seu computador de desenvolvimento, use o Visual Studio Code para anexar e depurar seu módulo em um contêiner de módulo local ou remoto.

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

  • Azure IoT Edge Ferramenta de Desenvolvimento CLI (ferramenta de linha de comando). Essa ferramenta é preferencial para desenvolvimento.
  • Extensão de Azure IoT Edge Tools para Visual Studio Code A extensão está no modo de manutenção.

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

Visual Studio Code dá suporte à escrita de módulos IoT Edge nas seguintes linguagens de programação:

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

Azure IoT Edge funciona com essas arquiteturas de dispositivo:

  • AMD64
  • ARM32v7
  • ARM64

Para obter mais informações sobre sistemas operacionais, linguagens e arquiteturas com suporte, veja Suporte a linguagens e arquiteturas.

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

Você também pode usar um computador de desenvolvimento Windows e módulos de depuração em um contêiner do Linux usando IoT Edge para Linux no Windows (EFLOW). Para obter mais informações sobre como usar o EFLOW para desenvolver módulos, consulte Tutorial: Desenvolver módulos IoT Edge com contêineres do Linux usando IoT Edge para Linux no Windows.

Se você é novo nos recursos de depuração do Visual Studio Code, consulte depuração do Visual Studio Code.

Pré-requisitos

Você pode usar um computador ou uma máquina virtual executando Windows, macOS ou Linux como seu computador de desenvolvimento. Em computadores Windows, você pode desenvolver módulos Windows ou Linux. Para desenvolver módulos para Linux, use um computador Windows que atenda aos requisitos para Docker Desktop.

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

Instale Visual Studio Code.

Adicione estas extensões:

Para depurar seu módulo em um dispositivo, você precisará:

Depurar sem um contêiner usando o simulador de IoT Edge

O Simulador de IoT Edge é uma ferramenta que é executada em seu computador de desenvolvimento e simula o comportamento de um único dispositivo IoT Edge. Você pode usar o Simulador de IoT Edge para desenvolver e testar seus módulos de IoT Edge sem um dispositivo físico ou um runtime completo do dispositivo IoT Edge.

As etapas de depuração a seguir pressupõem que um módulo personalizado já foi criado. Se você ainda não criou um módulo personalizado, siga as etapas no tutorial Desenvolver módulos do Azure IoT Edge usando o Visual Studio Code.

A depuração de um módulo sem um contêiner não está disponível ao usar C ou Python.

Depurar no modo de anexação usando o simulador de IoT Edge

A depuração no modo de anexação 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 do 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 você depura módulos usando esse método, seus módulos são executados em cima do runtime IoT Edge. O dispositivo IoT Edge e o Visual Studio Code podem ser executados no mesmo computador, mas normalmente o Visual Studio Code é executado no computador de desenvolvimento, enquanto o runtime do IoT Edge e os módulos são executados em outro computador físico. Para depurar de Visual Studio Code:

  • Configure seu dispositivo IoT Edge, crie seus módulos de IoT Edge com o dockerfile .debug e implante no dispositivo IoT Edge.
  • Atualize launch.json para que o Visual Studio Code possa anexar-se ao processo em um contêiner no computador remoto. Encontre esse arquivo na pasta .vscode no espaço de trabalho, e ele atualiza sempre que você adiciona um novo módulo que dá suporte à depuração.
  • Use a depuração remota de SSH para fazer a anexação ao contêiner no computador remoto.

Compilar e implantar seu módulo em um dispositivo IoT Edge

Em Visual Studio Code, abra o arquivo de manifesto de implantação deployment.debug.template.json. O manifesto de implantação descreve os módulos a serem configurados no dispositivo de destino da IoT Edge. Antes da implantação, atualize suas credenciais de Azure Container Registry e imagens de módulo com os valores de createOptions adequados. Para obter mais informações sobre os valores de opções de criação, consulte Como configurar opções de criação de contêiner para módulos do IoT Edge.

  1. Se você estiver usando um Azure Container Registry para armazenar sua imagem de módulo, adicione suas credenciais à seção edgeAgent>settings>registryCredentials no deployment.debug.template.json. Substitua myacr pelo seu próprio nome de registro em ambos os lugares e forneça sua senha e endereço do Servidor de logon. 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 convertido em formato de string na propriedade createOptions para cada sistema (edgeHub e edgeAgent) e módulo personalizado (por exemplo, filtermodule) listado. Se necessário, mude os valores.

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

    Por exemplo a configuração filtermodule 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: Compilar e Enviar solução de IoT Edge.
  2. Selecione o deployment.debug.template.json arquivo para sua solução.
  3. Na seção Azure IoT Hub>Devices da exibição Visual Studio Code Explorer, clique com o botão direito do mouse no nome do dispositivo IoT Edge para implantação e escolha Criate Deployment for Single Device.

    Dica

    Para confirmar se o dispositivo escolhido é um dispositivo IoT Edge, selecione-o para expandir a lista de módulos e verificar a presença de $edgeHub e $edgeAgent. Cada dispositivo IoT Edge inclui esses dois módulos.

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

Verifique o status do contêiner em seu dispositivo ou máquina virtual executando o docker ps comando em um terminal. Você deverá visualizar o contêiner listado depois de executar o comando. Se o Visual Studio Code e o runtime IoT Edge estiverem rodando na mesma máquina, verifique o status na visualização Docker do Visual Studio Code.

Importante

Se você estiver usando um registro privado como Azure Container Registry para suas imagens, talvez seja necessário autenticar para enviar imagens por push. Use docker login <Azure Container Registry login server> ou az acr login --name <Azure Container Registry name> para autenticar.

Entrar no Docker

Forneça suas credenciais de registro de contêiner para o Docker para que ele possa efetuar push de sua imagem de contêiner para ser armazenada no registro.

  1. Entre no Docker com as credenciais de Azure Container Registry que você salvou após a criação do registro.

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

    Talvez você receba um aviso de segurança recomendando usar --password-stdin. Embora seja uma prática recomendada para cenários de produção, ela está fora do escopo deste tutorial. Para saber mais, confira a referência de logon do docker.

  2. Entre no Azure Container Registry. Talvez seja necessário Instalar Azure CLI para usar o comando az. Esse comando solicita o nome de usuário e a senha encontrados no registro de contêiner em Configurações>Chaves de acesso.

    az acr login -n <Azure Container Registry name>

Dica

Se você for desconectado em algum momento neste tutorial, repita as etapas de entrada do Docker e Azure Container Registry para continuar.

Criar imagem Docker do módulo

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

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

Por exemplo, para criar a imagem para o registro local ou 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"

Enviar por push a imagem do Docker do módulo

Efetue push da 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

Implantar 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 implantar os módulos definidos no arquivo deployment.debug.template.json no 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>"

Dica

Você pode encontrar sua chave de acesso compartilhado IoT Hub no portal Azure em suas >configurações de segurança>políticas de acesso compartilhado>iothubowner.

Depurar seu módulo

Para depurar módulos em um dispositivo remoto, use a depuração de SSH Remota em Visual Studio Code.

Para habilitar a depuração remota no Visual Studio Code, instale a extensão Remote Development. Para obter mais informações sobre depuração remota do Visual Studio Code, consulte Visual Studio Code Remote Development.

Para obter detalhes sobre como usar a depuração remota com SSH no Visual Studio Code, consulte Remote Development using SSH.

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

Selecione Iniciar Depuração ou F5 e selecione o processo ao qual anexar. Na exibição de Depuração do Visual Studio Code, você verá variáveis no painel esquerdo.

Depurar usando o SSH remoto do Docker

Os mecanismos Docker e Moby dão suporte a conexões SSH a contêineres, permitindo que você depure em Visual Studio Code conectado a um dispositivo remoto. Você precisa atender aos pré-requisitos a seguir para poder usar esse recurso.

Os pré-requisitos de depuração de SSH remoto podem ser diferentes dependendo do idioma usado. As seções a seguir descrevem a configuração para .NET. Para obter informações sobre outras linguagens, consulte Desenvolvimento Remoto com o SSH, para obter uma visão geral. Detalhes sobre como configurar a depuração remota são incluídos nas seções de depuração para cada idioma na documentação do Visual Studio Code.

Configurar tunelamento SSH do Docker

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

  2. Conectar-se ao Docker requer privilégios de root. Siga as etapas em Gerenciar o Docker como usuário não raiz para permitir a conexão com o daemon do Docker no dispositivo remoto. Ao concluir a depuração, talvez você queira remover o usuário do grupo do 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 do Docker apontando para o computador remoto. Esse comando permite que Visual Studio Code e a CLI do Docker usem o contexto do computador remoto.

    Dica

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

  4. Para verificar se o contexto remoto do Docker 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 ao 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 no Visual Studio Code e adicione uma nova configuração. Selecione Adicionar configuração e escolha o modelo de anexação remota correspondente para o módulo. Por exemplo, a configuração a seguir é para .NET Core. Altere o valor do parâmetro -H em PipeArgs para o nome DNS ou o 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 o módulo remotamente

  1. No modo de exibição de depuração Visual Studio Code, selecione a configuração de depuração Emote Debug IoT Edge Module (.NET Core).

  2. Selecione Iniciar Depuração ou selecione F5. Selecione o processo ao qual ele deverá ser anexado.

  3. No modo de Depuração do Visual Studio Code, você verá as variáveis no painel esquerdo.

  4. Em Visual Studio Code, defina pontos de interrupção em seu módulo personalizado.

  5. Quando um ponto de interrupção é atingido, você pode inspecionar variáveis, percorrer o código e depurar o seu módulo.

    Captura de tela do Visual Studio Code anexado a um contêiner do Docker em um dispositivo remoto pausado em um ponto de interrupção.

Observação

O exemplo anterior mostra como depurar módulos IoT Edge em contêineres remotos. O exemplo adiciona um contexto remoto do Docker e alterações nos 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.

Confira esta entrada no blog do Desenvolvedor de IoT para ver um exemplo que usa um dispositivo Raspberry Pi.

Próximas etapas

Depois de construir o módulo, saiba como implantar os módulos do Azure IoT Edge.

Para desenvolver módulos para seus dispositivos IoT Edge, saiba mais e use Azure IoT Hub SDKs.

  • Last updated on