Compartir a través de

Depurar módulos Azure IoT Edge mediante Visual Studio Code

Se aplica a:Marca de verificación de IoT Edge 1.5 IoT Edge 1.5

Importante

IoT Edge 1.5 LTS es la versión compatible. IoT Edge 1.4 LTS finaliza su ciclo de vida el 12 de noviembre de 2024. Si está usando una versión anterior, consulte Actualización de IoT Edge.

En este artículo se explica cómo usar Visual Studio Code para depurar módulos de IoT Edge en varios lenguajes. En el equipo de desarrollo, use Visual Studio Code para adjuntar y depurar el módulo en un contenedor de módulos local o remoto.

En este artículo se incluyen los pasos para dos herramientas de desarrollo de IoT Edge.

  • Herramienta de línea de comandos (CLI) de herramienta de desarrollo de Azure IoT Edge. Para el desarrollo se prefiere esta herramienta.
  • Extensión de Herramientas de Azure IoT Edge para Visual Studio Code. La extensión está en modo de mantenimiento.

Seleccione la versión de la herramienta con el botón selector de herramientas al principio de este artículo.

Visual Studio Code admite la escritura de módulos de IoT Edge en los siguientes lenguajes de programación:

  • C# y Azure Functions
  • C
  • Pitón
  • Node.js.
  • Java

Azure IoT Edge funciona con estas arquitecturas de dispositivo:

  • AMD64
  • ARM32v7
  • ARM64

Para obtener más información sobre los sistemas operativos, los lenguajes y las arquitecturas compatibles, consulte Compatibilidad de lenguaje y arquitectura.

Al usar la extensión IoT Edge de Visual Studio Code, también puede iniciar y depurar el código del módulo en el simulador de IoT Edge.

También puede usar un equipo de desarrollo de Windows y depurar módulos en un contenedor de Linux mediante IoT Edge para Linux en Windows (EFLOW). Para más información sobre el uso de EFLOW para el desarrollo de módulos, consulte Tutorial: Desarrollo de módulos de IoT Edge con contenedores de Linux mediante IoT Edge para Linux en Windows.

Si no está familiarizado con las funcionalidades de depuración de Visual Studio Code, consulte Depuración de Visual Studio Code.

Requisitos previos

Puede usar un equipo o máquina virtual con Windows, macOS o Linux como equipo de desarrollo. En equipos Windows, puede desarrollar módulos de Windows o Linux. Para desarrollar módulos de Linux, use un equipo Windows que cumpla los requisitos de Docker Desktop.

Para instalar las herramientas necesarias para el desarrollo y la depuración, complete el tutorial Desarrollo de módulos de Azure IoT Edge mediante Visual Studio Code.

Instale Visual Studio Code.

Agregue estas extensiones:

Para depurar el módulo en un dispositivo, necesita:

Depuración sin un contenedor mediante el simulador de IoT Edge

El simulador de IoT Edge es una herramienta que se ejecuta en el equipo de desarrollo y simula el comportamiento de un único dispositivo IoT Edge. Puede usar el simulador de IoT Edge para desarrollar y probar los módulos de IoT Edge sin un dispositivo físico o un entorno de ejecución de dispositivo IoT Edge completo.

En los pasos de depuración siguientes se asume que ya ha creado un módulo personalizado. Si no ha creado un módulo personalizado, siga los pasos descritos en el tutorial Desarrollo de módulos de Azure IoT Edge mediante Visual Studio Code.

La depuración de un módulo sin un contenedor no está disponible cuando se usa C o Python.

Depuración en modo de asociación con el simulador de IoT Edge

La depuración en modo adjunto no está disponible para C o Python.

Depuración de un módulo con el entorno de tiempo de ejecución de IoT Edge

Cada carpeta de módulo contiene varios archivos de Docker para distintos tipos de contenedor. Use cualquier archivo que termine con la extensión .debug para compilar el módulo para realizar pruebas.

Al depurar los módulos con este método, estos se ejecutan sobre el entorno de ejecución de IoT Edge. El dispositivo IoT Edge y Visual Studio Code se pueden ejecutar en la misma máquina, pero normalmente, Visual Studio Code se ejecuta en la máquina de desarrollo mientras el entorno de ejecución y los módulos de IoT Edge se ejecutan en otra máquina física. Para depurar desde Visual Studio Code:

  • Configurar el dispositivo de IoT Edge, compilar los módulos de IoT Edge con el archivo Dockerfile .debug y, después, implementarlos en el dispositivo de IoT Edge.
  • Actualizar el archivo launch.json para que Visual Studio Code pueda adjuntarse al proceso del contenedor en el equipo remoto. Puede encontrar este archivo en la carpeta .vscode del área de trabajo y se actualiza cada vez que agrega un nuevo módulo que admite la depuración.
  • Use la depuración de SSH remota para conectarse al contenedor en la máquina remota.

Compilación e implementación del módulo en un dispositivo de IoT Edge

En Visual Studio Code, abra el archivo de manifiesto deployment.debug.template.json. El manifiesto de implementación describe los módulos que se van a configurar en los dispositivos IoT Edge de destino. Antes de la implementación, actualice las credenciales y las imágenes del módulo de Azure Container Registry con los valores adecuados createOptions . Para más información sobre los valores de createOption, consulte Configuración de las opciones de creación de contenedores para módulos de IoT Edge.

  1. Si usa un Azure Container Registry para almacenar la imagen del módulo, agregue sus credenciales a la sección edgeAgent>configuración>registryCredentials en deployment.debug.template.json. Reemplace myacr por su propio nombre del registro en ambos lugares y proporcione la contraseña y la dirección del servidor de inicio de sesión. Por ejemplo:

    "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. Agregue o reemplace el siguiente contenido con cadenas para el valor createOptions en cada sistema (edgeHub y edgeAgent) y módulo personalizado (por ejemplo: filtermodule) que aparece enumerado. Cambie los valores si es necesario.

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

    Por ejemplo, la configuración filtermodule debería ser similar 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. En la paleta de comandos de Visual Studio, ejecute el comando Azure IoT Edge: Build and Push IoT Edge solution.
  2. Seleccione el archivo deployment.debug.template.json para su solución.
  3. En la sección Azure IoT Hub>Dispositivos de la vista Explorador de Visual Studio Code, haga clic con el botón derecho en el nombre del dispositivo de IoT Edge para la implementación y, luego, elija Crear implementación para un único dispositivo.

    Sugerencia

    Para confirmar que el dispositivo que ha elegido es un dispositivo IoT Edge, selecciónelo para expandir la lista de módulos y comprobar la presencia de $edgeHub y $edgeAgent. Todos los dispositivos IoT Edge incluyen estos dos módulos.

  4. Vaya a la carpeta config de la solución, seleccione el archivo deployment.debug.amd64.json y haga clic en Select Edge Deployment Manifest (Seleccionar manifiesto de implementación de Edge).

Compruebe el estado del contenedor desde el dispositivo o la máquina virtual mediante la ejecución del docker ps comando en un terminal. Debería ver el contenedor en la lista después de ejecutar el comando. Si Visual Studio Code y el entorno de ejecución de IoT Edge se ejecutan en la misma máquina, compruebe el estado en la vista docker de Visual Studio Code.

Importante

Si usa un registro privado como Azure Container Registry para las imágenes, es posible que tenga que autenticarse para insertar imágenes. Use docker login <Azure Container Registry login server> o az acr login --name <Azure Container Registry name> para autenticarse.

Inicio de sesión en Docker

Especifique las credenciales del registro de contenedor a Docker para que pueda insertar la imagen de contenedor para que se almacene en el registro.

  1. Inicie sesión en Docker con las credenciales del registro de contenedor de Azure que guardó después de crear el registro.

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

    Podría recibir una advertencia de seguridad en la que se recomiende el uso de --password-stdin. Aunque es un procedimiento recomendado para escenarios de producción, está fuera del ámbito de este tutorial. Para más información, consulte la referencia de docker login.

  2. Inicie sesión en Azure Container Registry. Es posible que tenga que Instalar la CLI de Azure para usar el comando az. Este comando solicita el nombre de usuario y la contraseña que se encuentran en el registro de contenedor en Configuración>Claves de acceso.

    az acr login -n <Azure Container Registry name>

Sugerencia

Si cierra la sesión en cualquier momento de este tutorial, repita los pasos de inicio de sesión de Docker y Azure Container Registry para continuar.

Imagen de Docker del módulo de compilación

Use el Dockerfile del módulo para compilar la imagen de Docker.

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

Por ejemplo, para compilar la imagen del registro local o un registro de contenedor de Azure, use los siguientes 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"

Imagen de Docker del módulo de inserción

Inserte la imagen del módulo en el registro local o en un registro de contenedor.

docker push <ImageName>

Por ejemplo:

# 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

Implementación del módulo en el dispositivo de IoT Edge

Use el comando IoT Edge Azure CLI set-modules para implementar los módulos en Azure IoT Hub. Por ejemplo, para implementar los módulos definidos en el archivo deployment.debug.template.json en el centro de IoT my-iot-hub para el dispositivo de IoT Edge my-device, use el siguiente 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>"

Sugerencia

Podrá encontrar la clave de acceso compartido de IoT Hub en Azure Portal en la >configuración de seguridad de IoT Hub >Directivas de acceso compartido>iothubowner.

Depuración del módulo

Para depurar módulos en un dispositivo remoto, use depuración SSH remota en Visual Studio Code.

Habilite la depuración remota de Visual Studio Code mediante la instalación de la extensión de desarrollo remoto. Para más información sobre la depuración remota de Visual Studio Code, consulte Desarrollo remoto de Visual Studio Code.

Para más información sobre el uso de la depuración de SSH remota en Visual Studio Code, consulte Desarrollo remoto mediante SSH.

En la vista de depuración de Visual Studio Code, seleccione el archivo de configuración de depuración para el módulo. De forma predeterminada, el archivo Dockerfile .debug, la configuración createOptions del contenedor del módulo y el archivo launch.json usan localhost.

Seleccione Iniciar depuración o F5 y, a continuación, seleccione el proceso al que se va a asociar. En la vista Depuración de Visual Studio Code, verá las variables en el panel izquierdo.

Depuración mediante SSH remoto de Docker

Los motores Docker y Moby admiten conexiones SSH a contenedores que le permiten realizar la depuración en Visual Studio Code conectado a un dispositivo remoto. Antes de usar esta característica, debe cumplir los siguientes requisitos previos.

Los requisitos previos de depuración de SSH remoto pueden diferir en función del lenguaje que use. En las secciones siguientes se describe la configuración de .NET. Para obtener información sobre otros lenguajes, consulte Desarrollo remoto mediante SSH para obtener información general. Los detalles sobre cómo configurar la depuración remota se incluyen en las secciones de depuración de cada lenguaje de la documentación de Visual Studio Code.

Configuración de la tunelización SSH de Docker

  1. Siga los pasos descritos en Tunelización ssh de Docker para configurar la tunelización SSH en el equipo de desarrollo. La tunelización SSH requiere autenticación de pares de claves pública y privada y un contexto de Docker que define el punto de conexión del dispositivo remoto.

  2. La conexión a Docker requiere privilegios raíz. Siga los pasos descritos en Administración de Docker como usuario no raíz para permitir la conexión con el demonio de Docker en el dispositivo remoto. Cuando termine de depurar, es posible que quiera quitar el usuario del grupo de Docker.

  3. En Visual Studio Code, use la paleta de comandos (Ctrl+Mayús+P) para emitir el comando Docker Context: Use para activar el contexto de Docker que apunta a la máquina remota. Este comando permite que Visual Studio Code y la CLI de Docker usen el contexto de máquina remota.

    Sugerencia

    Todos los comandos de Docker usan el contexto actual. Recuerde volver a cambiar el contexto al predeterminado cuando haya terminado la depuración.

  4. Para comprobar que el contexto remoto de Docker está activo, enumere los contenedores en ejecución en el dispositivo remoto:

    docker ps

    La salida enumera los contenedores que se ejecutan en el dispositivo remoto, de forma similar a la siguiente:

    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. En el directorio .vscode , abra launch.json en Visual Studio Code y agregue una nueva configuración. Seleccione Agregar configuración y, a continuación, elija la plantilla de asociación remota coincidente para el módulo. Por ejemplo, la siguiente configuración es para .NET Core. Cambie el valor del parámetro -H en PipeArgs por el nombre DNS o la dirección IP 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
},

Depuración remota del módulo

  1. En la vista de depuración de Visual Studio Code, seleccione la configuración de depuración Remote Debug IoT Edge Module (.NET Core).

  2. Seleccione Iniciar depuración o presione F5. Seleccione el proceso al que desea asociarlo.

  3. En la vista Depuración de Visual Studio Code, verá las variables en el panel izquierdo.

  4. En Visual Studio Code, establezca puntos de interrupción en el módulo personalizado.

  5. Cuando se alcanza un punto de interrupción, puede inspeccionar variables, recorrer el código y depurar el módulo.

    Captura de pantalla de Visual Studio Code conectado a un contenedor de Docker en un dispositivo remoto, que está en pausa en un punto de interrupción.

Nota:

En el ejemplo anterior se muestra cómo depurar módulos de IoT Edge en contenedores remotos. Este ejemplo agrega un contexto remoto de Docker y cambia los privilegios de Docker en el dispositivo remoto. Después de finalizar la depuración de los módulos, establezca el contexto de Docker en el predeterminado y quite los privilegios de la cuenta de usuario.

Consulte esta entrada de blog para desarrolladores de IoT para ver un ejemplo de uso de un dispositivo Raspberry Pi.

Pasos siguientes

Después de compilar el módulo, aprenda a implementar módulos de Azure IoT Edge.

Para desarrollar módulos para los dispositivos IoT Edge, obtenga información sobre los SDK de Azure IoT Hub y los use.