Depurar módulos Azure IoT Edge mediante Visual Studio Code

  • Artículo

Se aplica a:IoT Edge 1.4 checkmark IoT Edge 1.4

Importante

IoT Edge 1.4 es la versión admitida. Si está usando una versión anterior, consulte Actualización de IoT Edge.

En este artículo se muestra cómo usar Visual Studio Code para depurar módulos de IoT Edge en varios lenguajes. En el equipo de desarrollo, puede usar Visual Studio Code para asociar 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.

Use el botón del selector de la herramienta al principio de este artículo para seleccionar la versión de la herramienta.

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

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

Azure IoT Edge admite las siguientes arquitecturas de dispositivos:

  • 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.

Instalar Visual Studio Code

Agregue las siguientes extensiones:

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

  • Una instancia de IoT Hub activa con al menos un dispositivo de IoT Edge.
  • Un dispositivo físico IoT Edge o un dispositivo virtual. Para crear un dispositivo virtual en Azure, siga los pasos del inicio rápido para Linux.
  • Un módulo de IoT Edge personalizado. Para crear un módulo personalizado, siga los pasos descritos en el tutorial Desarrollo de módulos de Azure IoT Edge mediante Visual Studio Code.

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

No se admite la depuración en modo de asociación para C o Python.

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

En cada carpeta de módulo, hay varios archivos de Docker para diferentes tipos de contenedor. Use cualquiera de estos archivos que acaban con la extensión .debug para compilar el módulo de pruebas.

Al depurar los módulos con este método, estos se ejecutan sobre el entorno de ejecución de IoT Edge. El dispositivo de IoT Edge y Visual Studio Code pueden estar en la misma máquina, o como es más habitual, Visual Studio Code se encuentra en el equipo de desarrollo y el entorno de tiempo de ejecución y los módulos de IoT Edge se ejecutan en otro equipo físico. Para depurar desde Visual Studio Code, debe:

  • 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, debe actualizar las credenciales de Azure Container Registry y las imágenes del módulo con los valores de createOptions adecuados. 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).

Puede comprobar el estado del contenedor desde el dispositivo o la máquina virtual ejecutando el comando docker ps en un terminal. Debería ver el contenedor en la lista después de ejecutar el comando. Si el entorno de tiempo de ejecución de IoT Edge y Visual Studio Code se ejecutan en el mismo equipo, también puede comprobar el estado en la vista de 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>

    Puede recibir una advertencia de seguridad en la que se recomiende el uso de --password-stdin. Aunque ese 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 archivo Dockerfile del módulo para compilar la imagen de Docker del módulo.

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, puede usar la depuración SSH remota de Visual Studio Code.

Para habilitar la depuración remota de Visual Studio Code, instale 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 cómo usar la depuración SSH remota en Visual Studio Code, consulte Desarrollo remoto mediante SSH

En la vista Depuración de Visual Studio Code seleccione el archivo de configuración de depuración del 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 presione F5. Seleccione el proceso al que desea asociarlo. 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 ser diferentes 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 de nivel 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 haya terminado 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 hace que Visual Studio Code y la CLI de Docker usen el contexto de la 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 debe mostrar 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.4                            "/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.4                          "/bin/sh -c 'exec /a…"    24 hours ago   Up 6 minutes                                                                                                    
                                       edgeAgent

  5. En el directorio .vscode, agregue una nueva configuración a launch.json abriendo el archivo en Visual Studio Code. Seleccione Add configuration y 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.

    Screenshot of Visual Studio Code attached to a Docker container on a remote device paused at a breakpoint.

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 cómo implementar módulos de Azure IoT Edge desde Visual Studio Code.

Para desarrollar módulos para los dispositivos IoT Edge, consulte Información y uso de los SDK de Azure IoT Hub.