Depurar módulos do Azure IoT Edge usando o Visual Studio Code

  • Artigo

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

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS são versões suportadas. O IoT Edge 1.4 LTS termina a vida útil em 12 de novembro de 2024. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

Este artigo mostra como usar o Visual Studio Code para depurar módulos do IoT Edge em vários idiomas. Em seu computador de desenvolvimento, você pode usar 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 do IoT Edge.

  • Ferramenta de linha de comando (CLI) da Ferramenta de Desenvolvimento do Azure IoT Edge. Esta ferramenta é preferida para o desenvolvimento.
  • Ferramentas do Azure IoT Edge para extensão de código do Visual Studio. A extensão está em 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 oferece suporte à gravação de módulos do IoT Edge nas seguintes linguagens de programação:

  • Funções do Azure em C# e C#
  • C
  • Python
  • Node.js
  • Java

O Azure IoT Edge suporta as seguintes arquiteturas de dispositivo:

  • AMD64
  • ARM32v7
  • ARM64

Para obter mais informações sobre sistemas operacionais, idiomas e arquiteturas suportados, consulte Suporte a linguagem e arquitetura.

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

Você também pode usar um computador de desenvolvimento Windows e depurar módulos em um contêiner Linux usando o 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 do IoT Edge com contêineres do Linux usando o IoT Edge para Linux no Windows.

Se você não estiver familiarizado com os recursos de depuração do Visual Studio Code, consulte Depuração de código do Visual Studio.

Pré-requisitos

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

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

Instalar o Visual Studio Code

Adicione as seguintes extensões:

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

  • Um Hub IoT ativo com pelo menos um dispositivo IoT Edge.
  • Um dispositivo IoT Edge físico ou um dispositivo virtual. Para criar um dispositivo virtual no Azure, siga as etapas no início rápido para Linux.
  • Um módulo IoT Edge personalizado. Para criar um módulo personalizado, siga as etapas no tutorial Desenvolver módulos do Azure IoT Edge usando o Visual Studio Code .

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

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

As etapas de depuração a seguir pressupõem que você já tenha criado um módulo personalizado. Se você 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 do IoT Edge

A depuração no modo de anexação não é suportada para C ou Python.

Depurar um módulo com o tempo de execução 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 criar seu módulo para teste.

Quando você depura módulos usando esse método, seus módulos são executados sobre o tempo de execução do IoT Edge. O dispositivo IoT Edge e seu Visual Studio Code podem estar na mesma máquina ou, mais tipicamente, o Visual Studio Code está na máquina de desenvolvimento e o tempo de execução e os módulos do IoT Edge estão sendo executados em outra máquina física. Para depurar do Visual Studio Code, você deve:

  • Configure seu dispositivo IoT Edge, crie seus módulos IoT Edge com o Dockerfile .debug e implante no dispositivo IoT Edge.
  • Atualize launch.json para que o Visual Studio Code possa anexar ao processo em um contêiner 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.
  • Use a depuração SSH remota para anexar ao contêiner na máquina remota.

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

  1. Se você estiver usando um Registro de Contêiner do Azure para armazenar a imagem do módulo, adicione suas credenciais à seção edgeAgent>settings>registryCredentials no 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 stringified ao 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: Build and Push IoT Edge solution.
  2. Selecione o deployment.debug.template.json arquivo para sua solução.
  3. Na seção Dispositivos do Hub IoT do Azure do modo de exibição Explorador>de Código do Visual Studio, 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.

    Gorjeta

    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. Todos os dispositivos IoT Edge incluem esses dois módulos.

  4. Navegue até a pasta de configuração da solução, selecione o arquivo e selecione Selecionar manifesto deployment.debug.amd64.jsonde implantação de borda.

Você pode verificar 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 tempo de execução do IoT Edge estiverem sendo executados na mesma máquina, você também poderá verificar o status no modo de exibição Visual Studio Code Docker.

Importante

Se você estiver usando um registro privado como o 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.

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. Entre no Docker com as credenciais do Registro de Contêiner do Azure que você salvou depois de criar o Registro.

    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 essa 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 de login do docker.

  2. Entre no Registro de Contêiner do Azure. Talvez seja necessário instalar a CLI do Azure para usar o az comando. Este comando solicita o seu nome de utilizador e palavra-passe encontrados no registo do contentor em Definições>de chaves de acesso.

    az acr login -n <Azure Container Registry name>

Gorjeta

Se você sair em qualquer momento deste tutorial, repita as etapas de entrada do Docker e do Registro de Contêiner do Azure para continuar.

Imagem do Docker do módulo de compilação

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 para o registro local ou 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"

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

Implantar 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 para o dispositivo my-device do IoT Edge, 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

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

Depurar seu módulo

Para depurar módulos em um dispositivo remoto, você pode usar 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 depuração remota do Visual Studio Code, consulte Visual Studio Code Remote Development.

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

Na visualização Visual Studio Code Debug, selecione o arquivo de configuração de depuração para seu 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 selecione F5. Selecione o processo ao qual anexar. No modo de exibição Depuração de código do Visual Studio, você vê variáveis no painel esquerdo.

Depurar usando o SSH remoto do Docker

Os mecanismos Docker e Moby oferecem suporte a conexões SSH para contêineres, permitindo que você depure no Visual Studio Code conectado 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 ser diferentes, dependendo do idioma que você está usando. As seções a seguir descrevem a instalação do .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 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 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 nível raiz. 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 usuário do grupo Docker.

  3. No 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 a máquina remota. Esse comando faz com que o Visual Studio Code e a CLI do Docker usem o contexto da máquina remota.

    Gorjeta

    Todos os comandos do Docker usam o contexto atual. Lembre-se de alterar o contexto de volta para o 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 deve listar os contêineres em execução no dispositivo remoto semelhante:

    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 ao launch.json abrindo o arquivo no Visual Studio Code. Selecione Adicionar configuração e, em seguida, escolha o modelo de conexão remota correspondente para o seu 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 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. No modo de exibição de depuração de código do Visual Studio, selecione a configuração de depuração Remote Debug IoT Edge Module (.NET Core).

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

  3. No modo de exibição Depuração de código do Visual Studio, você vê as variáveis no painel esquerdo.

  4. No 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 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.

Nota

O exemplo anterior mostra como depurar módulos do IoT Edge em contêineres 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 criar seu módulo, saiba como implantar módulos do Azure IoT Edge.

Para desenvolver módulos para seus dispositivos IoT Edge, entenda e use os SDKs do Hub IoT do Azure.