Tutorial: Desenvolver módulos IoT Edge usando Visual Studio Code

  • Artigo

Aplica-se a:IoT Edge 1.4 checkmark IoT Edge 1.4

Importante

A versão com suporte é a IoT Edge 1.4. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Este tutorial explica como desenvolver e implantar seu código em um dispositivo do IoT Edge. Use os módulos do Azure IoT Edge para implantar um código que implementa a lógica de negócios diretamente em seus dispositivos IoT Edge. No início rápido Implantar código em um dispositivo Linux, você criou um dispositivo do IoT Edge e implantou um módulo do Azure Marketplace.

Este artigo inclui etapas para duas ferramentas de desenvolvimento IoT Edge.

  • Ferramenta de Desenvolvimento do Azure IoT Edge para linha de comando (CLI). Essa ferramenta é preferencial para desenvolvimento.
  • Extensão do Azure IoT Edge Tools para Visual Studio Code. A extensão está no modo de manutenção.

Use o botão seletor de ferramentas no início deste artigo para selecionar a versão da ferramenta.

Neste tutorial, você aprenderá como:

  • Configurar seu computador de desenvolvimento.
  • Usar as ferramentas do IoT Edge para criar um projeto.
  • Criar seu projeto como um contêiner do Docker e armazená-lo em um registro de contêiner do Azure.
  • Implantar seu código em um dispositivo IoT Edge.

O módulo IoT Edge criado neste tutorial filtra os dados de temperatura que seu dispositivo gera. Ele somente envia mensagens upstream se a temperatura estiver acima de um limite especificado. Esse tipo de análise na borda é útil para reduzir a quantidade de dados que é comunicada e armazenada na nuvem.

Pré-requisitos

Um computador de desenvolvimento:

  • Use seu computador ou uma máquina virtual.
  • Seu computador de desenvolvimento deve dar suporte à virtualização aninhada para executar um mecanismo de contêiner.
  • A maioria dos sistemas operacionais que pode executar um mecanismo de contêiner pode ser usada para desenvolver módulos do IoT Edge para dispositivos Linux. Este tutorial usa um computador Windows, mas indica diferenças conhecidas no macOS ou no Linux.
  • Instalar o Visual Studio Code
  • Instale a CLI do Azure.

Um dispositivo do Azure IoT Edge:

Recursos de nuvem:

  • Um hub IoT gratuito ou de camada padrão no Azure.

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

Dica

Para obter diretrizes sobre a depuração interativa no Visual Studio Code ou no Visual Studio 2022:

Este tutorial ensina as etapas de desenvolvimento para o Visual Studio Code.

Principais conceitos

Este tutorial explica o desenvolvimento de um módulo do IoT Edge. Um módulo do IoT Edge é um contêiner com código executável. É possível implantar um ou mais módulos em um dispositivo IoT Edge. Módulos executam tarefas específicas, como ingerir dados de sensores, limpar e analisar dados ou enviar mensagens a um hub IoT. Para saber mais, confira Understand Azure IoT Edge modules (Noções básicas sobre módulos do Azure IoT Edge).

Ao desenvolver módulos do IoT Edge, é importante entender a diferença entre o computador de desenvolvimento e o dispositivo do IoT Edge de destino em que o módulo é implantado. O contêiner que você criar para armazenar seu código de módulo deverá corresponder ao SO (sistema operacional) do dispositivo de destino. Por exemplo, o cenário mais comum é alguém desenvolver um módulo em um computador Windows com a intenção de direcionar um dispositivo Linux que executa o IoT Edge. Nesse caso, o sistema operacional do contêiner seria Linux. Ao percorrer este tutorial, lembre-se a diferença entre o sistema operacional do computador de desenvolvimento e o sistema operacional do contêiner.

Dica

Se você estiver usando o IoT Edge para Linux no Windows, o dispositivo de destino em seu cenário será a máquina virtual Linux, não o host do Windows.

Este tutorial tem como destino dispositivos que executam o IoT Edge com contêineres Linux. É possível usar o sistema operacional de sua preferência, contanto que o computador de desenvolvimento execute contêineres do Linux. É recomendável usar o Visual Studio Code para desenvolver com contêineres Linux, portanto, é isso que o tutorial usará. É possível usar o Visual Studio também, embora haja diferenças no suporte entre as duas ferramentas.

A tabela a seguir lista os cenários de desenvolvimento compatíveis para contêineres do Linux no Visual Studio Code e no Visual Studio.

Visual Studio Code Visual Studio 2019/2022
Arquitetura de dispositivo do Linux Linux AMD64
Linux ARM32v7
Linux ARM64		 Linux AMD64
Linux ARM32
Linux ARM64
Serviços do Azure Verificação de
Azure Stream Analytics
Azure Machine Learning
Idiomas C
C#
Java
Node.js
Python		 C
C#
Mais informações Azure IoT Edge para Visual Studio Code Ferramentas do Azure IoT Edge para Visual Studio 2019
Azure IoT Edge Tools para Visual Studio 2022

Instalar o mecanismo de contêiner

Os módulos do IoT Edge são empacotados como contêineres, portanto, você precisa de um sistema de gerenciamento de contêiner compatível com o Docker no computador de desenvolvimento para criar e gerenciá-los. Recomendamos o Docker Desktop para desenvolvimento devido à sua popularidade e ao seu suporte a recursos. O Docker Desktop no Windows permite alternar entre contêineres do Linux e do Windows para poder desenvolver módulos para tipos diferentes de dispositivos do IoT Edge.

Use a documentação do Docker para instalar em seu computador de desenvolvimento:

  • Instalar o Docker Desktop para Windows

    • Quando instala o Docker Desktop para Windows, você é solicitado se deseja usar os contêineres do Linux ou do Windows. Você pode alterar essa decisão a qualquer momento. Para este tutorial, usaremos contêineres do Linux, porque nossos módulos estão direcionando dispositivos Linux. Para saber mais, confira Switch between Windows and Linux containers (Alternar entre contêineres do Windows e do Linux).

  • Instalar o Docker Desktop para Mac

  • Leia Sobre o Docker CE para obter informações sobre a instalação em várias plataformas do Linux.

    • Para o WSL (Subsistema do Windows para Linux), instale o Docker Desktop para Windows.

Configurar ferramentas

Instale a Ferramenta de Desenvolvimento do Azure IoT Edge baseada em Python para criar a solução do IoT Edge. Há duas opções:

Importante

A extensão das Ferramentas de Azure IoT Edge para Visual Studio Code está em modo de manutenção. A ferramenta de desenvolvimento recomendada é a Ferramenta de Desenvolvimento do Azure IoT Edge para linha de comando (CLI).

Use as extensões da IoT para o Visual Studio Code desenvolver módulos do IoT Edge. Essas extensões oferecem modelos de projeto, automatizam a criação do manifesto de implantação e permite que você monitore e gerencie dispositivos do IoT Edge. Nesta seção, você instalará o Visual Studio Code e a extensão IoT; em seguida, configurará sua conta do Azure para gerenciar recursos do Hub IoT de dentro do Visual Studio Code.

  1. Instale a extensão do Azure IoT Edge.

  2. Instalar a extensão do Hub IoT do Azure.

  3. Depois de instalar as extensões, abra a paleta de comandos selecionando Exibir>Paleta de Comandos.

  4. Na paleta de comandos novamente, pesquise e selecione Hub IoT do Azure: selecionar Hub IoT. Siga os prompts para selecionar sua assinatura e o Hub IoT do Azure.

  5. Abra a seção do gerenciador do Visual Studio Code selecionando o ícone na barra de atividades à esquerda ou selecionando Exibir>Explorer.

  6. Na parte inferior da seção do Explorer, expanda o menu Hub IoT do Azure / Dispositivos recolhido. Você deverá os dispositivos e os dispositivos do IoT Edge associados ao Hub IoT selecionados por meio da paleta de comandos.

Instalar ferramentas específicas da linguagem

Instale as ferramentas específicos da linguagem que você está usando para o desenvolvimento:

Criar um registro de contêiner

Neste tutorial, você usa as extensões do Azure IoT Edge e do Hub IoT do Azure para compilar um módulo e criar uma imagem de contêiner dos arquivos. Em seguida, você efetua push dessa imagem para um registro que armazena e gerencia suas imagens. Finalmente, você implanta a imagem do seu registro para executar no dispositivo IoT Edge.

Importante

A extensão do Visual Studio Code do Azure IoT Edge está em modo de manutenção.

Você pode usar qualquer registro compatível com o Docker para manter as imagens de contêiner. Dois serviços de registro populares do Docker são o Registro de Contêiner do Azure e o Hub do Docker. Este tutorial utiliza o Registro de Contêiner do Azure.

Caso ainda não tenha um registro de contêiner, siga estas etapas para criar um novo no Azure:

  1. No portal do Azure, selecione Criar um recurso>Contêineres>Registro de Contêiner.

  2. Forneça os seguintes valores obrigatórios para criar seu registro de contêiner:

    Campo Valor
    Subscription Selecione uma assinatura na lista suspensa.
    Resource group Use o mesmo grupo de recursos para todos os recursos de teste criados durante os tutoriais e inícios rápidos do IoT Edge. Por exemplo, IoTEdgeResources.
    Nome do registro Forneça um nome exclusivo.
    Location Escolha um local perto de você.
    SKU Selecione Basic.

  3. Selecione Examinar + criar, depois Criar.

  4. Selecione seu novo registro de contêiner na seção Recursos da página inicial do portal do Azure para abri-lo.

  5. No painel esquerdo do registro de contêiner, selecione Chaves de acesso no menu localizado em Configurações.

    Screenshot of the Access Keys menu location.

  6. Habilite Usuário administrador com o botão de alternância e exiba o Nome de usuário e a Senha do seu registro de contêiner.

  7. Copie os valores para Servidor de logon, Nome de usuário e Senha e salve-os em um local conveniente. É possível usar esses valores neste tutorial para fornecer acesso ao registro de contêiner.

Criar um projeto de módulo

A extensão do Azure IoT Edge oferece modelos de projeto para todas as linguagens de módulo do IoT Edge compatíveis com o Visual Studio Code. Todos esses modelos têm os arquivos e o código nos quais você precisa implantar um módulo de trabalho para testar o IoT Edge ou oferecem a você um ponto de partida para personalizar o modelo com sua própria lógica de negócios.

Criar um modelo de projeto

A Ferramenta de Desenvolvimento do IoT Edge simplifica o desenvolvimento do Azure IoT Edge com comandos controlados por variáveis de ambiente. Ela começa o desenvolvimento do IoT Edge com o contêiner de Desenvolvimento do IoT Edge e a solução de scaffolding do IoT Edge que contém um módulo padrão e todos os arquivos de configuração necessários.

  1. Crie um diretório para sua solução com o caminho de sua preferência. Altere para o diretório iotedgesolution.

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

  2. Use o comando iotedgedev solution init para criar uma solução e configurar o Hub IoT do Azure na linguagem de programação de sua preferência.

    iotedgedev solution init --template csharp

O script iotedgedev solution init solicita que você conclua várias etapas, incluindo:

  • Autenticar no Azure
  • Escolher uma assinatura do Azure
  • Escolher ou criar um grupo de recursos
  • Escolher ou criar um Hub IoT do Azure
  • Escolher ou criar um dispositivo Azure IoT Edge

Use o Visual Studio Code e a extensão do Azure IoT Edge. Você começa criando uma solução e, em seguida, gerando o primeiro módulo nessa solução. Cada solução pode conter vários módulos.

  1. Selecione Exibir>Paleta de Comandos.
  2. Na paleta de comandos, insira e execute o comando Azure IoT Edge: New IoT Edge Solution.
  3. Navegue até a pasta em que você deseja criar a nova solução e selecione Selecionar pasta.
  4. Digite um nome para a solução.
  5. Selecione um modelo de módulo para sua linguagem de desenvolvimento preferida para ser o primeiro módulo na solução.
  6. Digite um nome para o módulo. Escolha um nome exclusivo no registro de contêiner.
  7. Forneça o nome do repositório de imagens do módulo. O Visual Studio Code preenche automaticamente o nome do módulo com localhost:5000/<nome do seu módulo>. Substitua-o pelas informações de seu registro. Use localhost se você usa um registro local do Docker para testes. Se usar o Registro de Contêiner do Azure, utilize o Servidor de logon nas configurações do registro. O servidor de entrada é semelhante ao <nome de registro>.azurecr.io. Apenas substitua a parte da cadeia de caracteres localhost:5000 para que o resultado final se pareça com *<nome do registro>.azurecr.io/<nome do seu módulo>.

O Visual Studio Code usa as informações fornecidas, cria uma solução do IoT Edge e, em seguida, a carrega em uma nova janela.

Após a criação da solução, esses arquivos principais estão na solução:

  • Uma pasta .vscode contendo arquivo de configuração launch.json.

  • Uma pasta módulos com subpastas para cada módulo. Dentro da subpasta de cada módulo o arquivo module.json controla como os módulos são criados e implantados.

  • Um arquivo .env lista as variáveis de ambiente. A variável de ambiente do registro de contêiner é localhost:5000 por padrão.

  • Dois arquivos de implantação de módulo chamados deployment.template.json e deployment.debug.template.json listam os módulos a serem implantados no dispositivo. Por padrão, a lista inclui os módulos do sistema do IoT Edge (edgeAgent e edgeHub) e módulos de exemplo, como:

    Observação

    Os módulos exatos instalados podem depender da linguagem escolhida.

Definir versão de runtime do IoT Edge

A versão mais recente e estável do módulo do sistema de IoT Edge é a 1.4. Defina os módulos do sistema para a versão 1.4.

  1. No Visual Studio Code, abra o arquivo de manifesto de implantação deployment.template.json. O manifesto de implantação é um documento JSON que descreve os módulos a serem configurados nos dispositivos IoT Edge de destino.

  2. Altere a versão de runtime das imagens do módulo de runtime do sistema edgeAgent e edgeHub. Por exemplo, se você quiser usar o runtime do IoT Edge versão 1.4, altere as seguintes linhas no arquivo de manifesto de implantação:

    "systemModules": {
    "edgeAgent": {

        "image": "mcr.microsoft.com/azureiotedge-agent:1.4",

    "edgeHub": {

        "image": "mcr.microsoft.com/azureiotedge-hub:1.4",

Forneça suas credenciais de Registro para o agente do IoT Edge

O arquivo do ambiente armazena as credenciais para o registro de contêiner e as compartilha com o runtime do IoT Edge. O runtime precisa dessas credenciais para efetuar pull de suas imagens de contêiner para o dispositivo IoT Edge.

A extensão do IoT Edge tenta efetuar pull de suas credenciais de Registro de Contêiner do Azure e as popula no arquivo de ambiente.

Observação

O arquivo de ambiente será criado somente se você fornecer um repositório de imagens para o módulo. Se você aceitou os padrões do localhost para testar e depurar localmente, não será necessário declarar variáveis de ambiente.

Verifique se suas credenciais já existem. Caso contrário, adicione-as agora:

  1. Se o Registro de Contêiner do Azure for seu registro, configure um nome de usuário e uma senha do Registro de Contêiner do Azure. Obtenha esses valores no menu Configurações>Chaves de acesso do registro de contêiner no portal do Azure.

  2. Abra o arquivo .env em sua solução de módulo.

  3. Adicione os valores nome de usuário e senha que você copiou do Registro de Contêiner do Azure. Por exemplo:

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

  4. Salve suas alterações no arquivo .env.

Observação

Este tutorial usa as credenciais de logon do administrador do Registro de Contêiner do Azure que são convenientes para cenários de desenvolvimento e teste. Se você está pronto para cenários de produção, recomendamos uma opção de autenticação de privilégios mínimos, como entidades de serviço ou tokens com escopo de repositório. Para obter mais informações, confira Gerenciar o acesso ao registro de contêiner.

Arquitetura de destino

É necessário selecionar a arquitetura que você deseja usar para cada solução, porque isso afeta como o contêiner é criado e executado. O padrão é o Linux AMD64. Para este tutorial, estamos usando uma máquina virtual Ubuntu como o dispositivo do IoT Edge, portanto, manteremos o amd64 padrão.

Se você precisar alterar a arquitetura de destino para sua solução, use as etapas a seguir.

  1. Abra a paleta de comandos e pesquise Azure IoT Edge: definir a plataforma de destino padrão para a solução Edge ou selecione o ícone de atalho na barra lateral na parte inferior da janela.

  2. Na paleta de comandos, selecione a arquitetura de destino na lista de opções.

A arquitetura de destino é definida quando você cria a imagem de contêiner em uma etapa posterior.

Atualizar o módulo com código personalizado

Cada modelo inclui código de exemplo que usa dados simulados de sensor do módulo SimulatedTemperatureSensor e os encaminha ao hub IoT. O módulo de exemplo recebe mensagens e as passa adiante. A funcionalidade de pipeline demonstra um conceito importante no IoT Edge, que é como os módulos comunicam-se uns com os outros.

Cada módulo pode ter várias filas de entrada e de saída declaradas em seu código. O hub do IoT Edge em execução no dispositivo roteia mensagens da saída de um módulo para a entrada de um ou mais módulos. O código específico para declarar entradas e saídas varia entre as linguagens, mas o conceito é o mesmo em todos os módulos. Para saber mais sobre o roteamento entre módulos, confira Declarar rotas.

O código de exemplo C# que vem com o modelo de projeto usa a classe ModuleClient do SDK do Hub IoT para .NET.

  1. No explorador do Visual Studio Code, abra módulos>filtermodule>ModuleBackgroundService.cs.

  2. Antes do namespace filtermodule, adicione três instruções using aos tipos usados posteriormente:

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

  3. Adicione a variável temperatureThreshold à classe ModuleBackgroundService. Essa variável define o valor que a temperatura medida deve exceder para que os dados sejam enviados ao hub IoT.

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

  4. Adicione as classes MessageBody, Machine e Ambient. 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;}
}

  5. Localize a função ExecuteAsync. Essa função cria e configura um objeto ModuleClient, que permite que o módulo se conecte ao runtime do Azure IoT Edge para enviar e receber mensagens. Depois de criar o ModuleClient, o código lê o valor temperatureThreshold das propriedades desejadas do módulo gêmeo. O código registra um retorno de chamada para receber mensagens de um hub do IoT Edge por meio de um ponto de extremidade chamado input1.

    Substitua a chamada para o método ProcessMessageAsync por uma nova que atualiza o nome do ponto de extremidade e o método que é chamado quando a entrada é recebida. Além disso, adicione um método SetDesiredPropertyUpdateCallbackAsync para obter atualizações nas propriedades desejadas. Para fazer essa alteração, substitua a última linha do método ExecuteAsync pelo seguinte código:

    // 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. Adicione o método onDesiredPropertiesUpdate à classe ModuleBackgroundService. Este método recebe atualizações sobre as 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;
}

  7. Adicione o método FilterMessages. Esse método é chamado sempre que o módulo recebe uma mensagem do hub do IoT Edge. Ele filtra as mensagens que reportam temperaturas abaixo do limite de temperatura definido através do módulo gêmeo. Ele também adiciona a propriedade MessageType à mensagem com o valor definido para Alerta.

    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. Salve o arquivo ModuleBackgroundService.cs.

  9. No explorador do Visual Studio Code, abra o arquivo deployment.template.json no workspace da solução IoT Edge.

  10. Como alteramos o nome do ponto de extremidade que o módulo escuta, também precisamos atualizar as rotas no manifesto de implantação para que o edgeHub envie mensagens para o novo ponto de extremidade.

    Localize a seção rotas no módulo gêmeo $edgeHub. Atualize a rota sensorTofiltermodule para substituir input1 por inputFromSensor:

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

  11. Adicione o módulo gêmeo filtermodule ao manifesto de implantação. Insira o seguinte conteúdo JSON na parte inferior da seção modulesContent, após o módulo gêmeo do $edgeHub:

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

  12. Salve o arquivo deployment.template.json.

Compilar e enviar por push sua solução

Você atualizou o código do módulo e o modelo de implantação para ajudar na compreensão de alguns conceitos importantes de implantação. Agora você está pronto para criar a imagem de contêiner do módulo e efetuar push dela para seu registro de contêiner.

No Visual Studio Code, abra o arquivo de manifesto de implantação deployment.template.json. O manifesto de implantação descreve os módulos a serem configurados no dispositivo do IoT Edge de destino. Antes da implantação, você precisa atualizar as credenciais do Registro de Contêiner do Azure e as imagens de módulo com os valores de createOptions adequados. Para obter mais informações sobre os valores de createOption, confira Como configurar opções de criação de contêiner para módulos do IoT Edge.

Se você estiver usando um Registro de Contêiner do Azure para armazenar sua imagem de módulo, adicione suas credenciais à seção modulesContent>edgeAgent>configurações>registryCredentials em deployment.template.json. Substitua myacr pelo seu próprio nome de registro e forneça sua senha e endereço do Servidor de logon. Por exemplo:

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

Adicione ou substitua o seguinte conteúdo com cadeia de caracteres ao valor createOptions para cada sistema (edgeHub e edgeAgent) e módulo personalizado (filtermodule e tempSensor) listado. Se necessário, mude os valores.

"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

Por exemplo a configuração filtermodule deve ser semelhante 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\"}]}}}"
}

Criar imagem do Docker do módulo

Abra o terminal integrado do Visual Studio Code selecionando Terminal>Novo Terminal.

Use o comando dotnet publish para compilar a imagem de contêiner para a arquitetura Linux e amd64. Mude o diretório para o diretório filtermodule no seu projeto e execute o comando dotnet publish.

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

No momento, o modelo de ferramenta iotedgedevestá configurado para .NET 7.0. Se desejar usar uma versão diferente do .NET, você pode editar o arquivo filtermodule.csproj e modificar os valores TargetFramework e PackageReference. Por exemplo, para direcionar o .NET 8.0, seu arquivo filtermodule.csproj deve parecer com isso:

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

Marque a imagem do Docker com as informações, versão e arquitetura do registro de contêiner. Substitua myacr pelo seu próprio nome de registro.

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

Enviar por push a imagem do Docker do módulo

Forneça suas credenciais de registro de contêiner para o Docker para que ele possa efetuar push de sua imagem de contêiner para ser armazenada no registro.

  1. Entre no Docker com as credenciais do Registro de Contêiner do Azure (ACR).

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

    Talvez você receba um aviso de segurança recomendando usar --password-stdin. Embora essa melhor prática seja recomendada para cenários de produção, ela não serve para este tutorial. Para saber mais, confira a referência de logon do docker.

  2. Entre no Registro de Contêiner do Azure. Você precisa instalar a CLI do Azure para usar o comando az. Esse comando solicita o nome de usuário e a senha encontrados no registro de contêiner em Configurações>Chaves de acesso.

    az acr login -n <ACR registry name>

    Dica

    Se você fizer logon em qualquer momento nesse tutorial, repita as etapas acima de entrada do Docker e do Registro de Contêiner do Azure para continuar.

  3. Efetue push da imagem do módulo para o registro local ou para um registro de contêiner.

    docker push <ImageName>

    Por exemplo:

    # 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

Atualizar o modelo de implantação

Atualize o modelo de implantação deployment.template.json com o local da imagem do registro de contêiner. Por exemplo, se você estiver usando um Registro de Contêiner do Azure myacr.azurecr.io e sua imagem for filtermodule:0.0.1-amd64, atualize a configuração filtermodule para:

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

No gerenciador do Visual Studio Code, clique com o botão direito do mouse no arquivo deployment.template.json e selecione Criar e efetuar push da solução IoT Edge.

O comando de criação e de envio por push inicia três operações. Primeiro, é criada uma pasta na solução denominada config que contém o manifesto de implantação completo, criado com base nas informações do modelo de implantação e em outros arquivos da solução. Depois, ele executa docker build para montar a imagem de contêiner com base no dockerfile apropriado para sua arquitetura de destino. Por fim, ele executa docker push para enviar por push o repositório de imagens para seu registro de contêiner.

Esse processo pode levar vários minutos na primeira vez, mas será mais rápido na próxima vez em que você executar os comandos.

Opcional: atualizar o módulo e a imagem

Se você fizer alterações no código do módulo, precisará recompilar e enviar a imagem do módulo por push para o registro de contêiner. Use as etapas nesta seção para atualizar a compilação e a imagem de contêiner. Você poderá ignorar esta seção se não tiver feito nenhuma alteração no código do módulo.

Abra o arquivo deployment.amd64.json na pasta de configuração recém-criada. O nome do arquivo reflete a arquitetura de destino; portanto, ele será diferente se você escolher uma arquitetura diferente.

Observe que os dois parâmetros que têm espaços reservados agora são contém seus valores adequados. A seção registryCredentials tem o nome de usuário e a senha do seu registro extraídos do arquivo .env. O filtermodule tem o repositório de imagens completo com o nome, a versão e a marca de arquitetura do arquivo module.json.

  1. Abra o arquivo module.json na pasta filtermodule.

  2. Altere o número de versão da imagem de módulo. Por exemplo, incremente o número de versão de patch para "version": "0.0.2" como se você tivesse feito uma pequena correção no código do módulo.

    Dica

    As versões de módulo permitem o controle de versão e que você teste alterações em um pequeno conjunto de dispositivos antes de implantar atualizações em produção. Se você não incrementar a versão de módulo antes de criar e efetuar push, então você substituirá o repositório em seu registro de contêiner.

  3. Salve as alterações no arquivo module.json.

Crie e efetue push da imagem atualizada com uma marca de versão 0.0.2. Por exemplo, para criar e efetuar push da imagem do registro local ou de um registro de contêiner do Azure, use os seguintes 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

Clique com o botão direito do mouse no arquivo deployment.template.json e selecione novamente Criar e efetuar push da solução IoT Edge.

Abra o arquivo deployment.amd64.json novamente. Observe que o sistema de build não cria um novo arquivo ao executar o comando build e efetuar push novamente. Em vez disso, o mesmo arquivo foi atualizado para refletir as alterações. Agora a imagem filtermodule aponta para a versão 0.0.2 do contêiner.

Para verificar ainda mais o que o comando de criação e de envio por push fez, acesse o portal do Azure e navegue até o registro de contêiner.

No registro de contêiner, selecione Repositórios e, sem seguida, filtermodule. Verifique se as duas versões da imagem foram enviadas por push para o registro.

Screenshot of where to view both image versions in your container registry.

Solucionar problemas

Se encontrar erros ao criar e enviar sua imagem de módulo por push, isso geralmente estará relacionado à configuração do Docker em seu computador de desenvolvimento. Use as seguintes verificações para examinar sua configuração:

  • Você executou o comando docker login usando as credenciais que copiou do seu registro de contêiner? Essas credenciais são diferentes daquelas que você usa para entrar no Azure.
  • Seu repositório de contêiner está correto? Ele tem seu nome de registro de contêiner correto e seu nome de módulo correto? Abra o arquivo module.json na pasta filtermodule para verificar. O valor do repositório deve ter a aparência de <nome do Registro>.azurecr.io/filtermodule.
  • Se você usou um nome diferente de filtermodule para o seu módulo, esse nome está consistente em toda a solução?
  • Seu computador está executando o mesmo tipo de contêineres que você está criando? Este tutorial é para dispositivos IoT Edge do Linux; portanto, o Visual Studio Code deve informar amd64 ou arm32v7 na barra lateral e o Docker Desktop deve estar executando contêineres do Linux.

Implantar módulos no dispositivo

Você verificou que as imagens de contêineres criadas estão armazenadas em seu registro de contêiner; portanto, chegou a hora de implantá-las em um dispositivo. Verifique se seu dispositivo IoT Edge está em funcionamento.

Use o comando IoT Edge Azure CLI set-modules para implantar os módulos no Hub IoT do Azure. Por exemplo, para implantar os módulos definidos no arquivo deployment.template.json no Hub IoT my-iot-hub do dispositivo do IoT Edge my-device, use o seguinte comando. Substitua os valores de nome do hub, id do dispositivo e logon Hub IoT cadeia de conexão por sua própria.

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

Dica

Você pode encontrar seu Hub IoT cadeia de conexão, incluindo a chave de acesso compartilhado no portal do Azure. Acesse as >Configurações de segurança>Políticas de acesso compartilhado>iothubowner no Hub IoT.

  1. No gerenciador do Visual Studio Code, na seção Hub IoT do Azure, expanda Dispositivos para ver sua lista de dispositivos IoT.

  2. Clique com o botão direito do mouse no dispositivo IoT Edge no qual você deseja implantar e selecione Criar implantação para um único dispositivo.

  3. No explorador de arquivos, navegue até a pasta config e selecione o arquivo deployment.amd64.json.

    Não use o arquivo deployment.template.json, que não tem as credenciais de registro de contêiner ou os valores de imagem de módulo nele. Se você direcionar um dispositivo Linux ARM32, o nome do manifesto de implantação será deployment.arm32v7.json.

  4. No dispositivo, expanda Módulos para ver uma lista de módulos implantados e em execução. Selecione o botão Atualizar. Você deve ver os novos módulos tempSensor e filtermodule em execução em seu dispositivo.

    Os módulos podem demorar alguns minutos para iniciar. O runtime do IoT Edge precisa receber seu novo manifesto de implantação, obter as imagens de módulo do runtime do contêiner e iniciar cada novo módulo.

Exibir mensagens do dispositivo

O código de módulo de exemplo recebe mensagens por meio de sua fila de entrada e as passa adiante por meio de sua fila de saída. O manifesto de implantação declarou rotas que passavam mensagens para filtermodule de tempSensor e, em seguida, encaminhava mensagens de filtermodule para o Hub IoT. As extensões do Azure IoT Edge e do Hub IoT do Azure permitem que você veja mensagens à medida que elas chegam ao Hub IoT dos dispositivos individuais.

  1. No gerenciador do Visual Studio Code, clique com o botão direito do mouse no dispositivo IoT Edge que deseja monitorar e, em seguida, selecione Iniciar o Monitoramento do Ponto de Extremidade de Evento Interno.

  2. Observe a janela de Saída no Visual Studio Code para ver as mensagens chegando em seu hub IoT.

    Screenshot showing where to view incoming device to cloud messages.

Exibir alterações no dispositivo

Se desejar ver o que está acontecendo no seu próprio dispositivo, use os comandos nesta seção para inspecionar o runtime do IoT Edge e os módulos em execução em seu dispositivo.

Os comandos nesta seção são para seu dispositivo IoT Edge, não para seu computador de desenvolvimento. Se estiver usando uma máquina virtual para seu dispositivo IoT Edge, conecte-se a ela agora. No Azure, acesse a página de visão geral da máquina virtual e selecione Conectar para acessar a conexão de shell segura.

  • Exiba todos os módulos implantados em seu dispositivo e verifique seu status:

    iotedge list

    Você deverá ver quatro módulos: os dois módulos de runtime do IoT Edge, o tempSensor e o filtermodule. Todos os quatro devem estar listados como em execução.

  • Inspecione os logs para ver se há um módulo específico:

    iotedge logs <module name>

    Os módulos do IoT Edge diferenciam maiúsculas de minúsculas.

    Os logs de tempSensor e filtermodule devem mostrar as mensagens que estão processando. O módulo edgeAgent é responsável por iniciar os outros módulos, portanto seus logs terão informações sobre como implementar o manifesto de implantação. Se você encontrar um módulo não listado ou não estiver em execução, os logs do edgeAgent provavelmente terão os erros. O módulo edgeHub é responsável pelas comunicações entre os módulos e o Hub IoT. Se os módulos estiverem em execução, mas as mensagens não estiverem chegando ao seu Hub IoT, os logs do edgeHub provavelmente terão erros.

Limpar os recursos

Se você pretende continuar no próximo artigo recomendado, pode manter os recursos e as configurações já criados e reutilizá-los. Você também pode continuar usando o mesmo dispositivo IoT Edge como um dispositivo de teste.

Caso contrário, é possível excluir as configurações locais e os recursos do Azure usados neste artigo para evitar encargos.

Excluir recursos do Azure

A exclusão de recursos do Azure e dos grupos de recursos é irreversível. Não exclua acidentalmente grupo de recursos ou recursos incorretos. 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:

  1. Entre no portal do Azure e selecione Grupos de recursos.

  2. Selecione o nome do grupo de recursos que contém os recursos de teste do IoT Edge.

  3. Examine a lista de recursos contidos no grupo de recursos. Se você deseja 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ê configurou o Visual Studio Code em seu computador de desenvolvimento e implantou seu primeiro módulo do IoT Edge que contém código para filtrar dados brutos gerados pelo dispositivo do IoT Edge.

É possível passar para os próximos tutoriais para saber como o Azure IoT Edge pode ajudar você a implantar os serviços de nuvem do Azure para processar e analisar dados na borda.

Depurar módulos do Azure IoT EdgeFunctionsStream AnalyticsServiço de Visão Personalizada