Compartir a través de

Tutorial: Desarrollo de módulos de IoT Edge mediante Visual Studio Code

Se aplica a:IoT Edge 1.5 checkmark IoT Edge 1.5

Importante

IoT Edge 1.5 LTS es la versión compatible. IoT Edge 1.4 LTS alcanzó el final del ciclo de vida el 12 de noviembre de 2024. Si usa una versión anterior, consulte Update IoT Edge.

En este tutorial se muestra cómo desarrollar e implementar el código en un dispositivo IoT Edge. Azure IoT Edge módulos permiten implementar código que ejecuta la lógica de negocios directamente en el dispositivo IoT Edge. En la guía de inicio rápido para implementar código en un dispositivo Linux, configuraste un dispositivo IoT Edge e implementaste un módulo desde el Azure Marketplace.

En este artículo se describen los pasos para dos herramientas de desarrollo de IoT Edge:

  • Azure IoT Edge Dev Tool línea de comandos (CLI), que es preferible para el desarrollo.
  • Extensión Azure IoT Edge Tools para Visual Studio Code que está en modo mantenimiento.

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

En este tutorial, aprenderá a:

  • Configuración de la máquina de desarrollo
  • Usar las herramientas de IoT Edge para crear un nuevo proyecto
  • Compile el proyecto como un contenedor Docker y almacénelo en un registro de contenedor de Azure
  • Implementación del código en un dispositivo IoT Edge

El módulo IoT Edge que crea en este tutorial filtra los datos de temperatura que genera el dispositivo. Envía mensajes ascendentes solo si la temperatura está por encima de un umbral establecido. Este tipo de análisis en la periferia ayuda a reducir la cantidad de datos enviados y almacenados en la nube.

Requisitos previos

Una máquina de desarrollo:

  • Use su propio equipo o una máquina virtual.
  • Asegúrese de que la máquina de desarrollo admite la virtualización anidada para ejecutar un motor de contenedor.
  • Puede usar la mayoría de los sistemas operativos que ejecutan un motor de contenedor para desarrollar módulos IoT Edge para dispositivos Linux. En este tutorial se usa un equipo Windows, pero también se indican diferencias conocidas en macOS o Linux.
  • Instale Visual Studio Code
  • Instale el Azure CLI.

Un dispositivo Azure IoT Edge:

Recursos en la nube:

Si no tiene una cuenta de Azure, cree una cuenta free antes de comenzar.

Sugerencia

Para obtener instrucciones sobre la depuración interactiva en Visual Studio Code o Visual Studio 2022:

En este tutorial se describen los pasos de desarrollo de Visual Studio Code.

Conceptos clave

En este tutorial se explica el desarrollo de un módulo de IoT Edge. Un módulo IoT Edge es un contenedor con código ejecutable. Puede implementar uno o varios módulos en un dispositivo IoT Edge. Los módulos realizan tareas específicas, como la ingesta de datos de sensores, la limpieza y el análisis de datos, o el envío de mensajes a un IoT Hub. Para obtener más información, consulte Understand Azure IoT Edge modules.

Al desarrollar módulos IoT Edge, debe comprender la diferencia entre la máquina de desarrollo y el dispositivo de destino IoT Edge donde se implementa el módulo. El contenedor que compila para contener el código del módulo debe coincidir con el sistema operativo (SO) del dispositivo de destino. Por ejemplo, el escenario más común es desarrollar un módulo en un equipo Windows para dirigirse a un dispositivo Linux que ejecuta IoT Edge. En ese caso, el sistema operativo contenedor es Linux. A medida que avance en este tutorial, tenga en cuenta la diferencia entre el sistema operativo de la máquina de desarrollo y el sistema operativo del contenedor.

Sugerencia

Si usa IoT Edge para Linux en Windows, el dispositivo de destino en su escenario es la máquina virtual Linux, no el host de Windows.

Este tutorial tiene como destino los dispositivos que ejecutan IoT Edge con contenedores de Linux. Use su sistema operativo preferido siempre que la máquina de desarrollo ejecute contenedores de Linux. Visual Studio Code se recomienda desarrollar con contenedores de Linux, por lo que este tutorial lo usa. También puede usar Visual Studio, aunque existen diferencias en el soporte técnico entre las dos herramientas.

En la tabla siguiente se enumeran los escenarios de desarrollo admitidos para contenedores de Linux en Visual Studio Code y Visual Studio.

Visual Studio Code Visual Studio 2019/2022
Arquitectura de dispositivos Linux Linux AMD64
Linux ARM32v7
Linux ARM64		 Linux AMD64
Linux ARM32
Linux ARM64
servicios Azure Azure Functions
Azure Stream Analytics
Azure Machine Learning
Idiomas C
C#
Java
Node.js
Python		 C
C#
Más información Azure IoT Edge para Visual Studio Code Azure IoT Edge Tools for Visual Studio 2019
Azure IoT Edge Tools for Visual Studio 2022

Instalación de un motor de contenedor

IoT Edge módulos se empaquetan como contenedores, por lo que necesita un sistema de administración de contenedores compatible con Docker en el equipo de desarrollo para compilarlos y administrarlos. Docker Desktop es una opción popular para el desarrollo porque tiene una sólida compatibilidad con características. Docker Desktop en Windows permite cambiar entre contenedores de Linux y contenedores de Windows, por lo que puede desarrollar módulos para distintos tipos de dispositivos IoT Edge.

Use la documentación de Docker para instalar Docker en la máquina de desarrollo:

  • Instalar Docker Desktop para Windows. Al instalar Docker Desktop para Windows, se le pregunta si desea usar Contenedores de Linux o Windows. Puede cambiar esta opción en cualquier momento. En este tutorial se usan contenedores de Linux porque los módulos tienen como destino dispositivos Linux. Para obtener más información, consulte Switch entre Windows y contenedores de Linux.

  • Instalación de Docker Desktop para Mac

  • Lea Acerca de CE de Docker para obtener información acerca de la instalación en varias plataformas Linux. Para el Windows Subsystem for Linux (WSL), instale Docker Desktop para Windows.

Herramientas de configuración

Instale la herramienta basada en Python Azure IoT Edge Dev Tool para crear una solución IoT Edge. Tiene dos opciones:

Importante

La extensión Azure IoT Edge tools para Visual Studio Code está en modo mantenimiento. La herramienta de desarrollo preferida es la herramienta de línea de comandos (CLI) Azure IoT Edge Dev Tool.

Use las extensiones de IoT para Visual Studio Code para desarrollar módulos de IoT Edge. Estas extensiones ofrecen plantillas de proyecto, automatizan la creación del manifiesto de implementación y permiten supervisar y administrar dispositivos IoT Edge. En esta sección, instalará Visual Studio Code y la extensión de IoT y, a continuación, configurará la cuenta de Azure para administrar los recursos de IoT Hub desde Visual Studio Code.

  1. Instale Azure IoT Edge extensión.
  2. Instale Azure IoT Hub extensión.
  3. Después de instalar las extensiones, abra la paleta de comandos seleccionando Ver paleta de comandos.
  4. En la paleta de comandos, busque y seleccione Azure IoT Hub: Seleccione IoT Hub. Siga las indicaciones para seleccionar la suscripción de Azure y IoT Hub.
  5. Abra la sección del explorador de Visual Studio Code seleccionando el icono de la barra de actividades o seleccionando View > Explorer.
  6. En la parte inferior de dicha sección, expanda el menú Azure IoT Hub / Devices (Azure IoT Hub/Dispositivos). Verá los dispositivos y los dispositivos IoT Edge asociados con el centro de IoT que seleccionó en la paleta de comandos.

Instalación de herramientas específicas del lenguaje

Instale las herramientas específicas del lenguaje en el que vaya a trabajar:

Creación de un Registro de contenedor

En este tutorial, usará las extensiones Azure IoT Edge y Azure IoT Hub para crear un módulo y crear una imagen de contenedor a partir de los archivos. A continuación, inserta esta imagen en un registro que almacena y administra las imágenes. Por último, implementará la imagen en el Registro para que se ejecute en el dispositivo IoT Edge.

Importante

La extensión Azure IoT Edge Visual Studio Code está en modo maintenance.

Puede usar cualquier registro compatible con Docker para almacenar las imágenes de contenedor. Dos servicios populares del registro de Docker son Azure Container Registry y Docker Hub. En este tutorial se usa Azure Container Registry.

Si aún no tiene un registro de contenedor, siga estos pasos para crear uno nuevo en Azure:

  1. En el portal Azure, seleccione Crear un recurso>Containers>Container Registry.

  2. Especifique los siguientes valores obligatorios para crear el registro de contenedor:

    Campo Importancia
    Suscripción Seleccione una suscripción en la lista desplegable.
    Grupo de recursos Use el mismo grupo de recursos para todos los recursos de prueba que cree durante los inicios rápidos y tutoriales de IoT Edge; por ejemplo, IoTEdgeResources.
    Nombre de registro Especifique un nombre único.
    Ubicación Elija una ubicación cercana a usted.
    SKU Seleccione Básica.

  3. Seleccione Revisar y crear y, a continuación, Crear.

  4. Seleccione el nuevo registro de contenedor en la sección Resources de la página principal del portal de Azure para abrirlo.

  5. En el panel izquierdo del registro de contenedor, seleccione Claves de acceso en el menú ubicado en Configuración.

    Captura de pantalla de la ubicación del menú Claves de acceso.

  6. Habilite Usuario administrador con el botón de alternancia para ver el Nombre de usuario y la Contraseña para el registro de contenedor.

  7. Copie los valores de Servidor de inicio de sesión, Nombre de usuario y Contraseña, y guárdelos en cualquier lugar que le resulte práctico. Dichos valores se usan en todo el tutorial para proporcionar acceso al registro de contenedor.

Creación de un nuevo proyecto de módulo

La extensión Azure IoT Edge ofrece plantillas de proyecto para todos los lenguajes de módulo de IoT Edge admitidos en Visual Studio Code. Estas plantillas incluyen todos los archivos y el código que necesita para implementar un módulo de trabajo para probar IoT Edge, o bien proporcionar un punto de partida para personalizar la plantilla con su propia lógica de negocios.

Creación de una plantilla de proyecto

El IoT Edge Dev Tool simplifica el desarrollo Azure IoT Edge, con comandos controlados por variables de entorno. Le ayuda a empezar a trabajar con el desarrollo de IoT Edge mediante el IoT Edge contenedor de desarrollo y el scaffolding de la solución IoT Edge que incluye un módulo predeterminado y todos los archivos de configuración necesarios.

  1. Cree un directorio para la solución en la ruta de acceso que desee. Cambie al directorio .

    mkdir c:\dev\iotedgesolution
cd c:\dev\iotedgesolution

  2. Use el comando iotedgedev solution init para crear una solución y configurar el Azure IoT Hub en el lenguaje de desarrollo que prefiera:

    iotedgedev solution init --template csharp

El comando le pide que complete varios pasos, entre los que se incluyen:

  • Autenticación en Azure
  • Elección de una suscripción de Azure
  • Elegir o crear un grupo de recursos
  • Elija o cree un Azure IoT Hub
  • Elegir o crear un dispositivo Azure IoT Edge

Utiliza Visual Studio Code y la extensión Azure IoT Edge. Empiece por crear una solución y, a continuación, genere el primer módulo de esa solución. Cada solución puede incluir varios módulos.

  1. Seleccione Ver paleta de comandos.
  2. En la paleta de comandos, escriba y ejecute el comando Azure IoT Edge: New IoT Edge Solution.
  3. Vaya a la carpeta donde desea crear la nueva solución y, a continuación, seleccione Seleccionar carpeta.
  4. Escriba un nombre para la solución.
  5. Seleccione una plantilla de módulo para que su lenguaje de desarrollo preferido sea el primer módulo de la solución.
  6. Escriba un nombre para el módulo. Elija un nombre que sea único dentro del registro de contenedor.
  7. Escriba el nombre del repositorio de imágenes del módulo. Visual Studio Code rellena automáticamente el nombre del módulo con localhost:5000/<su nombre del módulo>. Reemplácelo por su propia información de registro. Utilice localhost si usa un registro de Docker local para hacer pruebas. Si usa Azure Container Registry, use Login server desde la configuración de su registro. El servidor de inicio de sesión se parece al nombre del registro.azurecr.io. Reemplace solo la parte localhost:5000 de la cadena, de modo que el resultado final sea similar al nombre del registro.azurecr.io/ su nombre del módulo.

Visual Studio Code toma la información proporcionada, crea una solución de IoT Edge y, a continuación, la carga en una nueva ventana.

Después de crear la solución, estos archivos principales se encuentran en la solución:

  • La carpeta .vscode incluye el archivo de configuración launch.json.

  • La carpeta modules tiene subcarpetas para cada módulo. En cada subcarpeta, el archivo module.json controla cómo se compilan e implementan los módulos.

  • El archivo .env enumera las variables de entorno. La variable de entorno para el registro de contenedor es localhost:5000 de forma predeterminada.

  • Dos archivos de implementación de módulos, deployment.template.json y deployment.debug.template.json, enumere los módulos que se van a implementar en el dispositivo. De forma predeterminada, la lista incluye los módulos del sistema de IoT Edge (edgeAgent y edgeHub) y módulos de ejemplo, como:

    • filtermodule es un módulo de ejemplo que implementa una función de filtro simple.
    • El módulo SimulatedTemperatureSensor simula los datos que puede usar para las pruebas. Para más información sobre cómo funcionan los manifiestos de implementación, consulte cómo usar los manifiestos de implementación para implementar módulos y establecer rutas. Para obtener más información sobre cómo funciona el módulo de temperatura simulado, consulte el código fuente SimulatedTemperatureSensor.csproj.

    Nota:

    Los módulos exactos instalados pueden depender del idioma que prefiera.

Configurar la versión de ejecución de IoT Edge

La versión más reciente del módulo del sistema IoT Edge estable es la 1.5. Establezca los módulos del sistema en la versión 1.5.

  1. En Visual Studio Code, abra el archivo de manifiesto de implementación deployment.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 del módulo en tiempo de ejecución del sistema y . Por ejemplo, si desea usar la versión 1.5 del entorno de ejecución de IoT Edge, 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",

Proporcione las credenciales del Registro al agente de IoT Edge

El archivo de entorno almacena las credenciales del registro de contenedor y las comparte con el entorno de ejecución de IoT Edge. El entorno de ejecución necesita estas credenciales para obtener las imágenes del contenedor en el dispositivo IoT Edge.

La extensión IoT Edge intenta extraer las credenciales del registro de contenedor de Azure y rellenarlas en el archivo de entorno.

Nota:

Solo se crea el archivo de entorno si proporciona un repositorio de imágenes para el módulo. Si aceptó los valores predeterminados de localhost para probar y depurar localmente, no es necesario declarar las variables de entorno.

Compruebe si existen sus credenciales. Si no lo están, agréguelas ahora:

  1. Si Azure Container Registry es el registro, establezca un nombre de usuario y una contraseña de Azure Container Registry. Obtenga estos valores en el menú Configuración de su registro de contenedor>Claves de acceso en el portal de Azure.

  2. Abra el archivo .env en la solución del módulo.

  3. Agregue los valores username y password que copió del registro de contenedor de Azure. Por ejemplo:

    CONTAINER_REGISTRY_SERVER="myacr.azurecr.io"
CONTAINER_REGISTRY_USERNAME="myacr"
CONTAINER_REGISTRY_PASSWORD="<registry_password>"

  4. Guarde los cambios en el archivo .env.

Nota:

En este tutorial se usan credenciales de administrador para Azure Container Registry que son convenientes 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 o los tokens de ámbito de repositorio. Para obtener más información, vea Administración del acceso al registro de contenedor.

Arquitectura de destino

Seleccione la arquitectura de destino con cada solución, ya que esto afecta a cómo se compila y ejecuta el contenedor. La opción predeterminada es Linux AMD64. En este tutorial, utilice una máquina virtual Ubuntu como dispositivo IoT Edge y mantenga el valor predeterminado amd64.

Si necesita cambiar la arquitectura de destino de la solución, siga estos pasos.

  1. Abra la paleta de comandos y busque Azure IoT Edge: Establecer plataforma de destino predeterminada para solución perimetral o seleccione el icono de acceso directo en la barra lateral de la parte inferior de la ventana.
  2. En la paleta de comandos, seleccione la arquitectura de destino en la lista de opciones.

La arquitectura de destino se establece al crear la imagen de contenedor en un paso posterior.

Actualización del módulo con código personalizado

Cada plantilla incluye código de ejemplo que toma datos de sensor simulados del módulo SimulatedTemperatureSensor y lo enruta al IoT Hub. El módulo de ejemplo recibe mensajes y los pasa. La funcionalidad de canalización muestra un concepto importante en IoT Edge: cómo se comunican los módulos entre sí.

Cada módulo puede tener varias colas de entrada y salida declaradas en su código. El centro de IoT Edge que se ejecuta en el dispositivo enruta los mensajes de la salida de un módulo a la entrada de uno o varios módulos. El código específico para declarar entradas y salidas varía entre idiomas, pero el concepto es el mismo para todos los módulos. Para más información acerca del enrutamiento entre módulos, consulte Declaración de rutas.

El código de C# de ejemplo que viene con la plantilla de proyecto usa la clase ModuleClient del SDK de IoT Hub para .NET.

  1. En el explorador de Visual Studio Code, abra modules > filtermodule > ModuleBackgroundService.cs.

  2. En la parte superior del espacio de nombres , agregue tres instrucciones para los tipos que se usarán más adelante en:

    using System.Collections.Generic;     // For KeyValuePair<>
using Microsoft.Azure.Devices.Shared; // For TwinCollection
using Newtonsoft.Json;                // For JsonConvert

  3. Agregue la variable a la clase . Esta variable establece el valor que debe superar la temperatura medida para que los datos se envíen al IoT Hub.

    static int temperatureThreshold { get; set; } = 25;

  4. Agregue las clases , y . Estas clases definen el esquema esperado para el cuerpo de los mensajes entrantes.

    class MessageBody
{
    public Machine machine {get;set;}
    public Ambient ambient {get; set;}
    public string timeCreated {get; set;}
}
class Machine
{
    public double temperature {get; set;}
    public double pressure {get; set;}
}
class Ambient
{
    public double temperature {get; set;}
    public int humidity {get; set;}
}

  5. Busque la función . Esta función crea y configura un objeto ModuleClient que permite al módulo conectarse al entorno de ejecución de Azure IoT Edge local para enviar y recibir mensajes. Después de crear el , el código lee el valor de las propiedades deseadas del módulo gemelo. El código registra un callback para recibir mensajes de un hub IoT Edge a través de un punto de conexión llamado input1.

    Reemplace la llamada al método por una nueva que actualice el nombre del punto de conexión y el método al que se llama cuando llegue la entrada. Además, agregue un método para las actualizaciones a las propiedades deseadas. Para realizar este cambio, reemplace la última línea del método por el código siguiente:

    // Register a callback for messages that are received by the module.
// await _moduleClient.SetInputMessageHandlerAsync("input1", PipeMessage, cancellationToken);

// Read the TemperatureThreshold value from the module twin's desired properties
var moduleTwin = await _moduleClient.GetTwinAsync();
await OnDesiredPropertiesUpdate(moduleTwin.Properties.Desired, _moduleClient);

// Attach a callback for updates to the module twin's desired properties.
await _moduleClient.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertiesUpdate, null);

// Register a callback for messages that are received by the module. Messages received on the inputFromSensor endpoint are sent to the FilterMessages method.
await _moduleClient.SetInputMessageHandlerAsync("inputFromSensor", FilterMessages, _moduleClient);

  6. Agregue el método a la clase . Este método recibe actualizaciones de las propiedades deseadas del módulo gemelo y actualiza la variable para que coincida. Todos los módulos tienen su propio módulo gemelo, que le permite configurar el código que se ejecuta dentro de un módulo directamente desde la nube.

    static Task OnDesiredPropertiesUpdate(TwinCollection desiredProperties, object userContext)
{
    try
    {
        Console.WriteLine("Desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));

        if (desiredProperties["TemperatureThreshold"]!=null)
            temperatureThreshold = desiredProperties["TemperatureThreshold"];

    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error when receiving desired property: {0}", exception);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error when receiving desired property: {0}", ex.Message);
    }
    return Task.CompletedTask;
}

  7. Agregue el método . Se llama a este método cada vez que el módulo recibe un mensaje del centro de IoT Edge. Filtra los mensajes que informan de temperaturas por debajo del umbral de temperatura que se establecen mediante el módulo gemelo. También agrega la propiedad al mensaje con el valor establecido en .

    async Task<MessageResponse> FilterMessages(Message message, object userContext)
{
    var counterValue = Interlocked.Increment(ref _counter);
    try
    {
        ModuleClient moduleClient = (ModuleClient)userContext;
        var messageBytes = message.GetBytes();
        var messageString = Encoding.UTF8.GetString(messageBytes);
        Console.WriteLine($"Received message {counterValue}: [{messageString}]");

        // Get the message body.
        var messageBody = JsonConvert.DeserializeObject<MessageBody>(messageString);

        if (messageBody != null && messageBody.machine.temperature > temperatureThreshold)
        {
            Console.WriteLine($"Machine temperature {messageBody.machine.temperature} " +
                $"exceeds threshold {temperatureThreshold}");
            using (var filteredMessage = new Message(messageBytes))
            {
                foreach (KeyValuePair<string, string> prop in message.Properties)
                {
                    filteredMessage.Properties.Add(prop.Key, prop.Value);
                }

                filteredMessage.Properties.Add("MessageType", "Alert");
                await moduleClient.SendEventAsync("output1", filteredMessage);
            }
        }

        // Indicate that the message treatment is completed.
        return MessageResponse.Completed;
    }
    catch (AggregateException ex)
    {
        foreach (Exception exception in ex.InnerExceptions)
        {
            Console.WriteLine();
            Console.WriteLine("Error in sample: {0}", exception);
        }
        // Indicate that the message treatment is not completed.
        var moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
        // Indicate that the message treatment is not completed.
        ModuleClient moduleClient = (ModuleClient)userContext;
        return MessageResponse.Abandoned;
    }
}

  8. Guarde el archivo ModuleBackgroundService.cs.

  9. En el explorador de Visual Studio Code, abra el archivo deployment.template.json en el área de trabajo de la solución de IoT Edge.

  10. Puesto que hemos cambiado el nombre del punto de conexión en el que el módulo escucha, también es necesario actualizar las rutas en el manifiesto de implementación para que edgeHub envíe mensajes al nuevo punto de conexión.

    Busque la sección en el gemelo del módulo $edgeHub. Actualice la ruta para reemplazar por :

    "sensorTofiltermodule": "FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/inputFromSensor\")"

  11. Agregue el módulo gemelo de filtermodule al manifiesto de implementación. Inserte el siguiente contenido JSON en la parte inferior de la sección, después del módulo gemelo de $edgeHub :

       "filtermodule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }

  12. Guarde el archivo deployment.template.json.

Compilación e inserción de la solución

Actualizó el código del módulo y la plantilla de implementación para ayudar a conocer algunos conceptos clave de la implementación. Ya está listo para que compilar la imagen de contenedor del módulo e insertarla en el registro de contenedor.

En Visual Studio Code, abra el archivo de manifiesto de implementación deployment.template.json. El manifiesto deployment 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 y las imágenes del módulo con los valores de createOptions adecuados. Para obtener más información sobre los valores de createOptions, consulte Cómo configurar las opciones de creación de contenedores para módulos de IoT Edge.

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

"registryCredentials": {
    "myacr": {
        "username": "myacr",
        "password": "<your_acr_password>",
        "address": "myacr.azurecr.io"
    }
}

Agregue o reemplace el siguiente contenido con cadenas para el valor en cada sistema (edgeHub y edgeAgent) y módulo personalizado (filtermodule y tempSensor) 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 debe ser similar a la siguiente:

"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\"}]}}}"
}

Imagen de Docker del módulo de compilación

Abra el terminal integrado Visual Studio Code seleccionando Terminal > Nuevo terminal.

Use el comando para compilar la imagen de contenedor para la arquitectura Linux y amd64. Cambie el directorio al directorio filtermodule del proyecto y ejecute el comando .

dotnet publish --os linux --arch x64 /t:PublishContainer

Actualmente, la plantilla de herramientas iotedgedev tiene como destino .NET 7.0, que alcanzó el final del soporte técnico en mayo de 2024. Actualice el proyecto a .NET 8.0 (LTS, compatible a noviembre de 2026) editando el archivo filtermodule.csproj y cambiando los valores de TargetFramework y PackageReference. El archivo filtermodule.csproj debe tener este aspecto:

<Project Sdk="Microsoft.NET.Sdk.Worker">
    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.Azure.Devices.Client" Version="1.42.0" />
        <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
    </ItemGroup>
</Project>

Etiquete la imagen de Docker con la arquitectura, la versión y la información del registro de contenedor. Reemplace por su propio nombre del registro:

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.1-amd64

Imagen de Docker del módulo de inserción

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 de Azure Container Registry (ACR):

    docker login -u <ACR username> -p <ACR password> <ACR login server>

    Podría recibir una advertencia de seguridad en la que se recomiende el uso de . Aunque ese es un procedimiento recomendado para escenarios de producción, está fuera del ámbito de este tutorial. Para la autenticación del registro de contenedores de producción, use una entidad de servicio o tokens con ámbito de repositorio en lugar de credenciales de administrador. Para más información, consulte Administración del acceso al registro de contenedor y a la referencia de inicio de sesión de Docker .

  2. Inicie sesión en el Azure Container Registry. Debe instalar Azure CLI 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 <ACR registry name>

    Sugerencia

    Si ha cerrado 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.

  3. 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. Replace myacr with your Azure Container Registry name.

az acr login --name myacr
docker push myacr.azurecr.io/filtermodule:0.0.1-amd64

Actualizar la plantilla de implementación

Actualice la plantilla de implementación deployment.template.json con la ubicación de la imagen del registro de contenedor. Por ejemplo, si está utilizando un Azure Container Registry myacr.azurecr.io y su imagen es filtermodule:0.0.1-amd64, actualice la configuración de filtermodule 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\"}]}}}"
    }
}

En el explorador de Visual Studio Code, haga clic con el botón derecho en el archivo deployment.template.json y seleccione Build and Push IoT Edge Solution.

El comando de compilación e inserción inicia tres operaciones. En primer lugar, se crea una nueva carpeta en la solución denominada config que contiene los archivos del manifiesto de la implementación completa, con la información de la plantilla de implementación y otros archivos de la solución. En segundo lugar, ejecuta para generar la imagen de contenedor basándose en el Dockerfile adecuado para la arquitectura de destino. A continuación, ejecuta para insertar el repositorio de imágenes en el registro de contenedor.

Este proceso puede tardar varios minutos la primera vez, pero es más rápido la próxima vez que ejecute los comandos.

Opcional: actualizar el módulo y la imagen

Si realiza cambios en el código del módulo, debe volver a generar e insertar la imagen del módulo en el registro de contenedor. Siga los pasos de esta sección para actualizar la compilación y la imagen de contenedor. Puede omitir esta sección si no ha realizado ningún cambio en el código del módulo.

Abra el archivo deployment.amd64.json en la carpeta de configuración recién creada. El nombre de archivo refleja la arquitectura de destino, así que es diferente si ha elegido una otra arquitectura.

Tenga en cuenta que los dos parámetros que tenían marcadores de posición ahora contienen los valores adecuados. La sección tiene el nombre de usuario del Registro y la contraseña extraídos del archivo .env . tiene el repositorio de imágenes completo con el nombre, la versión y la etiqueta de arquitectura del archivo module.json.

  1. Abra el archivo module.json de la carpeta filtermodule.

  2. Cambie el número de versión de la imagen del módulo. Por ejemplo, incremente el número de versión de la revisión a como si hubiera hecho una pequeña corrección en el código del módulo.

    Sugerencia

    Las versiones del módulo habilitan el control de versiones y permiten probar los cambios en un pequeño conjunto de dispositivos antes de implementar actualizaciones en producción. Si no incrementa la versión del módulo antes de la compilación e inserción, entonces sobrescribirá el repositorio en el registro de contenedor.

  3. Guarde los cambios en el archivo module.json.

Compile e inserte la imagen actualizada con una etiqueta de versión 0.0.2. Por ejemplo, para compilar e insertar la imagen para el registro local o un registro de contenedor de Azure, use los siguientes comandos:

# Build the container image for Linux and amd64 architecture.

dotnet publish --os linux --arch x64

# For local registry:
# Tag the image with version 0.0.2, x64 architecture, and the local registry.

docker tag filtermodule localhost:5000/filtermodule:0.0.2-amd64

# For Azure Container Registry:
# Tag the image with version 0.0.2, x64 architecture, and your container registry information. Replace **myacr** with your own registry name.

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.2-amd64

Haga clic con el botón derecho en el archivo deployment.template.json y seleccione Build and Push IoT Edge Solution de nuevo.

Vuelva a abrir el archivo deployment.amd64.json de nuevo. Observe que el sistema de compilación no crea un nuevo archivo al ejecutar de nuevo el comando de compilación e inserción. Más bien, el mismo archivo se actualiza para reflejar los cambios. La imagen de filtermodule ahora apunta a la versión 0.0.2 del contenedor.

Para comprobar aún más lo que hicieron los comandos de compilación e inserción, vaya al portal Azure y dirígete al registro de contenedores. En el registro de contenedor, seleccione Repositorios y después filtermodule. Compruebe que ambas versiones de la imagen se insertan en el registro.

Captura de pantalla de dónde ver ambas versiones de imagen en el registro de contenedor.

Solución de problemas

Si encuentra errores al compilar e insertar la imagen del módulo, a menudo tiene que ver con la configuración de Docker en la máquina de desarrollo. Utilice las siguientes comprobaciones para revisar la configuración:

  • ¿Ha ejecutado el comando mediante las credenciales que copió del registro de contenedor? Estas credenciales son diferentes de las que se usan para iniciar sesión en Azure.
  • ¿Es el repositorio de contenedor correcto? ¿Tiene el nombre correcto del registro de contenedor y el nombre correcto del módulo? Abra el archivo module.json de la carpeta filtermodule para comprobar. El valor del repositorio debe ser similar al nombre del registro.azurecr.io/filtermodule.
  • Si utilizó un nombre diferente a filtermodule para el módulo, ¿es coherente ese nombre en toda la solución?
  • ¿La máquina funciona con el mismo tipo de contenedores que está creando? Este tutorial es para dispositivos linux IoT Edge, por lo que Visual Studio Code debe decir amd64 o arm32v7 en la barra lateral y Docker Desktop debe ejecutar contenedores de Linux.

Implementación de módulos en el dispositivo

Ha verificado que hay imágenes de contenedor creadas y almacenadas en el registro de contenedor, por lo que es el momento de implementarlas en un dispositivo. Asegúrese de que el dispositivo IoT Edge esté en funcionamiento.

Use el comando IoT Edge Azure CLI set-modules para implementar los módulos en el Azure IoT Hub. Por ejemplo, para implementar los módulos definidos en el archivo deployment.template.json en el archivo IoT Hub my-iot-hub para el dispositivo IoT Edge my-device, use el siguiente comando. Reemplace los valores hub-name, device-id y login IoT Hub connection string por los suyos propios.

az iot edge set-modules --hub-name my-iot-hub --device-id my-device --content ./deployment.template.json --login "HostName=my-iot-hub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"

Sugerencia

Busque la cadena de conexión de IoT Hub, incluida la clave de acceso compartido, en el portal de Azure. Vaya a la IoT Hub y seleccione Configuración de seguridad > Directivas de acceso compartido > iothubowner.

  1. En el explorador de Visual Studio Code, en la sección Azure IoT Hub, expanda Devices para ver la lista de dispositivos IoT.

  2. Haga clic con el botón derecho en el dispositivo IoT Edge en el que desea implementar y seleccione Crear implementación para un solo dispositivo.

  3. En el Explorador de archivos, vaya a la carpeta config y seleccione el archivo deployment.amd64.json.

    No utilice el archivo deployment.template.json, que no contiene todas las credenciales del registro de contenedor o los valores de imagen del módulo. Si tiene como destino un dispositivo LINUX ARM32, el nombre del manifiesto de implementación es deployment.arm32v7.json.

  4. En el dispositivo, expanda Módulos para ver una lista de módulos implementados y en ejecución. Seleccione el botón actualizar. Debería ver los nuevos módulos tempSensor y filtermodule que se ejecutan en el dispositivo.

    Los módulos pueden tardar unos minutos en iniciarse. El entorno de ejecución de IoT Edge recibe su nuevo manifiesto de implementación, extrae las imágenes del módulo del entorno de ejecución del contenedor y, a continuación, inicia cada nuevo módulo.

Visualización de los mensajes desde el dispositivo

El código del módulo de ejemplo obtiene mensajes a través de su cola de entrada y los envía a través de su cola de salida. El manifiesto de implementación configura rutas que envían mensajes a filtermodule de tempSensor y, a continuación, reenvía mensajes de filtermodule a IoT Hub. Las extensiones Azure IoT Edge y Azure IoT Hub permiten ver los mensajes a medida que llegan a IoT Hub desde el dispositivo.

  1. En el explorador de Visual Studio Code, seleccione el dispositivo IoT Edge que quiere supervisar y, a continuación, seleccione Iniciar la supervisión en el punto de conexión de eventos integrado.

  2. Vea la ventana de salida en Visual Studio Code para ver los mensajes que llegan a la IoT Hub.

    Captura de pantalla de la ventana de salida de Visual Studio Code que muestra mensajes entrantes de dispositivo a nube.

Visualización de los cambios en el dispositivo

Para ver lo que sucede en el dispositivo, use los comandos de esta sección para inspeccionar el entorno de ejecución de IoT Edge y los módulos que se ejecutan en el dispositivo.

Estos comandos son para el dispositivo IoT Edge, no para la máquina de desarrollo. Si usa una máquina virtual para el dispositivo IoT Edge, conéctese a ella ahora. En Azure, vaya a la página de información general de la máquina virtual y seleccione Connect para acceder a la conexión de shell seguro.

  • Vea todos los módulos implementados en el dispositivo y compruebe su estado:

    iotedge list

    Verá cuatro módulos: los dos módulos IoT Edge Runtime, tempSensor y filtermodule. Los cuatro deben aparecer como en ejecución.

  • Inspeccione los registros para un módulo específico:

    iotedge logs <module name>

    Los nombres de módulo distinguen entre mayúsculas y minúsculas.

    Los registros tempSensor y filtermodule muestran los mensajes que están procesando. El módulo edgeAgent inicia los demás módulos, por lo que sus registros tienen información sobre el manifiesto de implementación. Si un módulo no aparece o no se está ejecutando, compruebe si hay errores en los registros de edgeAgent. El módulo edgeHub administra la comunicación entre los módulos y IoT Hub. Si los módulos se ejecutan, pero los mensajes no llegan al IoT Hub, compruebe los registros de errores de edgeHub.

Limpieza de recursos

Si desea continuar con el siguiente artículo recomendado, mantenga los recursos y las configuraciones que creó y reutilícelas. También puede seguir utilizando el mismo dispositivo IoT Edge como dispositivo de prueba. De lo contrario, para evitar cargos, elimine la configuración local y los recursos de Azure que usó en este artículo.

Eliminación de recursos de Azure

No se puede deshacer la eliminación de los recursos de Azure y los grupos de recursos. Asegúrese de no eliminar por accidente el grupo de recursos o los recursos equivocados. Si creó el IoT Hub dentro de un grupo de recursos existente que tiene recursos que desea conservar, elimine solo el recurso IoT Hub, no el grupo de recursos.

Para eliminar los recursos:

  1. Inicie sesión en el portal Azure y seleccione Grupos de recursos.
  2. Seleccione el nombre del grupo de recursos que contiene los recursos de prueba de IoT Edge.
  3. Revise la lista de recursos que contiene el grupo de recursos. Si desea eliminar todos ellos, puede seleccionar Eliminar grupo de recursos. Si desea eliminar solo algunos de ellos, seleccione cada recurso para eliminarlos individualmente.

Pasos siguientes

En este tutorial, configurará Visual Studio Code en la máquina de desarrollo e implementará el primer módulo de IoT Edge con código que filtra los datos sin procesar generados por el dispositivo IoT Edge.

Continúe con los siguientes tutoriales para aprender cómo Azure IoT Edge le permite implementar servicios en la nube de Azure para procesar y analizar datos en el borde.

Depurar módulos de Azure IoT EdgeFunctionsStream AnalyticsCustom Vision Service

  • Last updated on