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

  • Artigo

Aplica-se a:Marca de verificação do IoT Edge 1.5 IoT Edge 1.5 Marca de verificação do IoT Edge 1.4 IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS são versões suportadas. O IoT Edge 1.4 LTS termina a vida útil em 12 de novembro de 2024. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

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

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

  • Linha de comando (CLI) da Ferramenta de Desenvolvimento do Azure IoT Edge. Esta ferramenta é preferida para o desenvolvimento.
  • Ferramentas do Azure IoT Edge para extensão de código do Visual Studio. A extensão está em 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, irá aprender a:

  • Configure sua máquina de desenvolvimento.
  • Use as ferramentas do IoT Edge para criar um novo projeto.
  • Crie seu projeto como um contêiner do Docker e armazene-o em um registro de contêiner do Azure.
  • Implante seu código em um dispositivo IoT Edge.

O módulo IoT Edge criado neste tutorial filtra os dados de temperatura gerados pelo dispositivo. Envia apenas mensagens de origem caso a temperatura seja superior a um limiar especificado. Este tipo de análise no Edge é útil para reduzir a quantidade de dados que são comunicados e armazenados na cloud.

Pré-requisitos

Uma máquina de desenvolvimento:

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

Um dispositivo Azure IoT Edge:

Recursos da cloud:

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

Gorjeta

Para obter orientações sobre depuração interativa no Visual Studio Code ou Visual Studio 2022:

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

Conceitos-chave

Este tutorial descreve o desenvolvimento de um módulo do IoT Edge. Um módulo IoT Edge é um contêiner com código executável. Você pode implantar um ou mais módulos em um dispositivo IoT Edge. Os módulos executam tarefas específicas, como ingerir dados de sensores, limpar e analisar dados ou enviar mensagens para um hub IoT. Para obter mais informações, consulte Compreender os módulos do Azure IoT Edge.

Ao desenvolver módulos IoT Edge, é importante entender a diferença entre a máquina de desenvolvimento e o dispositivo IoT Edge de destino onde o módulo é implantado. O contêiner que você cria para armazenar o código do módulo deve corresponder ao sistema operacional (SO) do dispositivo de destino. Por exemplo, o cenário mais comum é alguém desenvolvendo um módulo em um computador Windows com a intenção de atingir um dispositivo Linux executando o IoT Edge. Nesse caso, o sistema operacional do contêiner seria o Linux. Ao passar por este tutorial, tenha em mente a diferença entre o sistema operacional da máquina de desenvolvimento e o sistema operacional do contêiner.

Gorjeta

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

Este tutorial destina-se a dispositivos que executam o IoT Edge com contêineres Linux. Você pode usar seu sistema operacional preferido, desde que sua máquina de desenvolvimento execute contêineres Linux. Recomendamos usar o Visual Studio Code para desenvolver com contêineres Linux, então é isso que este tutorial usa. Você também pode usar o Visual Studio, embora haja diferenças no suporte entre as duas ferramentas.

A tabela a seguir lista os cenários de desenvolvimento com suporte para contêineres Linux no Visual Studio Code e Visual Studio.

Visual Studio Code Visual Studio 2019/2022
Arquitetura de dispositivos Linux Linux AMD64
Linux ARM32v7
Linux ARM64		 Linux AMD64
Linux ARM32
Linux ARM64
Serviços do Azure Azure Functions
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
Ferramentas do Azure IoT Edge para Visual Studio 2022

Instalar 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êineres compatível com o Docker em sua máquina de desenvolvimento para criá-los e gerenciá-los. Recomendamos o Docker Desktop para desenvolvimento devido ao seu suporte a recursos e popularidade. O Docker Desktop no Windows permite alternar entre contêineres Linux e Windows para que você possa desenvolver módulos para diferentes tipos de dispositivos IoT Edge.

Use a documentação do Docker para instalar em sua máquina de desenvolvimento:

  • Instalar o Docker Desktop para Windows

    • Ao instalar o Docker Desktop para Windows, você é perguntado se deseja usar contêineres Linux ou Windows. Pode alterar esta decisão a qualquer momento. Para este tutorial, usamos contêineres Linux porque nossos módulos são direcionados a dispositivos Linux. Para obter mais informações, consulte Alternar entre contêineres Windows e Linux.

  • Instalar o Docker Desktop para Mac

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

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

Configurar ferramentas

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

  • Usar o contêiner de desenvolvimento do IoT Edge pré-criado
  • Instale a ferramenta usando a configuração de desenvolvimento iotedgedev

Importante

A extensão de código das ferramentas do Azure IoT Edge para Visual Studio está no modo de manutenção. A ferramenta de desenvolvimento preferida é a linha de comando (CLI) Azure IoT Edge Dev Tool.

Use as extensões IoT para Visual Studio Code para desenvolver módulos IoT Edge. Essas extensões oferecem modelos de projeto, automatizam a criação do manifesto de implantação e permitem monitorar e gerenciar dispositivos IoT Edge. Nesta seção, você instala o Visual Studio Code e a extensão IoT e, em seguida, configura sua conta do Azure para gerenciar recursos do Hub IoT a partir do Visual Studio Code.

  1. Instale a extensão Azure IoT Edge .

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

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

  4. Na paleta de comandos novamente, procure e selecione Hub IoT do Azure: Selecione Hub IoT. Siga as instruções para selecionar sua assinatura do Azure e o Hub IoT.

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

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

Instalar ferramentas específicas do idioma

Instale ferramentas específicas para o idioma que você está desenvolvendo:

Criar um registo de contentores

Neste tutorial, você usa as extensões do Azure IoT Edge e do Hub IoT do Azure para criar um módulo e criar uma imagem de contêiner a partir dos arquivos. Em seguida, vai enviar essa imagem para um registo que armazena e gere as suas imagens. Por fim, vai implementar a imagem a partir do registo para ser executada no seu dispositivo IoT Edge.

Importante

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

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

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

  1. No Portal do Azure, selecione Criar um recurso>Contentores>Registo de Contentor.

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

    Campo Value
    Subscrição Selecione uma subscrição na lista pendente.
    Grupo de recursos 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 de registo Indique um nome exclusivo.
    Location Escolha uma localização perto de si.
    SKU Selecione Básico.

  3. Selecione Rever + criar e, em seguida , Criar.

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

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

    Captura de ecrã da localização do menu Teclas de Acesso.

  6. Habilite o usuário Admin com o botão de alternância e visualize o Nome de usuário e a Senha do registro do contêiner.

  7. Copie os valores para Servidor de login, Nome de usuário e senha e salve-os em algum lugar conveniente. Você usa esses valores ao longo deste tutorial para fornecer acesso ao registro de contêiner.

Criar um novo projeto de módulo

A extensão do Azure IoT Edge oferece modelos de projeto para todas as linguagens de módulo IoT Edge suportadas no Visual Studio Code. Esses modelos têm todos os arquivos e códigos necessários para implantar um módulo de trabalho para testar o IoT Edge ou fornecer um ponto de partida para personalizar o modelo com sua própria lógica de negócios.

Criar um modelo de projeto

A IoT Edge Dev Tool simplifica o desenvolvimento do Azure IoT Edge para comandos orientados por variáveis de ambiente. Ele ajuda você a começar com o desenvolvimento do IoT Edge com o Contêiner de Desenvolvimento do IoT Edge e o andaime da solução IoT Edge que tem 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 escolha. Mude para o seu iotedgesolution diretório.

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

  2. Use o comando iotedgedev solution init para criar uma solução e configurar seu Hub IoT do Azure na linguagem de desenvolvimento de sua escolha.

    iotedgedev solution init --template csharp

O script init da solução iotedgedev solicita que você conclua várias etapas, incluindo:

  • Autenticar no Azure
  • Escolher uma subscrição 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 Azure IoT Edge . Você começa criando uma solução e, em seguida, gerando o primeiro módulo dessa 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 onde deseja criar a nova solução e selecione Selecionar pasta.
  4. Introduza um nome para a sua solução.
  5. Selecione um modelo de módulo para sua linguagem de desenvolvimento preferida para ser o primeiro módulo da solução.
  6. Insira um nome para o módulo. Escolha um nome exclusivo no seu 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/<your module name>. Substitua-o por suas próprias informações de registro. Use localhost se você usar um registro Docker local para teste. Se você usar o Registro de Contêiner do Azure, use o Servidor de Logon nas configurações do Registro. O servidor de início de sessão tem o aspeto <do nome> de registo.azurecr.io. Substitua apenas a parte localhost:5000 da cadeia de caracteres para que o resultado final se <pareça com o nome> do registro.azurecr.io/< nome do módulo.>

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

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

  • Uma pasta .vscode contém o arquivo de configuração launch.json.

  • Uma pasta de módulos que tem 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 suas variáveis de ambiente. A variável de ambiente para o 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 seu dispositivo. Por padrão, a lista inclui os módulos do sistema IoT Edge (edgeAgent e edgeHub) e módulos de exemplo, como:

    Nota

    Os módulos exatos instalados podem depender do idioma de sua escolha.

Definir a versão do tempo de execução do IoT Edge

A última versão estável do módulo do sistema IoT Edge é a 1.5. Defina os módulos do sistema para a versão 1.5.

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

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

    "systemModules": {
    "edgeAgent": {

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

    "edgeHub": {

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

Forneça suas credenciais do Registro ao agente do IoT Edge

O ficheiro de ambiente armazena as credenciais do seu registo de contentor e partilha-as com o runtime do IoT Edge. O tempo de execução precisa dessas credenciais para puxar suas imagens de contêiner para o dispositivo IoT Edge.

A extensão IoT Edge tenta extrair suas credenciais de registro de contêiner do Azure e preenchê-las no arquivo de ambiente.

Nota

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

Verifique se as suas credenciais existem. Se não, adicione-os agora:

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

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

  3. Adicione os valores de nome de usuário e senha que você copiou do seu 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 as alterações no arquivo .env .

Nota

Este tutorial usa credenciais de logon de administrador para o Registro de Contêiner do Azure que são convenientes para cenários de desenvolvimento e teste. Quando estiver 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, consulte Gerenciar o acesso ao registro de contêiner.

Arquitetura de destino

Você precisa selecionar a arquitetura que está segmentando com cada solução, porque isso afeta como o contêiner é criado e executado. O padrão é Linux AMD64. Para este tutorial, estamos usando uma máquina virtual Ubuntu como o dispositivo IoT Edge e mantemos 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 procure Azure IoT Edge: set Default Target Platform for Edge Solution 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.

Módulo de atualização com código personalizado

Cada modelo inclui código de exemplo que pega dados simulados do sensor do módulo SimulatedTemperatureSensor e os encaminha para o hub IoT. O módulo de exemplo recebe mensagens e, em seguida, passa-as adiante. A funcionalidade de pipeline demonstra um conceito importante no IoT Edge, que é como os módulos se comunicam entre si.

Cada módulo pode ter várias filas de entrada e saída declaradas em seu código. O hub 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 idiomas, mas o conceito é o mesmo em todos os módulos. Para obter mais informações sobre roteamento entre módulos, consulte Declarar rotas.

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

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

  2. Antes do namespace filtermodule , adicione três instruções using para tipos que são 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 . Esta variável 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;

  4. Adicione as classes MessageBody, Machine e Ambient . Estas classes definem o esquema esperado para o corpo das mensagens a receber.

    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. Encontre a função ExecuteAsync . Essa função cria e configura um objeto ModuleClient que permite que o módulo se conecte ao tempo de execução local do Azure IoT Edge para enviar e receber mensagens. Depois de criar o ModuleClient, o código lê o valor temperatureThreshold a partir das propriedades pretendidas do módulo duplo. O código registra um retorno de chamada para receber mensagens de um hub IoT Edge por meio de um ponto de extremidade chamado input1.

    Substitua a chamada para o método ProcessMessageAsync por uma nova que atualize o nome do ponto de extremidade e o método que é chamado quando a entrada chega. Além disso, adicione um método SetDesiredPropertyUpdateCallbackAsync para atualizações das propriedades desejadas. Para fazer essa alteração, substitua a última linha do método ExecuteAsync com o 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 nas propriedades pretendidas do módulo duplo e atualiza a variável temperatureThreshold para corresponder. Todos os módulos têm o seu próprio módulo duplo, que lhe permite configurar o código em execução no interior de um módulo diretamente a partir da cloud.

    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 . Este método é chamado sempre que o módulo recebe uma mensagem do hub do IoT Edge. Ele filtra as mensagens que comunicam temperaturas inferiores ao limiar de temperatura definido através do módulo duplo. 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 de códigos do Visual Studio, abra o arquivo de deployment.template.json no espaço de trabalho 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.

    Encontre a secção de rotas no módulo twin $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 twin filtermodule ao manifesto de implantação. Insira o seguinte conteúdo JSON na parte inferior da secção modulesContent, após o módulo duplo $edgeHub:

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

  12. Guarde o ficheiro deployment.template.json.

Crie e impulsione a sua solução

Você atualizou o código do módulo e o modelo de implantação para ajudar a entender alguns dos principais conceitos de implantação. Agora, você está pronto para criar sua imagem de contêiner de módulo e enviá-la para seu registro de contêiner.

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

Se você estiver usando um Registro de Contêiner do Azure para armazenar a imagem do módulo, adicione suas credenciais à seção modulesContent>edgeAgent>settings>registryCredentials no deployment.template.json. Substitua myacr pelo seu próprio nome de registo e forneça a sua palavra-passe e endereço do servidor de início de sessão. Por exemplo:

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

Adicione ou substitua o seguinte conteúdo stringified ao valor createOptions para cada sistema (edgeHub e edgeAgent) e módulo personalizado (filtermodule e tempSensor) listado. Altere os valores, se necessário.

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

Por exemplo, a configuração do módulo de filtro 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\"}]}}}"
}

Imagem do Docker do módulo de compilação

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

Use o dotnet publish comando para criar a imagem de contêiner para a arquitetura Linux e amd64. Altere o diretório para o diretório filtermodule em seu projeto e execute o comando dotnet publishing .

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

Atualmente, o modelo de ferramenta iotedgedev tem como alvo o .NET 7.0. Se você quiser direcionar uma versão diferente do .NET, você pode editar o arquivo filtermodule.csproj e alterar os valores TargetFramework e PackageReference . Por exemplo, para direcionar o .NET 8.0, seu arquivo filtermodule.csproj deve ter esta aparência:

<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, a versão e a arquitetura do registro do contêiner. Substitua myacr pelo seu próprio nome de registo.

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

Imagem do Docker do módulo Push

Forneça suas credenciais de registro de contêiner ao Docker para que ele possa enviar sua imagem de contêiner para armazenamento no registro.

  1. Entre no Docker com as credenciais do Azure Container Registry (ACR).

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

    Poderá receber um aviso de segurança a recomendar a utilização do --password-stdin. Embora essa seja uma prática recomendada para cenários de produção, está fora do escopo deste tutorial. Para obter mais informações, consulte a referência de login do docker.

  2. Entre no Registro de Contêiner do Azure. Você precisa instalar a CLI do Azure para usar o az comando. Este comando solicita o seu nome de utilizador e palavra-passe encontrados no registo do contentor em Definições>de chaves de acesso.

    az acr login -n <ACR registry name>

    Gorjeta

    Se você sair em qualquer momento deste tutorial, repita as etapas de entrada do Docker e do Registro de Contêiner do Azure para continuar.

  3. Envie a 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 do contêiner. Por exemplo, se você estiver usando um myacr.azurecr.io do Registro de Contêiner do Azure e sua imagem for filtermodule:0.0.1-amd64, atualize a configuração do 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 explorador de código do Visual Studio, clique com o botão direito do mouse no arquivo de deployment.template.json e selecione Criar e enviar solução IoT Edge.

O comando build e push inicia três operações. Primeiro, ele cria uma nova pasta na solução chamada config que contém o manifesto de implantação completo, construído a partir de informações no modelo de implantação e outros arquivos de solução. Em segundo lugar, ele é executado docker build para criar a imagem do contêiner com base no dockerfile apropriado para sua arquitetura de destino. Em seguida, ele é executado docker push para enviar o repositório de imagens para o registro do contêiner.

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

Opcional: Atualize o módulo e a imagem

Se você fizer alterações no código do módulo, precisará reconstruir e enviar a imagem do módulo para o registro do contêiner. Use as etapas nesta seção para atualizar a compilação e a imagem do contêiner. Você pode pular 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, é diferente se você escolher uma arquitetura diferente.

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

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

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

    Gorjeta

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

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

Crie e envie a imagem atualizada com uma tag de versão 0.0.2 . Por exemplo, para criar e enviar por push a imagem para o registro local ou 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 novamente e selecione Criar e Enviar por Push a Solução IoT Edge.

Abra o arquivo deployment.amd64.json novamente. Observe que o sistema de compilação não cria um novo arquivo quando você executa o comando build and push novamente. Em vez disso, o mesmo arquivo é atualizado para refletir as alterações. A imagem filtermodule agora aponta para a versão 0.0.2 do contêiner.

Para verificar melhor o que o comando build e push fez, vá para o portal do Azure e navegue até o registro do contêiner.

No registro do contêiner, selecione Repositórios e filtermodule. Verifique se ambas as versões da imagem são enviadas por push para o registro.

Captura de tela de onde exibir ambas as versões de imagem no registro do contêiner.

Resolver problemas

Se você encontrar erros ao criar e enviar a imagem do módulo, isso geralmente tem a ver com a configuração do Docker em sua máquina de desenvolvimento. Use as seguintes verificações para revisar sua configuração:

  • Você executou o docker login comando usando as credenciais copiadas do registro do 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 se parecer com <o nome> do registro.azurecr.io/filtermodule.
  • Se você usou um nome diferente de filtermodule para seu módulo, esse nome é consistente em toda a solução?
  • Sua máquina está executando o mesmo tipo de contêineres que você está construindo? Este tutorial é para dispositivos Linux IoT Edge, portanto, o Visual Studio Code deve dizer amd64 ou arm32v7 na barra lateral, e o Docker Desktop deve estar executando contêineres Linux.

Implantar módulos no dispositivo

Você verificou que há imagens de contêiner criadas armazenadas em seu registro de contêiner, portanto, é hora de implantá-las em um dispositivo. Certifique-se de que seu dispositivo IoT Edge esteja instalado e funcionando.

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 para o dispositivo my device do IoT Edge, use o seguinte comando. Substitua os valores para nome do hub, ID do dispositivo e cadeia de conexão do Hub IoT de login pela sua.

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

Gorjeta

Você pode encontrar sua cadeia de conexão do Hub IoT, incluindo a chave de acesso compartilhada no portal do Azure. Vá para suas configurações>de segurança do Hub> IoT Políticas>de acesso compartilhado iothubowner.

  1. No explorador de código do Visual Studio, 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 do registro do contêiner ou os valores da imagem do módulo. Se você tiver como destino 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 no seu dispositivo.

    Pode levar alguns minutos para que os módulos sejam iniciados. O tempo de execução do IoT Edge precisa receber seu novo manifesto de implantação, extrair as imagens do módulo do tempo de execução do contêiner e iniciar cada novo módulo.

Ver mensagens do dispositivo

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

  1. No explorador de códigos do Visual Studio, clique com o botão direito do mouse no dispositivo IoT Edge que você deseja monitorar e selecione Iniciar monitoramento de ponto de extremidade de evento interno.

  2. Observe a janela de saída no Visual Studio Code para ver as mensagens que chegam ao seu hub IoT.

    Captura de ecrã a mostrar onde ver as mensagens recebidas do dispositivo para a nuvem.

Ver alterações no dispositivo

Se você quiser ver o que está acontecendo no próprio dispositivo, use os comandos desta seção para inspecionar o tempo de execução do IoT Edge e os módulos em execução no dispositivo.

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

  • Veja todos os módulos implementados no seu dispositivo e verifique o seu estado:

    iotedge list

    Você verá quatro módulos: os dois módulos de tempo de execução do IoT Edge, tempSensor e filtermodule. Você deve ver todos os quatro listados como em execução.

  • Inspecione os logs para um módulo específico:

    iotedge logs <module name>

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

    Os logs 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 têm informações sobre a implementação do manifesto de implantação. Se você achar que um módulo não está listado ou não está em execução, os logs do edgeAgent provavelmente têm 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 os erros.

Clean up resources (Limpar recursos)

Se planeia avançar para o próximo artigo recomendado, pode manter os recursos e as configurações que criou e reutilizá-los. Também pode continuar a utilizar o mesmo dispositivo IoT Edge como um dispositivo de teste.

Caso contrário, você pode excluir as configurações locais e os recursos do Azure usados neste artigo para evitar cobranças.

Eliminar recursos do Azure

A eliminação de recursos e grupos de recursos do Azure é irreversível. Confirme que não elimina acidentalmente o grupo de recursos ou recursos errados. Se você criou o hub IoT dentro de um grupo de recursos existente que tem recursos que deseja manter, exclua apenas o recurso do hub IoT em si, não o grupo de recursos.

Para eliminar os recursos:

  1. Inicie sessão 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. Reveja a lista de recursos contidos no seu grupo de recursos. Se quiser eliminá-los todos, pode selecionar Eliminar grupo de recursos. Se quiser eliminar apenas alguns dos recursos, pode clicar em cada um para eliminá-los individualmente.

Próximos passos

Neste tutorial, você configurou o Visual Studio Code em sua máquina de desenvolvimento e implantou seu primeiro módulo IoT Edge que contém código para filtrar dados brutos gerados pelo dispositivo IoT Edge.

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

Depurar módulosdo Azure IoT Edge FunçõesStream AnalyticsServiço de Visão Personalizada