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

1. En Solution Explorer, haga clic con el botón derecho en el nombre del proyecto principal y seleccione Set IoT Edge versión en tiempo de ejecución.

   

2. Use el menú desplegable para elegir la versión en tiempo de ejecución que ejecutan los dispositivos IoT Edge y, a continuación, seleccione OK 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 IoT Edge versión 1.5 del entorno de ejecución, cambie las líneas siguientes 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, 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 deployment 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 IoT Edge versión 1.5 del entorno de ejecución, cambie las líneas siguientes 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 Azure IoT EdgeHub proporciona una experiencia de desarrollo y depuración local. La herramienta ayuda a iniciar IoT Edge módulos sin el entorno de ejecución de IoT Edge para poder crear, desarrollar, probar, ejecutar y depurar IoT Edge módulos y soluciones localmente. Para realizar las pruebas, no es necesario insertar imágenes en un registro de contenedor e implementarlas en un dispositivo.

Para obtener más información, consulte Azure IoT EdgeHub Dev Tool.

Para inicializar la herramienta en Visual Studio:

1. Obtenga la cadena de conexión de su dispositivo IoT Edge (que se encuentra en el IoT Hub) desde el portal Azure o desde Azure CLI.

   Si usa la CLI para recuperar el connection string, 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. En el menú Tools de Visual Studio, seleccione Azure IoT Edge Tools>Setup IoT Edge Simulator.

3. Pegue el connection string y seleccione OK.

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 un envío de mensajes a través del puerto 53000.

1. En Solution Explorer, seleccione y resalte la carpeta del proyecto del módulo (por ejemplo, IotEdgeModule1). Defina el módulo personalizado como el proyecto de inicio. Seleccione ProyectoEstablecer como proyecto de inicio del menú.

2. Presione 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.

   Captura de pantalla de cómo ejecutar un módulo.

3. Debería ver que aparece una ventana de aplicación de consola de .NET Core si el módulo se ha inicializado correctamente.

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 de ModuleBackgroundService.cs.
   • Si usa C, establezca un punto de interrupción en la función en main.c.

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 ruptura. Puede ver las variables en la ventana Visual Studio Locals, que se encuentra cuando se ejecuta el depurador. Vaya a Debug>Windows>Locals.

   En bash o shell, debería ver una confirmación .

   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 parar la depuración.

Compilar y depurar múltiples módulos

Después de desarrollar un único módulo, es posible que desee ejecutar y depurar toda una solución con múltiples módulos. La herramienta del simulador de IoT Edge permite ejecutar todos los módulos definidos en el manifiesto de implementación, incluido un edgeHub simulado para el enrutamiento de 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 son enviados a cada módulo personalizado.

1. En Solution Explorer, agregue un segundo módulo a la solución haciendo clic con el botón derecho en la carpeta principal del proyecto. En el menú, seleccione Agregar>Nuevo IoT Edge Module.

   

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 con el servidor de inicio de sesión de Azure Container Registry, como hizo antes.

3. Abra el archivo para ver que el nuevo módulo se ha agregado a la sección modules. También se agregó una nueva ruta a la sección routes de 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 . Reemplace (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 haga clic en el botón ejecutar de la barra de herramientas 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 que dos ventanas de aplicación de consola .NET Core aparecen 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 de ModuleBackgroundService.cs.
   • Si usa C, establezca un punto de interrupción en la función en main.c.

8. Cree puntos de interrupción en cada módulo y luego presione F5 para ejecutar y depurar varios módulos a la vez. Debería ver varias ventanas de aplicación de consola de .NET Core, con cada ventana que representa un módulo diferente.

   

9. Presione Ctrl + F5 o seleccione el botón Detener para parar 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 el Azure Container Registry. A continuación, implemente el módulo en el dispositivo IoT Edge.

1. Establezca el proyecto de IoT Edge principal como 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 Debug, 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 de su registro en el portal de Azure.

   docker login <ACR login server>
   

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

   Agregue las credenciales al archivo :

   En Solution Explorer, seleccione el botón de barra de herramientas Show All Files. Aparece el archivo . Agregue el nombre de usuario y la contraseña de Azure Container Registry a su archivo .env. Busque estas credenciales en la página Access Keys del Azure Container Registry en el portal de Azure.

   

       DEFAULT_RT_IMAGE=1.5
       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 para Azure Container Registry, que son convenientes para escenarios de desarrollo y prueba. 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 Solution Explorer, haga clic con el botón derecho en la carpeta principal del proyecto y seleccione Build and Push IoT Edge Modules 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, ha terminado.

Implementación de la solución

Ahora que ha creado e insertado las imágenes del módulo en la 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 Azure CLI 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 Visual Studio Solution Explorer y elija Generar implementación para IoT Edge.

   Captura de pantalla de la ubicación del elemento de menú "generate deployment" (generar implementación).

2. Vaya a la carpeta del proyecto principal de Visual Studio local y busque en la carpeta config. La ruta de acceso del archivo podría tener el aspecto siguiente: . Aquí encontrará el manifiesto de implementación generado, como .

3. Abra el archivo y confirme que la versión del 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 de esquema 1.2. Si necesita que sea 1.1 o 1.0, espere hasta que se genere la implementación (no lo cambie en el ). 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 el portal de Azure 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 el Azure CLI.

   

4. Ahora vamos a implementar nuestro manifiesto con un comando Azure CLI. 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 , y con sus propios valores. Si el identificador de dispositivo IoT Edge no existe en el IoT Hub, debe 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 push

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 IoT Edge.

En Visual Studio, abra deployment.debug.template.json archivo de manifiesto de implementación en el proyecto principal. El manifiesto deployment es un documento JSON que describe los módulos que se van a configurar en el dispositivo 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 obtener más información sobre los valores de opciones de creación, consulte Cómo configurar 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, 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 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\"}]}}}"
   }
   

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