Uso de Visual Studio 2022 para desarrollar y depurar módulos para Azure IoT Edge

1. En el Explorador de soluciones, haga clic con el botón derecho en el nombre del proyecto principal y seleccione Establecer versión del entorno de ejecución de IoT Edge.

   

2. Use el menú desplegable para elegir la versión del entorno de ejecución en la que se ejecutan los dispositivos IoT Edge y, a continuación, seleccione Aceptar para guardar los cambios. Si no se realizó ningún cambio, seleccione Cancelar para salir.

   La extensión no incluye una selección para las versiones en tiempo de ejecución más recientes. Para establecer la versión de tiempo de ejecución superior a la 1.2, abra el archivo de manifiesto de implementación deployment.debug.template.json . Cambie la versión en tiempo de ejecución de las imágenes edgeAgent y edgeHub del módulo en tiempo de ejecución del sistema. Por ejemplo, para usar la versión 1.5 del entorno de ejecución de IoT Edge, cambie las siguientes líneas en el archivo de manifiesto de implementación:

   "systemModules": {
      "edgeAgent": {
       //...
         "image": "mcr.microsoft.com/azureiotedge-agent:1.5"
       //...
      "edgeHub": {
      //...
         "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
      //...
   

3. Si ha cambiado la versión, vuelva a generar el manifiesto de implementación haciendo clic con el botón derecho en el nombre del proyecto y seleccione Generar implementación para IoT Edge. Esto genera un manifiesto de implementación basado en la plantilla de implementación y lo coloca en la carpeta config del proyecto de Visual Studio.

1. Abra el archivo de manifiesto de implementación deployment.debug.template.json. El manifiesto de implementación es un documento JSON que describe los módulos que se van a configurar en el dispositivo IoT Edge de destino.

2. Cambie la versión en tiempo de ejecución de las imágenes edgeAgent y edgeHub del módulo en tiempo de ejecución del sistema. Por ejemplo, para usar la versión 1.5 del entorno de ejecución de IoT Edge, cambie las siguientes líneas en el archivo de manifiesto de implementación:

   "systemModules": {
       "edgeAgent": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
       //...
       "edgeHub": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
       //...
   

Depuración mediante el simulador

La herramienta de desarrollo de Azure IoT EdgeHub proporciona una experiencia de desarrollo y depuración local. La herramienta ayuda a iniciar los módulos IoT Edge sin el runtime de IoT Edge para que pueda crear, desarrollar, probar, ejecutar y depurar módulos y soluciones de IoT Edge de forma local. Para realizar las pruebas, no es necesario insertar imágenes en un registro de contenedor e implementarlas en un dispositivo.

Para más información, consulte el artículo sobre la herramienta de desarrollo de Azure IoT EdgeHub.

Para inicializar la herramienta en Visual Studio:

1. Recupere la cadena de conexión del dispositivo IoT Edge (que se encuentra en su IoT Hub) desde Azure Portal o desde la CLI de Azure.

   Si usa la CLI para recuperar la cadena de conexión, use este comando, reemplazando "[device_id]" y "[hub_name]" por sus propios valores:

   az iot hub device-identity connection-string show --device-id [device_id] --hub-name [hub_name]
   

2. Vaya al menú Herramientas en Visual Studio, seleccione Azure IoT Edge Tools>Configurar el simulador de IoT Edge.

3. Pegue la cadena de conexión y seleccione Aceptar.

Compilación y depuración de un solo módulo

Normalmente, quiere probar y depurar cada módulo antes de ejecutarlo dentro de una solución completa con varios módulos. La herramienta de simulador de IoT Edge permite ejecutar un único módulo de forma aislada y enviar mensajes a través del puerto 53000.

1. En Explorador de soluciones, seleccione y resalte la carpeta del proyecto del módulo (por ejemplo, IotEdgeModule1). Defina el módulo personalizado como el proyecto de inicio. Seleccione Proyecto>Establecer como proyecto de inicio del menú.

2. Pulse F5 o seleccione el botón ejecutar barra de herramientas para iniciar el simulador de IoT Edge para un único módulo. Puede tardar inicialmente entre 10 y 20 segundos.

   

3. Si el módulo se inicializa correctamente, debe ver que aparece una ventana de la aplicación de consola de .NET Core.

4. Establezca un punto de interrupción para inspeccionar el módulo.

   • Si desarrolla en C#, establezca un punto de interrupción en la función PipeMessage() de ModuleBackgroundService.cs.
   • Si usa C, establezca un punto de interrupción en la función InputQueue1Callback() de InputQueue1Callback().

5. Haga una prueba al módulo enviando un mensaje. Al depurar un solo módulo, el simulador escucha en el puerto predeterminado 53000 para los mensajes. Para enviar un mensaje al módulo, ejecute el siguiente comando curl desde un shell de comandos como Git Bash o WSL Bash.

   curl --header "Content-Type: application/json" --request POST --data '{"inputName": "input1","data":"hello world"}' http://localhost:53000/api/v1/messages
   

   Si recibe el error sin coincidencia de llave o corchete en la dirección URL, en su lugar, pruebe el siguiente comando:

   curl --header "Content-Type: application/json" --request POST --data "{\"inputName\": \"input1\", \"data\", \"hello world\"}"  http://localhost:53000/api/v1/messages
   

   

   Debe desencadenarse el punto de interrupción. Puede ver las variables en la ventana Variables locales de Visual Studio, que se encuentran cuando se ejecuta el depurador. Vaya a Depurar>Windows>Locales.

   En bash o shell, debería ver una confirmación {"message":"accepted"}.

   En la consola de .NET debería ver:

   IoT Hub module client initialized.
   Received message: 1, Body: [hello world]
   

6. Presione Ctrl + F5 o seleccione el botón Detener para detener la depuración.

Creación y depuración de varios módulos

Cuando haya terminado de desarrollar el módulo, querrá ejecutar y depurar una solución completa de varios módulos. Mediante la herramienta de simulador IoT Edge es posible ejecutar todos los módulos definidos en el manifiesto de implementación, entre los que se incluyen un edgeHub simulado para enrutar mensajes. En este ejemplo, ejecutará dos módulos personalizados y el módulo del sensor de temperatura simulado. Los mensajes del módulo del sensor de temperatura simulado se enrutan a cada módulo personalizado.

1. En el Explorador de soluciones, agregue un segundo módulo a la solución haciendo clic con el botón derecho en la carpeta del proyecto. En el menú, seleccione Agregar>New IoT Edge Module (Nuevo módulo de IoT Edge).

   

2. En la ventana Add module, asigne un nombre al nuevo módulo y reemplace la parte localhost:5000 de la dirección URL del repositorio por el servidor de inicio de sesión de Azure Container Registry, como hizo antes.

3. Abra el archivo deployment.debug.template.json para ver que el nuevo módulo se ha agregado a la sección modules. También se ha agregado una nueva ruta a la sección routes en EdgeHub para enviar mensajes desde el nuevo módulo a IoT Hub. Para enviar datos desde el sensor de temperatura simulado al nuevo módulo, agregue otra ruta con la línea siguiente de JSON. Reemplace <NewModuleName> (en dos lugares) por el nombre de su propio módulo.

   "sensorTo<NewModuleName>": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/<NewModuleName>/inputs/input1\")"
   

4. Haga clic con el botón derecho en el proyecto principal, (por ejemplo, AzureIotEdgeApp1) y seleccione Establecer como proyecto de inicio. Al establecer el proyecto principal como el de inicio, se ejecutan todos los módulos de la solución. Esto incluye ambos módulos que ha agregado a la solución, el módulo de sensor de temperatura simulado y el centro simulado de Edge.

5. Pulse F5 o seleccione el botón de la barra de herramientas de ejecutar para ejecutar la solución. Puede tardar inicialmente entre 10 y 20 segundos. Asegúrese de que no tiene otros contenedores de Docker en ejecución que puedan enlazar el puerto que necesita para este proyecto.

6. Debería ver dos ventanas de aplicación de .NET Core, una para cada módulo.

7. Establezca un punto de interrupción para inspeccionar el módulo.

   • Si desarrolla en C#, establezca un punto de interrupción en la función PipeMessage() de ModuleBackgroundService.cs.
   • Si usa C, establezca un punto de interrupción en la función InputQueue1Callback() de InputQueue1Callback().

8. Cree puntos de interrupción en cada módulo y luego presione F5 para ejecutar y depurar varios módulos a la vez. Verá varias ventanas de aplicación de consola de .NET Core; cada una de ellas representa un módulo distinto.

   

9. Presione Ctrl + F5 o seleccione el botón Detener para detener la depuración.

Compilación e inserción de imágenes en el registro

Después de desarrollar y depurar el módulo, compile e inserte la imagen del módulo en Azure Container Registry. A continuación, implemente el módulo en el dispositivo IoT Edge.

1. Establezca que el proyecto de IoT Edge sea el proyecto de inicio, no uno de los módulos individuales.

2. Seleccione Depurar o Versión como configuración para compilar las imágenes del módulo.

   Nota:

   Al elegir Depurar, Visual Studio usa Dockerfile.(amd64|windows-amd64).debug para compilar imágenes de Docker. Esto incluye el depurador de la línea de comandos de .NET Core VSDBG en la imagen de contenedor. Para los módulos de IoT Edge listos para producción, use la configuración Release, que usa Dockerfile.(amd64|windows-amd64) sin VSDBG.

3. Si usa un registro privado como Azure Container Registry (ACR), use el siguiente comando de Docker para iniciar sesión. Obtenga el nombre de usuario y la contraseña de la página Claves de acceso del registro en Azure Portal.

   docker login <ACR login server>
   

4. Agregue la información de inicio de sesión de Azure Container Registry a la configuración del entorno de ejecución en el deployment.debug.template.json archivo . Puede agregar sus credenciales del Registro al .env archivo (más seguro) o agregarlas directamente al deployment.debug.template.json archivo.

   Agregue las credenciales al archivo .env:

   En Explorador de soluciones,seleccione el botón de la barra de herramientas Mostrar todos los archivos. Aparece el archivo .env. Agregue su nombre de usuario y contraseña de Azure Container Registry al archivo .env. Busque estas credenciales en la página Claves de acceso de Azure Container Registry en Azure Portal.

   

       DEFAULT_RT_IMAGE=1.2
       CONTAINER_REGISTRY_USERNAME_myregistry=<my-registry-name>
       CONTAINER_REGISTRY_PASSWORD_myregistry=<my-registry-password>
   

   Adición de credenciales de forma directa a deployment.debug.template.json

   Si desea agregar las credenciales directamente a la plantilla de implementación, reemplace los marcadores de posición por el nombre de usuario, la contraseña y el nombre del registro del administrador de ACR.

         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "registry1": {
               "username": "<username>",
               "password": "<password>",
               "address": "<registry name>.azurecr.io"
             }
           }
         }
   

   Nota:

   En este artículo se usan credenciales de inicio de sesión de administrador de Azure Container Registry, que son prácticas para escenarios de desarrollo y pruebas. Cuando esté listo para escenarios de producción, se recomienda una opción de autenticación con privilegios mínimos, como las entidades de servicio. Para obtener más información, vea Administración del acceso al registro de contenedor.

5. Si usa un registro local, ejecute un registro local.

6. Por último, en el Explorador de soluciones, haga clic con el botón derecho en la carpeta del proyecto principal y seleccione Compilación e inserción de módulos IoT Edge para compilar e insertar la imagen de Docker para cada módulo. Esta operación puede tardar un minuto. Cuando vea Finished Build and Push IoT Edge Modules. en la consola de salida de Visual Studio, ya habrá terminado.

Implementación de la solución

Ahora que ha compilado e insertado las imágenes del módulo en Azure Container Registry, implemente la solución en el dispositivo IoT Edge. Ya tiene una plantilla de manifiesto de implementación en este tutorial. Genere un manifiesto de implementación a partir de él y, a continuación, use un comando de la CLI de Azure para implementar los módulos en el dispositivo IoT Edge en Azure.

1. Haga clic con el botón derecho en el proyecto principal en el Explorador de soluciones de Visual Studio y elija Generar implementación para IoT Edge.

   

2. Vaya a la carpeta local del proyecto principal de Visual Studio y busque en la carpeta config. La ruta de acceso del archivo podría tener el aspecto siguiente: C:\Users\<YOUR-USER-NAME>\source\repos\<YOUR-IOT-EDGE-PROJECT-NAME>\config. Aquí encontrará el manifiesto de implementación generado, como deployment.amd64.debug.json.

3. Abra el deployment.amd64.debug.json archivo y confirme que la versión del edgeHub esquema está establecida en 1.2.

    "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.2",
          "routes": {
            "IotEdgeModule2022ToIoTHub": "FROM /messages/modules/IotEdgeModule2022/outputs/* INTO $upstream",
            "sensorToIotEdgeModule2022": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/IotEdgeModule2022/inputs/input1\")",
            "IotEdgeModule2022bToIoTHub": "FROM /messages/modules/IotEdgeModule2022b/outputs/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      }
   

   Sugerencia

   La plantilla de implementación para Visual Studio 2022 requiere la versión 1.2 del esquema. Si necesita que sea 1.1 o 1.0, espere hasta que se genere la implementación (no lo cambie en el deployment.debug.template.json). La generación de una implementación crea un esquema 1.2 de forma predeterminada. Sin embargo, puede cambiar manualmente deployment.amd64.debug.json, el manifiesto generado, si es necesario, antes de implementarlo en Azure.

   Importante

   Una vez implementado el dispositivo IoT Edge, actualmente no se mostrará correctamente en Azure Portal con la versión de esquema 1.2 (la versión 1.1 está bien). Sin embargo, esto no afectará al dispositivo, ya que todavía está conectado en IoT Hub y se puede comunicar con en cualquier momento mediante la CLI de Azure.

   

4. Ahora vamos a implementar nuestro manifiesto con un comando de la CLI de Azure. Abra el Símbolo del sistema para desarrolladores de Visual Studio y vaya al directorio config.

       cd config
   

5. Implemente el manifiesto del dispositivo IoT Edge en IoT Hub. El comando configura el dispositivo para usar módulos que se desarrollan en la solución. El manifiesto de implementación se creó en el paso anterior y se almacenó en la carpeta config. En la carpeta config, ejecute el siguiente comando de implementación. Reemplace [device id], [hub name] y [file path] con sus propios valores. Si el identificador del dispositivo IoT Edge no existe en IoT Hub, deberá crearse.

       az iot edge set-modules --device-id [device id] --hub-name [hub name] --content [file path]
   

   Por ejemplo, el comando podría tener el siguiente aspecto:

   az iot edge set-modules --device-id my-device-name --hub-name my-iot-hub-name --content deployment.amd64.debug.json
   

6. Después de ejecutar el comando, verá una confirmación de que la implementación se ha completado, impresa en formato JSON en su consola de comandos.

Imagen de Docker del módulo de compilación

Después de desarrollar el módulo, compile la imagen del módulo para almacenarla en un registro de contenedor para su implementación en el dispositivo IoT Edge.

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, si el shell de comandos está en el directorio del proyecto y el nombre del módulo es IotEdgeModule1, use los siguientes comandos para compilar la imagen para el registro local o un registro de contenedor de Azure:

# Build the image for the local registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t localhost:5000/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Or build the image for an Azure Container Registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

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/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure Container Registry
az acr login --name myacr
docker push myacr.azurecr.io/iotedgemodule1:0.0.1-amd64

Implemente el módulo en el dispositivo de IoT Edge.

En Visual Studio, abra el archivo de manifiesto de implementacióndeployment.debug.template.json del proyecto principal. El manifiesto de implementación es un documento JSON que 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, las imágenes del módulo y 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 una instancia de Azure Container Registry para almacenar la imagen del módulo, debe agregar las credenciales a deployment.debug.template.json en la configuración edgeAgent. Por ejemplo,

   "modulesContent": {
   "$edgeAgent": {
     "properties.desired": {
       "schemaVersion": "1.1",
       "runtime": {
         "type": "docker",
         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "myacr": {
               "username": "myacr",
               "password": "<your_acr_password>",
               "address": "myacr.azurecr.io"
             }
           }
         }
       },
   //...
   

2. Reemplace el valor de la propiedad image por el nombre de la imagen del módulo que insertó en el registro. Por ejemplo, si insertó una imagen etiquetada myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 para el módulo personalizado IotEdgeModule1, reemplace el valor de propiedad de la imagen por el valor de la etiqueta.

3. Agregue o reemplace el valor de createOptions por contenido con cadenas para cada sistema y módulo personalizado de la plantilla de implementación.

   Por ejemplo, la imagen de IotEdgeModule1 y la configuración createOptions sería similar a la siguiente:

   "IotEdgeModule1": {
   "version": "1.0.0",
   "type": "docker",
   "status": "running",
   "restartPolicy": "always",
   "settings": {
       "image": "myacr.azurecr.io/iotedgemodule1:0.0.1-amd64",
       "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
   }
   

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