Programación y difusión de trabajos (.NET)

Article
10/01/2024

Use Azure IoT Hub para programar y realizar el seguimiento de los trabajos que actualizan millones de dispositivos. Use los trabajos para:

Actualizar las propiedades deseadas
Actualizar etiquetas
Invocar métodos directos

Los trabajos contienen una de estas acciones y realizan el seguimiento de la ejecución en un conjunto de dispositivos, que define una consulta de dispositivo gemelo. Por ejemplo, una aplicación de back-end puede utilizar un trabajo para invocar un método directo en 10 000 dispositivos que reinicie los dispositivos. Especifique el conjunto de dispositivos con una consulta de dispositivo gemelo y programe el trabajo para que se ejecute en otro momento. Este trabajo realiza el seguimiento del progreso mientras los dispositivos reciben y ejecutan el método directo de reinicio.

Para más información sobre estas funcionalidades, vea:

Dispositivo gemelo y propiedades: Introducción a los dispositivos gemelos y Tutorial: Uso de las propiedades deseadas para configurar dispositivos
Métodos directos: Guía para desarrolladores de IoT Hub: métodos directos

Nota

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

En este artículo se muestra cómo crear dos aplicaciones de consola de .NET (C#):

Una aplicación de dispositivo, SimulateDeviceMethods, que implementa un método directo llamado LockDoor, que se puede llamar por la aplicación de back-end.
Una aplicación de back-end, ScheduleJob, que crea dos trabajos. Un trabajo llama al método directo lockDoor y otro trabajo envía actualizaciones de propiedades deseadas a varios dispositivos.

Nota

Consulte los SDK de Azure IoT para obtener más información sobre las herramientas de SDK disponibles para compilar aplicaciones de dispositivo y back-end.

Requisitos previos

Visual Studio.
Una instancia de IoT Hub en la suscripción de Azure. Si aún no tiene un centro, puede seguir los pasos descritos en Creación de un centro de IoT.
Un dispositivo registrado en su centro de IoT. Si no tiene un dispositivo en el centro de IoT, siga los pasos descritos en Registrar un dispositivo.
Asegúrese de que el puerto 8883 está abierto en el firewall. En el ejemplo de dispositivo de este artículo se usa el protocolo MQTT, que se comunica mediante el puerto 8883. Este puerto puede estar bloqueado en algunos entornos de red corporativos y educativos. Para más información y para saber cómo solucionar este problema, consulte el artículo sobre la conexión a IoT Hub (MQTT).

Creación de una aplicación de dispositivo simulado

En esta sección, creará una aplicación de consola de .NET que responderá a un método directo llamado por el back-end de solución.

Importante

En este artículo se incluyen los pasos para conectar un dispositivo mediante una firma de acceso compartido, también denominada autenticación de clave simétrica. Este método de autenticación es cómodo para probar y evaluar, pero autenticar un dispositivo mediante certificados X.509 es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de > Seguridad de la conexión.

En Visual Studio, seleccione Crear un proyecto nuevo y luego seleccione la plantilla de proyecto Aplicación de consola (.NET Framework) . Seleccione Next (Siguiente) para continuar.
En Configure su nuevo proyecto, asigne al proyecto el nombre SimulateDeviceMethods, luego seleccione Siguiente.
Acepte la versión predeterminada de .NET Framework y seleccione Crear para crear el proyecto.
En el Explorador de soluciones, haga clic con el botón derecho en el proyecto SimulateDeviceMethods, luego seleccione Administrar paquetes NuGet.
En Administrador de paquetes NuGet, seleccione Examinar y busque y elija Microsoft.Azure.Devices.Client. Seleccione Instalar.

Este paso permite descargar, instalar y agregar una referencia al paquete NuGet del SDK de dispositivo IoT de Azure y sus dependencias.

Agregue las siguientes instrucciones using al principio del archivo Program.cs :

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;
using System.Threading.Tasks;
using System.Text;

Agregue los campos siguientes a la clase Program . Sustituya el valor de marcador de posición por la cadena de conexión del dispositivo que anotó en la sección anterior:
```
static string DeviceConnectionString = "<yourDeviceConnectionString>";
static DeviceClient Client = null;
```

Agregue el código siguiente para implementar el método directo en el dispositivo:

static Task<MethodResponse> LockDoor(MethodRequest methodRequest, object userContext)
{
    Console.WriteLine();
    Console.WriteLine("Locking Door!");
    Console.WriteLine("\nReturning response for method {0}", methodRequest.Name);

    string result = "'Door was locked.'";
    return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Agregue el método siguiente para implementar el agente de escucha de dispositivos gemelos en el dispositivo:

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
{
    Console.WriteLine("Desired property change:");
    Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
}

Finalmente, agregue el código siguiente al método Main para abrir la conexión a su IoT Hub e inicializar la escucha del método directo:

try
{
    Console.WriteLine("Connecting to hub");
    Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
      TransportType.Mqtt);

    Client.SetMethodHandlerAsync("LockDoor", LockDoor, null);
    Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null);

    Console.WriteLine("Waiting for direct method call and device twin update\n Press enter to exit.");
    Console.ReadLine();

    Console.WriteLine("Exiting...");

    Client.SetMethodHandlerAsync("LockDoor", null, null);
    Client.CloseAsync().Wait();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}

Guarde el trabajo y compile la solución.

Nota

Por simplificar, este artículo no implementa una directiva de reintentos. En el código de producción, debe implementar directivas de reintento (por ejemplo, reintento de conexión), tal y como se sugiere en Control de errores transitorios.

Obtención de la cadena de conexión de IoT Hub

En este artículo se creará un servicio de back-end que programa un trabajo para que invoque un método directo en un dispositivo, programa un trabajo para actualizar el dispositivo gemelo y supervisa el progreso de cada trabajo. Para realizar estas operaciones, el servicio necesita los permisos de lectura del registro y escritura en el registro. De manera predeterminada, todas las instancias del centro de IoT se crean con una directiva de acceso compartido denominada registryReadWrite que concede estos permisos.

Para obtener la cadena de conexión de IoT Hub para la directiva registryReadWrite, siga estos pasos:

En Azure Portal, seleccione Grupos de recursos. Seleccione el grupo de recursos donde se encuentra el centro y, a continuación, seleccione el centro en la lista de recursos.
En el panel de la izquierda del centro, seleccione Directivas de acceso compartido.
En la lista de directivas, seleccione la directiva registryReadWrite.
Copie la Cadena de conexión principal y guarde el valor.

Para obtener más información sobre las directivas de acceso compartido y los permisos de IoT Hub, consulte Permisos y control del acceso.

Importante

En este artículo se incluyen los pasos para conectarse a un servicio mediante una firma de acceso compartido. Este método de autenticación es cómodo para las pruebas y la evaluación, pero la autenticación en un servicio con el Microsoft Entra ID o las identidades administradas es un enfoque más seguro. Para obtener más información, consulte Procedimientos recomendados de seguridad> Seguridad en la nube.

Programación de trabajos para llamar a un método directo y envío de actualizaciones de dispositivo gemelo

En esta sección, creará una aplicación de consola de .NET (mediante C#) que usa trabajos para llamar al método directo LockDoor y enviar las actualizaciones en la propiedad deseada a varios dispositivos.

Abra Visual Studio, seleccione Archivo>Nuevo>Proyecto. En Crear un proyecto, elija Aplicación de consola (.NET Framework) y seleccione Siguiente.
En Configure su nuevo proyecto, asigne al proyecto el nombre ScheduleJob, después seleccione Crear.
Acepte la versión predeterminada de .NET Framework y seleccione Crear para crear el proyecto.
En el Explorador de soluciones, haga clic con el botón derecho en el proyecto ScheduleJob y luego seleccione Administrar paquetes NuGet.
En el Administrador de paquetes NuGet, seleccione Examinar, busque y elija Microsoft.Azure.Devices y luego seleccione Instalar.

Este paso permite descargar, instalar y agregar una referencia al paquete NuGet del SDK de servicio IoT de Azure y sus dependencias.
Agregue las siguientes instrucciones using al principio del archivo Program.cs :
```
using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;
```
Agregue la siguiente instrucción using si no está ya presente en las instrucciones predeterminadas.
```
using System.Threading;
using System.Threading.Tasks;
```
Agregue los campos siguientes a la clase Program . Reemplace los marcadores de posición por la cadena de conexión de IoT Hub que copió anteriormente en Obtención de la cadena de conexión de IoT Hub y el nombre de su dispositivo.
```
static JobClient jobClient;
static string connString = "<yourIotHubConnectionString>";
static string deviceId = "<yourDeviceId>";
```

Agregue el método siguiente a la clase Program :

public static async Task MonitorJob(string jobId)
{
    JobResponse result;
    do
    {
        result = await jobClient.GetJobAsync(jobId);
        Console.WriteLine("Job Status : " + result.Status.ToString());
        Thread.Sleep(2000);
    } while ((result.Status != JobStatus.Completed) && 
      (result.Status != JobStatus.Failed));
}

Agregue el método siguiente a la clase Program :

public static async Task StartMethodJob(string jobId)
{
    CloudToDeviceMethod directMethod = 
      new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
      TimeSpan.FromSeconds(5));

    JobResponse result = await jobClient.ScheduleDeviceMethodAsync(jobId,
        $"DeviceId IN ['{deviceId}']",
        directMethod,
        DateTime.UtcNow,
        (long)TimeSpan.FromMinutes(2).TotalSeconds);

    Console.WriteLine("Started Method Job");
}

Agregue otro método a la clase Program:

public static async Task StartTwinUpdateJob(string jobId)
{
    Twin twin = new Twin(deviceId);
    twin.Tags = new TwinCollection();
    twin.Tags["Building"] = "43";
    twin.Tags["Floor"] = "3";
    twin.ETag = "*";

    twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

    JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
        jobId,
        $"DeviceId IN ['{deviceId}']", 
        twin, 
        DateTime.UtcNow, 
        (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

    Console.WriteLine("Started Twin Update Job");
}

Nota

Para más información sobre la sintaxis de consulta, consulte Lenguaje de consulta de IoT Hub.

Por último, agregue las líneas siguientes al método Main :

Console.WriteLine("Press ENTER to start running jobs.");
Console.ReadLine();

jobClient = JobClient.CreateFromConnectionString(connString);

string methodJobId = Guid.NewGuid().ToString();

StartMethodJob(methodJobId);
MonitorJob(methodJobId).Wait();
Console.WriteLine("Press ENTER to run the next job.");
Console.ReadLine();

string twinUpdateJobId = Guid.NewGuid().ToString();

StartTwinUpdateJob(twinUpdateJobId);
MonitorJob(twinUpdateJobId).Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

Guarde el trabajo y compile la solución.

Ejecución de las aplicaciones

Ya está preparado para ejecutar las aplicaciones.

En el Explorador de soluciones de Visual Studio, haga clic con el botón derecho en la solución y seleccione Establecer proyectos de inicio.
Seleccione Propiedades comunes>Proyecto de inicio y luego seleccione Proyectos de inicio múltiples.
Asegúrese de que SimulateDeviceMethods está en la parte superior de la lista seguido de ScheduleJob. Establezca ambas acciones en Iniciar y seleccione Aceptar.
Ejecute los proyectos haciendo clic en Iniciar o vaya al menú Depurar y haga clic en Iniciar depuración.

Verá la salida de las aplicaciones back-end y de dispositivo.

Pasos siguientes

En este artículo, ha programado trabajos para ejecutar un método directo y actualizar las propiedades del dispositivo gemelo.

Para continuar explorando el IoT Hub y los patrones de administración de dispositivos, actualice una imagen en el tutorial de Actualización de Dispositivos para Azure IoT Hub mediante la Imagen de Referencia de Raspberry Pi 3 B+.

Comparteix a través de

Programación y difusión de trabajos (.NET)

Requisitos previos

Creación de una aplicación de dispositivo simulado

Obtención de la cadena de conexión de IoT Hub

Programación de trabajos para llamar a un método directo y envío de actualizaciones de dispositivo gemelo

Ejecución de las aplicaciones

Pasos siguientes

Comentaris

Recursos addicionals