Introdução ao gerenciamento de dispositivos (.NET)

Artigo
03/19/2023

Os aplicativos de back-end podem usar primitivos do Hub IoT do Azure, como dispositivos gêmeos e métodos diretos, para iniciar e monitorar remotamente as ações de gerenciamento de dispositivo nos dispositivos. Este artigo mostra como um aplicativo de back-end e um dispositivo podem trabalhar juntos para permitir que você inicie e monitore uma reinicialização remota por meio do Hub IoT.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

Use um método direto para iniciar as ações de gerenciamento do dispositivo (como a reinicialização, redefinição de fábrica e atualização do firmware) a partir de um aplicativo de back-end na nuvem. O dispositivo é responsável por:

Lidar com a solicitação do método enviada a partir do Hub IoT.
Iniciar a ação específica do dispositivo correspondente no dispositivo.
Fornecimento de atualizações de status por meio das propriedades relatadas para o Hub IoT.

Você pode usar um aplicativo de back-end na nuvem para executar consultas do dispositivo gêmeo para relatar o progresso de suas ações de gerenciamento do dispositivo.

Este artigo mostra como criar:

SimulateManagedDevice: um aplicativo de dispositivo simulado com um método direto que reinicializa o dispositivo e relata a hora da última reinicialização. Métodos diretos são invocados da nuvem.
TriggerReboot: um aplicativo de console .NET que chama um método direto no aplicativo de dispositivo simulado por meio do Hub IoT. Ele exibe a resposta e as propriedades relatadas atualizadas.

Pré-requisitos

Visual Studio.
Um hub IoT. Crie um com a CLI ou o portal do Azure.
Um dispositivo registrado. Registre um no portal do Azure.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

Criar um aplicativo de dispositivo com um método direto

Nesta seção, você:

Crie um aplicativo de console do .NET que responde a um método direto chamado pela nuvem.
Dispare uma reinicialização do dispositivo simulado.
Use as propriedades relatadas para habilitar consultas de dispositivo gêmeo para identificar os dispositivos e quando foi sua última reinicialização.

Para criar o aplicativo de dispositivo simulado, siga estas etapas:

Abra o Visual Studio e selecione Criar um projeto, depois localize e selecione o modelo de projeto Aplicativo de Console (.NET Framework) e selecione Avançar.
Em Configurar seu novo projeto, nomeie o projeto como SimulateManagedDevice e, em seguida, selecione Avançar.
Mantenha a versão padrão do .NET Framework e selecione Criar.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto SimulateManagedDevice e selecione em Gerenciar Pacotes NuGet.
Selecione Procurar para pesquisar e selecione Microsoft.Azure.Devices.Client. Selecione Instalar.

Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do SDK do dispositivo IoT do Azure e as dependências dele.

Adicione as instruções using abaixo na parte superior do arquivo Program.cs :

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;

Adicione os seguintes campos à classe Program . Substitua o valor do espaço reservado {device connection string} pela cadeia de conexão de dispositivo que você viu quando registrou um dispositivo no Hub IoT:
```
static string DeviceConnectionString = "{device connection string}";
static DeviceClient Client = null;
```

Adicione o seguinte para implementar o método direto no dispositivo:

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
    // In a production device, you would trigger a reboot 
    //   scheduled to start after this method returns.
    // For this sample, we simulate the reboot by writing to the console
    //   and updating the reported properties.
    try
    {
        Console.WriteLine("Rebooting!");

        // Update device twin with reboot time. 
        TwinCollection reportedProperties, reboot, lastReboot;
        lastReboot = new TwinCollection();
        reboot = new TwinCollection();
        reportedProperties = new TwinCollection();
        lastReboot["lastReboot"] = DateTime.Now;
        reboot["reboot"] = lastReboot;
        reportedProperties["iothubDM"] = reboot;
        Client.UpdateReportedPropertiesAsync(reportedProperties).Wait();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }

    string result = @"{""result"":""Reboot started.""}";
    return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Por fim, adicione o seguinte código ao método Principal para abrir a conexão para o hub IoT e inicializar o ouvinte do método:

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

    // setup callback for "reboot" method
    Client.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
    Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
    Console.ReadLine();

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

    // as a good practice, remove the "reboot" handler
    Client.SetMethodHandlerAsync("reboot", null, null).Wait();
    Client.CloseAsync().Wait();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}

No Gerenciador de Soluções, clique com o botão direito do mouse na solução e selecione Definir Projetos de Inicialização.
Para Propriedades Comuns>Projeto de Inicialização, selecione Projeto de inicialização único e, em seguida, o projeto SimulateManagedDevice. Selecione OK para salvar suas alterações.
Selecione Compilar>Compilar Solução.

Observação

Para simplificar, este artigo não implementa nenhuma política de repetição. No código de produção, você deve implementar políticas de repetição (como uma retirada exponencial), conforme sugerido em Tratamento de falhas transitórias.

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end que invoca um método direto em um dispositivo. Para invocar um método direto em um dispositivo por meio do Hub IoT, o seu serviço precisa da permissão conexão de serviço. Por padrão, todo Hub IoT é criado com uma política de acesso compartilhado chamada serviço que concede essa permissão.

Para obter a cadeia de conexão do Hub IoT para a política de serviço, siga estas etapas:

No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do hub IoT, selecione Políticas de acesso compartilhado.
Na lista de políticas, selecione a política de serviço.
Copie a Cadeia de conexão primária e salve o valor.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Criar um aplicativo de serviço para disparar uma reinicialização

Nesta seção, você criará um aplicativo do console .NET, usando C#, que inicia uma reinicialização remota em um dispositivo usando um método direto. O aplicativo usa consultas de dispositivo gêmeo para descobrir o último horário de reinicialização para esse dispositivo.

Abra o Visual Studio e selecione Criar um projeto.
Em Criar um projeto, localize e selecione o modelo de projeto Aplicativo de Console (.NET Framework) e selecione Próximo.
Em Configurar seu novo projeto, nomeie o projeto como TriggerReboot e depois selecione Avançar.
Aceite a versão padrão do .NET Framework e selecione Criar, para criar o projeto.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto TriggerReboot e selecione Gerenciar Pacotes NuGet.
Selecione Procurar para pesquisar e selecione Microsoft.Azure.Devices. Selecione Instalar para instalar o pacote Microsoft.Azure.Devices.

Esta etapa baixa, instala e adiciona uma referência ao pacote NuGet do SDK do serviço IoT do Azure e suas dependências.
Adicione as instruções using abaixo na parte superior do arquivo Program.cs :
```
using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;
```
Adicione os seguintes campos à classe Program . Substitua o valor de espaço reservado {iot hub connection string} pela cadeia de conexão do Hub IoT que você copiou anteriormente em Obter a cadeia de conexão do hub IoT.
```
static RegistryManager registryManager;
static string connString = "{iot hub connection string}";
static ServiceClient client;
static string targetDevice = "myDeviceId";
```

Adicione o seguinte método à classe Programa. Esse código obtém o dispositivo gêmeo para o dispositivo de reinicialização e gera as propriedades relatadas.

public static async Task QueryTwinRebootReported()
{
    Twin twin = await registryManager.GetTwinAsync(targetDevice);
    Console.WriteLine(twin.Properties.Reported.ToJson());
}

Adicione o seguinte método à classe Programa. Esse código inicia uma reinicialização no dispositivo usando um método direto.

public static async Task StartReboot()
{
    client = ServiceClient.CreateFromConnectionString(connString);
    CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
    method.ResponseTimeout = TimeSpan.FromSeconds(30);

    CloudToDeviceMethodResult result = await 
      client.InvokeDeviceMethodAsync(targetDevice, method);

    Console.WriteLine("Invoked firmware update on device.");
}

Por fim, adicione as seguintes linhas ao método Principal :

registryManager = RegistryManager.CreateFromConnectionString(connString);
StartReboot().Wait();
QueryTwinRebootReported().Wait();
Console.WriteLine("Press ENTER to exit.");
Console.ReadLine();

Selecione Compilar>Compilar Solução.

Observação

Este artigo executa somente uma única consulta para propriedades relatadas do dispositivo. No código de produção, recomendamos a sondagem para detectar alterações nas propriedades relatadas.

Executar os aplicativos

Agora você está pronto para executar os aplicativos.

Para executar o aplicativo do dispositivo .NET SimulateManagedDevice, no Gerenciador de Soluções, clique com o botão direito do mouse no projeto SimulateManagedDevice, selecione Depurar e, em seguida, selecione Iniciar nova instância. O aplicativo deve começar a escutar chamadas de método do seu Hub IoT.
Depois que o dispositivo estiver conectado e aguardando invocações de método, clique com o botão direito do mouse no projeto TriggerReboot, selecione Depurar e, em seguida, selecione Iniciar nova instância.

Você deve ver Reiniciando escrito no console SimulatedManagedDevice e as propriedades relatadas do dispositivo, que incluem a hora da última reinicialização, escritas no console TriggerReboot.

Personalizar e estender as ações de gerenciamento do dispositivo

As soluções de IoT podem expandir o conjunto definido de padrões de gerenciamento do dispositivo ou habilitar padrões personalizados usando o dispositivo gêmeo e os primitivos do método da nuvem para o dispositivo. Outros exemplos de ações de gerenciamento do dispositivo incluem a redefinição de fábrica, atualização do firmware, atualização do software, gerenciamento de energia, gerenciamento da rede e da conectividade, e criptografia dos dados.

Janelas de manutenção do dispositivo

Normalmente, você pode configurar os dispositivos para executar ações em um horário que minimiza as interrupções e a inatividade. As janelas de manutenção do dispositivo são um padrão usado para definir a hora em que um dispositivo deve atualizar sua configuração. As soluções de back-end podem usar as propriedades desejadas do dispositivo gêmeo para definir e ativar uma política no dispositivo que permite uma janela de manutenção. Quando um dispositivo recebe a política da janela de manutenção, ele pode usar a propriedade relatada do dispositivo gêmeo para informar o status da política. O aplicativo de back-end pode usar as consultas do dispositivo gêmeo para atestar a conformidade dos dispositivos e cada política.

Próximas etapas

Neste artigo, você usou um método direto para disparar uma reinicialização remota em um dispositivo. Você usou as propriedades relatadas para relatar a hora da última reinicialização do dispositivo e consultou o dispositivo gêmeo para descobrir a hora da última reinicialização do dispositivo na nuvem.

Para continuar a introdução aos padrões de Hub IoT e de gerenciamento de dispositivos, como a atualização baseada em imagem de ponta a ponta no artigo de Atualização de dispositivo para o Hub IoT do Azure usando a imagem de referência do Raspberry Pi 3 B+.

Para saber como estender a sua solução de IoT e agendar chamadas de método em vários dispositivos, consulte Agendar e difundir trabalhos.

Introdução ao gerenciamento de dispositivos (.NET)

Pré-requisitos

Criar um aplicativo de dispositivo com um método direto

Obter a cadeia de conexão do hub IoT

Criar um aplicativo de serviço para disparar uma reinicialização

Executar os aplicativos

Personalizar e estender as ações de gerenciamento do dispositivo

Janelas de manutenção do dispositivo

Próximas etapas

Recursos adicionais