Tutorial: Desenvolver módulos do IoT Edge em C# usando contêineres do Windows

Aplica-se a: IoT Edge 1.1

Importante

A data de término do suporte do IoT Edge 1.1 foi em 13 de dezembro de 2022. Verifique o ciclo de vida do produto microsoft para obter informações sobre como este produto, serviço, tecnologia ou API tem suporte. Para obter mais informações sobre como atualizar para a versão mais recente do IoT Edge, consulte Atualizar o IoT Edge.

Este artigo mostra como usar o Visual Studio para desenvolver código C# e implantá-lo em um dispositivo Windows que executa o Azure IoT Edge.

Observação

O IoT Edge 1.1 LTS é o último canal de lançamento que dá suporte a contêineres do Windows. A partir da versão 1.2, não há suporte para contêineres do Windows. Considere usar ou migrar para o IoT Edge para Linux no Windows para executar o IoT Edge em dispositivos com Windows.

Você pode usar módulos do Azure IoT Edge para implantar código que implementa sua lógica de negócios diretamente em seus dispositivos do IoT Edge. Este tutorial explica como criar e implantar um módulo do IoT Edge que filtra os dados do sensor.

Neste tutorial, você aprenderá como:

Use o Visual Studio para criar um módulo do IoT Edge baseado no SDK do C#.
Use o Visual Studio e o Docker para criar uma imagem do Docker e publicá-la no registro.
Implante o módulo em seu dispositivo IoT Edge.
Exibir dados gerados.

O módulo do IoT Edge criado neste tutorial filtra os dados de temperatura gerados pelo dispositivo. O módulo envia mensagens upstream somente se a temperatura exceder um limite especificado. Este tipo de análise no edge é útil para reduzir a quantidade de dados que são comunicados e armazenados na nuvem.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

Este tutorial demonstra como desenvolver um módulo em C# usando o Visual Studio 2019 e, em seguida, implantá-lo em um dispositivo Windows. Se você estiver desenvolvendo módulos usando contêineres do Linux, vá para Desenvolver módulos do IoT Edge em C# usando contêineres do Linux .

Para entender suas opções de desenvolvimento e implantação de módulos C# usando contêineres do Windows, consulte a seguinte tabela:

C#	Visual Studio Code	Visual Studio 2017 e 2019
Desenvolvimento do Windows AMD64
Depuração do Windows AMD64

Antes de começar este tutorial, configure seu ambiente de desenvolvimento seguindo as instruções no tutorial Develop IoT Edge modules using Windows containers. Depois de concluí-lo, seu ambiente conterá os seguintes pré-requisitos:

Um hub IoT gratuito ou de camada padrão no Azure.
Um dispositivo Windows que está executando o Azure IoT Edge.
Um registro de contêiner, como o Registro de Contêiner do Azure.
Visual Studio 2019, configurado com a extensão ferramentas do Azure IoT Edge .
Docker Desktop, configurado para executar contêineres do Windows.

Dica

Se você estiver usando o Visual Studio 2017 (versão 15.7 ou posterior), baixe e instale as Ferramentas do Azure IoT Edge para Visual Studio 2017 no Visual Studio Marketplace.

Criar um projeto de módulo

Nesta seção, você criará um projeto de módulo do IoT Edge usando o Visual Studio e a extensão ferramentas do Azure IoT Edge. Depois de criar um modelo de projeto, você adicionará um novo código para que o módulo filtre mensagens com base em suas propriedades relatadas.

Criar um novo projeto

As Ferramentas do Azure IoT Edge fornecem modelos de projeto para todas as linguagens de módulo do IoT Edge com suporte no Visual Studio. Esses modelos têm todos os arquivos e código necessários para implantar um módulo de trabalho para testar o IoT Edge. Eles também podem fornecer um ponto de partida para personalizá-los com sua própria lógica de negócios.

Abra o Visual Studio 2019 e selecione Criar Novo Projeto.
No painel Criar um novo projeto, pesquise por IoT Edge e, na lista de resultados, selecione o projeto do Azure IoT Edge (Windows amd64).
Selecione Avançar.

O painel Configurar seu novo projeto é aberto.
No painel Configurar seu novo projeto , renomeie o projeto e a solução para algo mais descritivo, como CSharpTutorialApp.
Selecione Criar para criar o projeto.

O painel Adicionar Módulo é aberto.
Na página Configurar seu novo projeto , faça o seguinte:

um. No painel esquerdo, selecione o modelo do Módulo C# .
b. Na caixa Nome do Módulo , insira CSharpModule.
c. Na caixa Url do Repositório , substitua localhost:5000 pelo valor do servidor de logon do registro de contêiner do Azure, no seguinte formato: <registry name>.azurecr.io/csharpmodule

Observação

Um repositório de imagens inclui o nome do registro de contêiner e o nome da imagem de contêiner. Sua imagem de contêiner é pré-preenchida do valor do nome do projeto do módulo. Você pode recuperar o servidor de logon na página de visão geral do registro de contêiner no portal do Azure.
Selecione Adicionar para criar o projeto.

Adicionar suas credenciais de registro

O manifesto de implantação compartilha as credenciais do registro de contêiner com o runtime do IoT Edge. O runtime precisa dessas credenciais para fazer o download de suas imagens privadas no dispositivo IoT Edge. Use as credenciais da seção chaves de acesso do registro de contêiner do Azure.

No Gerenciador de Soluções do Visual Studio, abra o arquivo deployment.template.json .
Procure a propriedade registroCredenciais nas propriedades desejadas do $edgeAgent. O endereço do Registro da propriedade deve ser preenchido automaticamente com as informações fornecidas quando você criou o projeto. Os campos nome de usuário e senha devem conter nomes de variáveis. Por exemplo:
```
"registryCredentials": {
  "<registry name>": {
    "username": "$CONTAINER_REGISTRY_USERNAME_<registry name>",
    "password": "$CONTAINER_REGISTRY_PASSWORD_<registry name>",
    "address": "<registry name>.azurecr.io"
  }
}
```
Abra o arquivo ENV (ambiente) na solução do módulo. Por padrão, o arquivo está oculto no Gerenciador de Soluções, portanto, talvez seja necessário selecionar o botão Mostrar Todos os Arquivos para exibi-lo. O arquivo ENV deve conter as mesmas variáveis de nome de usuário e senha que você viu no arquivo deployment.template.json .
Adicione os valores nome de usuário e senha do registro de contêiner do Azure.
Salve suas alterações no arquivo ENV.

Atualizar o módulo com código personalizado

O código do módulo padrão recebe mensagens em uma fila de entrada e as passa por uma fila de saída. Vamos adicionar um código adicional para que o módulo processe as mensagens na borda antes de encaminhá-las para o hub IoT. Atualize o módulo para que ele analise os dados de temperatura em cada mensagem e envie a mensagem para o hub IoT somente se a temperatura exceder um determinado limite.

No Visual Studio, selecione CSharpModule>Program.cs.

Na parte superior do namespace CSharpModule , adicione três instruções usando para tipos usados posteriormente:

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

Adicione a variável temperatureThreshold à classe Program após a variável de contador. A variável temperatureThreshold define o valor que a temperatura medida deve exceder para que os dados sejam enviados para o hub IoT.
```
static int temperatureThreshold { get; set; } = 25;
```

Adicione as classes MessageBody, Machine e Ambient à classe Program após as declarações de variável. Essas classes definem o esquema esperado para o corpo de mensagens de entrada.

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;}
}

Procure o método Init. Esse método cria e configura um objeto ModuleClient , que permite que o módulo se conecte ao runtime local do Azure IoT Edge para enviar e receber mensagens. O código também registra um retorno de chamada para receber mensagens de um hub do IoT Edge por meio do endereço input1.

Substitua todo o método Init pelo seguinte código:
```
static async Task Init()
{
    AmqpTransportSettings amqpSetting = new AmqpTransportSettings(TransportType.Amqp_Tcp_Only);
    ITransportSettings[] settings = { amqpSetting };

    // Open a connection to the Edge runtime.
    ModuleClient ioTHubModuleClient = await ModuleClient.CreateFromEnvironmentAsync(settings);
    await ioTHubModuleClient.OpenAsync();
    Console.WriteLine("IoT Hub module client initialized.");

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

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

    // Register a callback for messages that are received by the module.
    await ioTHubModuleClient.SetInputMessageHandlerAsync("input1", FilterMessages, ioTHubModuleClient);
}
```
Esse método Init atualizado ainda configura a conexão com o runtime do IoT Edge com o ModuleClient, mas também adiciona novas funcionalidades. Ele lê as propriedades desejadas do módulo gêmeo para recuperar o valor temperatureThreshold . Em seguida, ele cria um callback que aguarda quaisquer atualizações futuras nas propriedades desejadas do módulo gêmeo. Com este callback, você pode atualizar remotamente o limite de temperatura no módulo twin, e as alterações serão incorporadas ao módulo.

O método Init atualizado também altera o método SetInputMessageHandlerAsync existente. No código de exemplo, as mensagens de entrada na entrada1 são processadas com a função PipeMessage , mas queremos alterá-las para usar a função FilterMessages que criaremos nas etapas a seguir.

Adicione um novo método onDesiredPropertiesUpdate à classe Program . Esse método recebe atualizações nas propriedades desejadas do módulo gêmeo e atualiza a variável temperatureThreshold para corresponder. Todos os módulos possuem seu próprio módulo gêmeo, o que permite configurar o código em execução dentro de um módulo diretamente da nuvem.

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;
}

Remova o método PipeMessage de exemplo e substitua-o por um novo método FilterMessages . Esse método é chamado sempre que o módulo recebe uma mensagem do hub do IoT Edge. Ele filtra mensagens que relatam temperaturas abaixo do limite de temperatura definido por meio do módulo gêmeo. O método também adiciona a propriedade MessageType à mensagem com o valor definido como Alerta.

static 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;
    }
}

Salve o arquivo Program.cs .
Abra o arquivo deployment.template.json em sua solução do IoT Edge. Esse arquivo informa ao agente do IoT Edge quais módulos implantar e informa ao hub do IoT Edge como rotear mensagens entre eles. Aqui, os módulos a serem implantados são SimulatedTemperatureSensor e CSharpModule .
Adicione o módulo gêmeo CSharpModule ao manifesto de implantação. Insira o seguinte conteúdo JSON na parte inferior da modulesContent seção, após o módulo gêmeo $edgeHub:
```
   "CSharpModule": {
       "properties.desired":{
           "TemperatureThreshold":25
       }
   }
```
Salve o arquivo deployment.template.json .

Compilar e enviar por push seu módulo

Na seção anterior, você criou uma solução do IoT Edge e adicionou código para CSharpModule para filtrar mensagens em que a temperatura do computador relatada está abaixo do limite aceitável. Agora você precisa construir a solução como uma imagem de contêiner e enviá-la para o registro de imagens de contêiner.

Use o comando a seguir para entrar no Docker em seu computador de desenvolvimento. Use o nome de usuário, a senha e o servidor de logon do registro de contêiner do Azure. Você pode recuperar esses valores da seção chaves de acesso do seu registro no portal do Azure.
```
docker login -u <ACR username> -p <ACR password> <ACR login server>
```
Você pode receber um aviso de segurança que recomenda o uso de --password-stdin. Embora recomendemos isso como uma prática recomendada para cenários de produção, ele está fora do escopo deste tutorial. Para obter mais informações, consulte a referência de login do docker .

Compilar e enviar por push

No Gerenciador de Soluções do Visual Studio, clique com o botão direito do mouse no nome do projeto que você deseja criar. O nome padrão é AzureIotEdgeApp1 e, como você está criando um módulo do Windows, a extensão deve ser Windows.Amd64.
Selecione Criar e Fazer Push de Módulos do IoT Edge.

O comando build e push inicia três operações:
- Primeiro, cria uma nova pasta na solução chamada configuração , que contém o manifesto de implantação completo. Ele é compilado a partir de informações no modelo de implantação e em outros arquivos de solução.
- Em segundo lugar, ele executa docker build para criar a imagem de contêiner, com base no Dockerfile apropriado para sua arquitetura de destino.
- Por fim, executa-se o docker push para fazer o push do repositório de imagens para o registro de containers.
Esse processo pode levar vários minutos na primeira vez, mas será mais rápido na próxima vez que você executar os comandos.

Implantar módulos no dispositivo

Use o Visual Studio Cloud Explorer e a extensão ferramentas do Azure IoT Edge para implantar o projeto de módulo em seu dispositivo IoT Edge. Você já preparou um manifesto de implantação para seu cenário, o arquivo deployment.windows-amd64.json na pasta de configuração . Agora, tudo o que você precisa fazer é selecionar um dispositivo para receber a implantação.

Verifique se seu dispositivo IoT Edge está em funcionamento.

No Visual Studio Cloud Explorer, expanda os recursos para exibir sua lista de dispositivos IoT.
Clique com o botão direito do mouse no nome do dispositivo IoT Edge que você deseja receber a implantação.
Selecione Criar Implantação.
No Explorador de Arquivos do Visual Studio, selecione o arquivo deployment.windows-amd64.json na pasta de configuração da solução.
Atualize o Cloud Explorer para exibir os módulos implantados listados em seu dispositivo.

Exibir os dados gerados

Depois de aplicar o manifesto de implantação ao dispositivo IoT Edge, o runtime do IoT Edge no dispositivo coletará as novas informações de implantação e começará a ser executado nele. Todos os módulos em execução no dispositivo, mas não incluídos no manifesto de implantação, são interrompidos. Todos os módulos ausentes do dispositivo são iniciados.

Você pode usar a extensão ferramentas do IoT Edge para exibir as mensagens à medida que elas chegam ao hub IoT.

No Visual Studio Cloud Explorer, selecione o nome do dispositivo IoT Edge.
Na lista Ações, selecione Iniciar Monitoramento do Ponto de Extremidade de Eventos Integrados.
Exiba as mensagens que estão chegando ao hub IoT. Pode demorar um pouco para que as mensagens cheguem, pois o dispositivo do IoT Edge precisa receber sua nova implantação e iniciar todos os módulos. As alterações no código CSharpModule devem aguardar até que a temperatura do computador atinja 25 graus antes que as mensagens possam ser enviadas. O código também adiciona o tipo de mensagem de Alerta a qualquer mensagem que atinja esse limite de temperatura.

Editar o módulo gêmeo

Você usou o módulo gêmeo CSharpModule para definir o limite de temperatura em 25 graus. Você pode usar o módulo gêmeo para alterar a funcionalidade sem precisar atualizar o código do módulo.

No Visual Studio, abra o arquivo deployment.windows-amd64.json .

Não abra o arquivo deployment.template. Se você não vir o manifesto de implantação no arquivo de configuração no Gerenciador de Soluções, selecione o ícone Mostrar todos os arquivos na barra de ferramentas do Gerenciador de Soluções.
Procure o gêmeo CSharpModule e altere o valor do parâmetro temperatureThreshold para uma nova temperatura de 5 a 10 graus mais alta do que a temperatura relatada mais recente.
Salve o arquivo deployment.windows-amd64.json .
Siga as instruções de implantação novamente para aplicar o manifesto de implantação atualizado ao seu dispositivo.
Monitore as mensagens de entrada do dispositivo para a nuvem. As mensagens devem parar até que o novo limite de temperatura seja atingido.

Limpar os recursos

Se você planeja continuar para o próximo artigo recomendado, poderá manter e reutilizar os recursos e as configurações que criou neste tutorial. Você também pode continuar usando o mesmo dispositivo IoT Edge como um dispositivo de teste.

Caso contrário, para evitar incorrer em encargos, você pode excluir as configurações locais e os recursos do Azure que você usou aqui.

Excluir recursos do Azure

A exclusão de recursos do Azure e dos grupos de recursos é irreversível. Certifique-se de não excluir acidentalmente o grupo de recursos ou os recursos errados. Se você criou o hub IoT em um grupo de recursos existente que contém recursos que deseja manter, exclua apenas o recurso do hub IoT, não o grupo de recursos.

Para excluir os recursos:

Entre no portal do Azure e selecione Grupos de recursos.
Selecione o nome do grupo de recursos que contém os recursos de teste do IoT Edge.
Examine a lista de recursos contidos em seu grupo de recursos. Se quiser excluir todos eles, selecione Excluir grupo de recursos. Se você quiser excluir apenas alguns deles, clique em cada recurso para excluí-los individualmente.

Próximas etapas

Neste tutorial, você criou um módulo do IoT Edge com código para filtrar dados brutos gerados pelo dispositivo IoT Edge.

Para saber como o Azure IoT Edge pode ajudá-lo a implantar serviços de nuvem do Azure para processar e analisar dados na borda, continue para os próximos tutoriais.

Azure Functions Azure Stream Analytics Azure Machine Learning Serviço de Visão Personalizada

Última atualização em 2020-08-03