Compartilhar via

Depurar módulos do Azure IoT Edge por meio do Visual Studio Code

  • Artigo

Aplica-se a: Marca de seleção do IoT Edge 1.5 IoT Edge 1.5 marca de seleção do IoT Edge 1.4 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Este artigo mostra como usar o Visual Studio Code para depurar módulos do IoT Edge em várias linguagens. No computador de desenvolvimento, você pode usar o Visual Studio Code para anexar e depurar o módulo em um contêiner de módulo local ou remoto.

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

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

Use o botão seletor de ferramentas no início deste artigo para selecionar a versão da ferramenta.

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

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

O Azure IoT Edge dá suporte às seguintes 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 IoT Edge do Visual Studio Code, você também pode iniciar e depurar o código do módulo no Simulador do IoT Edge.

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

Se você não estiver familiarizado com as funcionalidades de depuração do Visual Studio Code, confira Depuração no Visual Studio Code.

Pré-requisitos

É possível usar um computador ou uma máquina virtual que execute Windows, macOS ou Linux como o computador de desenvolvimento. Em computadores Windows, você pode desenvolver módulos do Windows ou do Linux. Para desenvolver módulos do Linux, use um computador Windows que atenda aos requisitos da Área de Trabalho do Docker.

Para instalar as ferramentas necessárias para desenvolvimento e depuração, conclua o tutorial Desenvolver módulos do Azure IoT Edge com o tutorial do Visual Studio Code.

Instalar o Visual Studio Code

Adicione as seguintes extensões:

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

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

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

As etapas de depuração a seguir pressupõem que um módulo personalizado já foi criado. Se ainda não criou um módulo personalizado, siga as etapas no tutorial Desenvolver módulos do Azure IoT Edge com o tutorial do 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 com o simulador do IoT Edge

Não há suporte para depuração no modo de anexação para C ou Python.

Depurar um módulo com o runtime do IoT Edge

Em cada pasta de módulo, há vários arquivos do Docker para diferentes tipos de contêiner. Use qualquer um dos arquivos que terminam com a extensão .debug para compilar o módulo para teste.

Durante a depuração de módulos usando esse método, os módulos são executados com base no runtime do IoT Edge. O dispositivo IoT Edge e o Visual Studio Code podem estar no mesmo computador ou, mais comumente, o Visual Studio Code está no computador de desenvolvimento e o runtime do IoT Edge e os módulos estão em execução em outro computador físico. Para depurar no Visual Studio Code, você deverá:

  • Configurar o dispositivo IoT Edge, compilar os módulos do IoT Edge com o Dockerfile .debug e depois implantar o dispositivo IoT Edge.
  • Atualizar o launch.json para que o Visual Studio Code possa se anexar 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 o módulo no dispositivo IoT Edge

No 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 do IoT Edge de destino. Antes da implantação, você precisa atualizar as credenciais do Registro de Contêiner do Azure e as imagens de módulo com os valores de createOptions adequados. Para obter mais informações sobre os valores de createOption, confira Como configurar opções de criação de contêiner para módulos do IoT Edge.

  1. Se você estiver usando um Registro de Contêiner do Azure para armazenar sua imagem de módulo, adicione suas credenciais à seção edgeAgent>configurações>registryCredentials em 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 com cadeia de caracteres ao valor 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: Build and Push IoT Edge solution.
  2. Selecione o deployment.debug.template.json arquivo para sua solução.
  3. Na seção Dispositivos> Hub IoT do Azure da exibição Gerenciador do Visual Studio Code, clique com o botão direito do mouse no nome do dispositivo IoT Edge para implantação e escolha Criar Implantação para Dispositivo Único.

    Dica

    Para confirmar que o dispositivo que você 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 esses dois módulos.

  4. Navegue até a pasta da sua solução config, selecione o arquivo deployment.debug.amd64.json e, em seguida, selecione Selecionar o manifesto de implantação de borda.

Verifique o status do contêiner no dispositivo ou máquina virtual executando o comando docker ps em um terminal. Você deverá visualizar o contêiner listado depois de executar o comando. Se o runtime do IoT Edge e Visual Studio Code estiver em execução no mesmo computador, você também poderá verificar o status na exibição do Docker do Visual Studio Code.

Importante

Caso esteja usando um registro privado como Registro de Contêiner do Azure 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 do Registro de Contêiner do Azure que você salvou após criar o 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 essa melhor prática seja recomendada para cenários de produção, ela não serve para este tutorial. Para saber mais, confira a referência de logon do docker.

  2. Entre no Registro de Contêiner do Azure. Talvez seja necessário instalar a CLI do Azure 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ê fizer logon em qualquer momento nesse tutorial, repita as etapas acima de entrada do Docker e do Registro de Contêiner do Azure para continuar.

Criar imagem do Docker do módulo

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

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

Por exemplo, para criar a imagem do registro local ou de um Registro de Contêiner do Azure, 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

Implante o módulo no dispositivo IoT Edge

Use o comando IoT Edge Azure CLI set-modules para implantar os módulos no Hub IoT do Azure. Por exemplo, para implantar os módulos definidos no arquivo deployment.debug.template.json no Hub IoT my-iot-hub do dispositivo do 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

Encontre a chave de acesso compartilhada do Hub IoT no portal do Azure em >Configurações de segurança>Políticas de acesso compartilhado>iothubowner do Hub IoT.

Depurar seu aplicativo

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

Para habilitar a depuração remota do Visual Studio Code, instale a extensão de Desenvolvimento Remoto. Para obter mais informações sobre a depuração remota do Visual Studio Code, consulte Desenvolvimento Remoto do Visual Studio Code.

Para obter detalhes de como usar a depuração SSH remota no Visual Studio Code, confira Desenvolvimento remoto usando SSH

Na exibição Depuração do Visual Studio Code e selecione o arquivo de configuração de depuração para o seu 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 selecione F5. Selecione o processo ao qual ele deverá ser anexado. Na exibição de Depuração do Visual Studio Code, você visualizará as variáveis no painel esquerdo.

Depurar usando o SSH remoto do Docker

Os mecanismos do Docker e do Moby dão suporte a conexões SSH com contêineres, permitindo a depuração no 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 linguagem que você está usando. 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 o túnel SSH do Docker

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

  2. A conexão ao Docker requer privilégios de nível raiz. 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 terminar a depuração, você poderá remover o usuário do grupo do Docker.

  3. No Visual Studio Code, use a Paleta de Comandos (Ctrl+Shift+P) para emitir o comando Docker Context: Use a fim de ativar o contexto do Docker apontando para o computador remoto. Este comando faz com que o 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 deve listar os contêineres em execução no dispositivo remoto semelhante a:

    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, adicione uma nova configuração para launch.json abrindo o arquivo no Visual Studio Code. Selecione Adicionar configuração e escolha o modelo de anexação remota correspondente do módulo. Por exemplo, a configuração a seguir é para o .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. Na exibição Depuração do Visual Studio Code, selecione a configuração Depuração remota do módulo do IoT Edge (.NET Core).

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

  3. Na exibição de Depuração do Visual Studio Code, visualize as variáveis no painel esquerdo.

  4. No Visual Studio Code, defina pontos de interrupção no 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 os módulos do 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

Após compilar o módulo, saiba como implantar módulos do Azure IoT Edge.

Para desenvolver módulos para seus dispositivos do IoT Edge, consulte entender e usar os SDKs de Hub IoT do Azure.