Partilhar via

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

Aplica-se a:IoT Edge 1.5 IoT Edge 1.5

Importante

IoT Edge 1.5 LTS é a versão suportada. O IoT Edge 1.4 LTS atingiu o fim de vida útil a 12 de novembro de 2024. Se estiveres a usar uma versão anterior, vê Update IoT Edge.

Este tutorial mostra como desenvolver e implementar o seu código num dispositivo IoT Edge. Os módulos Azure IoT Edge permitem-lhe implementar código que executa a lógica do seu negócio diretamente no seu dispositivo IoT Edge. No quickstart Implementar código num dispositivo Linux, configuras um dispositivo IoT Edge e implementaste um módulo a partir do Azure Marketplace.

Este artigo descreve os passos para duas ferramentas de desenvolvimento IoT Edge:

  • Azure IoT Edge Dev Tool linha de comandos (CLI), que é preferida para desenvolvimento.
  • Extensão de ferramentas Azure IoT Edge para Visual Studio Code, que está em modo de manutenção.

Use o botão seletor de ferramentas no início deste artigo para escolher sua ferramenta.

Neste tutorial, irá aprender a:

  • Configure sua máquina de desenvolvimento
  • Use as ferramentas IoT Edge para criar um novo projeto
  • Construa o seu projeto como um contentor Docker e armazene-o num registo de contentores Azure
  • Implemente o seu código num dispositivo IoT Edge

O módulo IoT Edge que cria neste tutorial filtra os dados de temperatura gerados pelo seu dispositivo. Ele envia mensagens a montante somente se a temperatura estiver acima de um limite definido. Esse tipo de análise na borda ajuda a reduzir a quantidade de dados enviados e armazenados na nuvem.

Pré-requisitos

Uma máquina de desenvolvimento:

  • Use seu próprio computador ou uma máquina virtual.
  • Certifique-se de que sua máquina de desenvolvimento ofereça suporte à virtualização aninhada para executar um mecanismo de contêiner.
  • Pode usar a maioria dos sistemas operativos que correm um motor de contentores para desenvolver módulos IoT Edge para dispositivos Linux. Este tutorial utiliza um computador Windows, mas também aponta diferenças conhecidas no macOS ou no Linux.
  • Instalar Visual Studio Code
  • Instala o Azure CLI.

Um dispositivo Azure IoT Edge:

  • Executa o IoT Edge num dispositivo separado. Manter a máquina de desenvolvimento e o dispositivo IoT Edge separados simula um cenário real de implementação e ajuda a manter os conceitos claros. Use o artigo de início rápido Deploy code to a Linux Device para criar um dispositivo IoT Edge no Azure ou o modelo Azure Resource Manager para implementar uma VM com IoT Edge ativada.

Recursos da cloud:

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

Gorjeta

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

Este tutorial cobre os passos de desenvolvimento para Visual Studio Code.

Conceitos-chave

Este tutorial explica como desenvolver um módulo IoT Edge. Um módulo IoT Edge é um contentor com código executável. Pode implementar um ou mais módulos num dispositivo IoT Edge. Os módulos realizam tarefas específicas como ingerir dados de sensores, limpar e analisar dados, ou enviar mensagens para um IoT Hub. Para mais informações, veja Compreender Azure IoT Edge módulos.

Ao desenvolver módulos IoT Edge, deve compreender a diferença entre a máquina de desenvolvimento e o dispositivo IoT Edge alvo onde o módulo é implementado. 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 é desenvolver um módulo num computador Windows para um dispositivo Linux que executa IoT Edge. Nesse caso, o sistema operacional do contêiner é 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 estiveres a usar IoT Edge para Linux em Windows, o dispositivo alvo no teu cenário é a máquina virtual Linux, não o host Windows.

Este tutorial destina-se a dispositivos que executam IoT Edge com contentores Linux. Use seu sistema operacional preferido, desde que sua máquina de desenvolvimento execute contêineres Linux. O Visual Studio Code é recomendado para desenvolver com containers Linux, por isso este tutorial utiliza-o. Também pode usar o Visual Studio, embora existam diferenças de suporte entre as duas ferramentas.

A tabela seguinte lista cenários de desenvolvimento suportados para contentores 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 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 Azure IoT Edge Ferramentas para Visual Studio 2019
Ferramentas do Azure IoT Edge para o Visual Studio 2022

Instalar mecanismo de contêiner

IoT Edge módulos são embalados como containers, por isso precisas de um sistema de gestão de contentores compatível com Docker na tua máquina de desenvolvimento para os construir e gerir. O Docker Desktop é uma escolha popular para desenvolvimento porque tem forte suporte a recursos. O Docker Desktop no Windows permite alternar entre containers Linux e containers Windows, para que possa desenvolver módulos para diferentes tipos de dispositivos IoT Edge.

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

Configurar ferramentas

Instale a ferramenta de desenvolvimento baseada em Python Azure IoT Edge Dev para criar a sua solução IoT Edge. Tem duas opções:

Importante

As ferramentas Azure IoT Edge para a extensão Visual Studio Code estão em modo manutenção. A ferramenta de desenvolvimento preferida é a ferramenta de linha de comandos (CLI) Azure IoT Edge Dev Tool.

Utilize as extensões IoT para o Visual Studio Code para desenvolver módulos IoT Edge. Estas extensões oferecem modelos de projeto, automatizam a criação do manifesto de implementação e permitem-lhe monitorizar e gerir dispositivos IoT Edge. Nesta secção, instala o Visual Studio Code e a extensão IoT, depois configura a sua conta no Azure para gerir os recursos do IoT Hub a partir do Visual Studio Code.

  1. Instala a extensão Azure IoT Edge.
  2. Instala a extensão Azure IoT Hub.
  3. Depois de instalar as extensões, abra a paleta de comandos selecionando Exibir > paleta de comandos.
  4. Na paleta de comandos, procure e selecione Azure IoT Hub: Selecione IoT Hub. Siga as instruções para selecionar a sua subscrição do Azure e o IoT Hub.
  5. Abra a secção do explorador da Visual Studio Code selecionando o ícone na barra de atividades ou selecionando Ver > Explorador.
  6. No final da secção do explorador, expanda o menu colapsado Azure IoT Hub / Dispositivos. Vê os dispositivos e dispositivos IoT Edge associados ao IoT Hub que selecionou através 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, utilizas as extensões Azure IoT Edge e Azure IoT Hub para construir um módulo e criar uma imagem contentor a partir dos ficheiros. Em seguida, você envia essa imagem para um registro que armazena e gerencia suas imagens. Por fim, implementa a sua imagem a partir do seu registo para correr no seu dispositivo IoT Edge.

Importante

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

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

Se ainda não tem um registo de contentores, siga estes passos para criar um novo no Azure:

  1. No portal Azure, selecione Criar um recurso>Containers>Container Registry.

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

    Campo Valor
    Subscrição Selecione uma subscrição na lista pendente.
    Grupo de recursos Use o mesmo grupo de recursos para todos os recursos de teste que cria durante o IoT Edge quickstarts e tutoriais; por exemplo, IoTEdgeResources.
    Nome de registo Indique um nome exclusivo.
    Localização Escolha uma localização perto de si.
    SKU Selecione Básico.

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

  4. Selecione o seu novo registo de contentores na secção Resources da página inicial do portal de Azure para o abrir.

  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 utilizador Administrador com o botão de alternância e visualize o Nome de Utilizador e a Palavra-passe do registo do contentor.

  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 Azure IoT Edge oferece modelos de projeto para todas as linguagens de módulos IoT Edge suportadas no Visual Studio Code. Estes modelos incluem todos os ficheiros e código necessários para implementar um módulo funcional para testar o IoT Edge, ou dar-lhe um ponto de partida para personalizar o modelo com a sua própria lógica de negócio.

Criar um modelo de projeto

A Ferramenta de Desenvolvimento IoT Edge simplifica o desenvolvimento Azure IoT Edge, com comandos controlados por variáveis do ambiente. Ajuda-o a iniciar o desenvolvimento IoT Edge utilizando o IoT Edge Dev Container e a estrutura da solução IoT Edge, que inclui um módulo padrão e todos os ficheiros de configuração necessários.

  1. Crie um diretório para sua solução no caminho desejado. 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 o seu Azure IoT Hub na linguagem de desenvolvimento que preferir:

    iotedgedev solution init --template csharp

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

  • Autenticar no Azure
  • Escolha uma subscrição do Azure
  • Escolher ou criar um grupo de recursos
  • Escolha ou crie um Azure IoT Hub
  • Escolha ou crie um dispositivo Azure IoT Edge

Use Visual Studio Code e a extensão Azure IoT Edge. Comece criando uma solução e, em seguida, gere o primeiro módulo dessa solução. Cada solução pode incluir vários módulos.

  1. Selecione Exibir > paleta de comandos.
  2. Na paleta de comandos, introduza 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. Insira o nome do repositório de imagens do módulo. Visual Studio Code preenche automaticamente o nome do módulo com localhost:5000/<nome do teu módulo>. Substitua-o por suas próprias informações de registro. Utilize localhost se utilizar um registo Docker local para testes. Se utilizar o Azure Container Registry, utilize o Login server das configurações do seu 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 <nome do registro>.azurecr.io/<seu nome do módulo>.

O Visual Studio Code pega na informação que forneceste, cria uma solução IoT Edge e depois carrega-a numa nova janela.

Depois de criar a solução, estes arquivos principais estão na solução:

  • A pasta .vscode inclui o arquivo de configuraçãolaunch.json.

  • A pasta modules tem subpastas para cada módulo. Em cada subpasta, o arquivo module.json controla como os módulos são criados e implantados.

  • O 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, deployment.template.json e deployment.debug.template.json, listam os módulos a serem implantados em seu dispositivo. Por defeito, a lista inclui os módulos do sistema IoT Edge (edgeAgent e edgeHub) e módulos de exemplo tais como:

    Nota

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

Definir a versão de runtime do IoT Edge

A versão mais recente do módulo estável 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 o ficheiro de manifestos de implementação deployment.template.json. O manifesto de implementação é um documento JSON que descreve os módulos a configurar no dispositivo alvo IoT Edge.

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

    "systemModules": {
    "edgeAgent": {

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

    "edgeHub": {

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

Forneça as suas credenciais de registo ao agente IoT Edge

O ficheiro de ambiente armazena as credenciais do seu registo de contentores e partilha-as com o runtime do IoT Edge. O runtime necessita destas credenciais para obter as imagens dos seus contentores no dispositivo IoT Edge.

A extensão IoT Edge tenta extrair as credenciais do registo de contentores do Azure e preenchê-las no ficheiro 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 Azure Container Registry for o teu registo, define um nome de utilizador e password do Azure Container Registry. Obtenha estes valores do menu Settings>Chaves de acesso do seu registo de contentores no portal Azure.

  2. Abra o arquivo .env na sua solução.

  3. Adicione os valores nome de utilizador e password valores que copiou do seu registo de contentores de 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 utiliza credenciais de administrador para o Azure Container Registry que são convenientes para cenários de desenvolvimento e teste. Quando você estiver pronto para cenários de produção, recomendamos uma opção de autenticação menos privilegiada, 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 alvo

Selecione a arquitetura que você está segmentando com cada solução, pois isso afeta como o contêiner é criado e executado. O padrão é Linux AMD64. Para este tutorial, usa uma máquina virtual Ubuntu como dispositivo IoT Edge e mantém o predefinido amd64.

Se você precisar alterar a arquitetura de destino para sua solução, siga estas etapas.

  1. Abra a paleta de comandos e procure por Azure IoT Edge: Definir Plataforma de Alvo Padrão para Solução de Borda, ou selecione o ícone de atalho na barra lateral no fundo 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 recolhe dados simulados do sensor do módulo SimulatedTemperatureSensor e os encaminha para o IoT Hub. O módulo de exemplo recebe mensagens e as transmite. A funcionalidade do pipeline mostra um conceito importante no IoT Edge: como os módulos 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 a correr no dispositivo encaminha 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 para 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 do projeto utiliza a classe ModuleClient do SDK IoT Hub para .NET.

  1. No explorador do Visual Studio Code, abra modules > filtermodule > ModuleBackgroundService.cs.

  2. Antes do filtermodule namespace, adicione três using instruções 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 temperatureThreshold variável à ModuleBackgroundService classe. Esta variável define o valor que a temperatura medida deve exceder para que os dados sejam enviados para o IoT Hub.

    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. Esta função cria e configura um objeto ModuleClient que permite ao módulo conectar-se ao tempo de execução local Azure IoT Edge para enviar e receber mensagens. Depois de criar o ModuleClient, o código lê o valor temperatureThreshold das propriedades desejadas do gêmeo do módulo. O código regista um callback para receber mensagens de um hub de IoT Edge através de um endpoint chamado input1.

    Substitua a chamada do método ProcessMessageAsync por uma nova que atualize o nome do endpoint e o método que é chamado quando a entrada chega. Além disso, adicione um SetDesiredPropertyUpdateCallbackAsync método para atualizações às propriedades desejadas. Para fazer essa alteração, substitua a ExecuteAsync última linha do método 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 OnDesiredPropertiesUpdate método à ModuleBackgroundService classe. Esse método recebe atualizações sobre as propriedades desejadas do módulo gêmeo e atualiza a temperatureThreshold variável para corresponder. Todos os módulos têm o seu próprio gêmeo digital, que lhe permite configurar o código em execução no interior de um módulo diretamente a partir 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. Este método é chamado sempre que o módulo recebe uma mensagem do hub IoT Edge. Ele filtra as mensagens que comunicam temperaturas inferiores ao limiar de temperatura definido através do módulo duplo. Ele também adiciona a MessageType propriedade à mensagem com o valor definido como Alert:

    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 Visual Studio Code, abra o ficheiro deployment.template.json no seu espaço de trabalho de IoT Edge solução.

  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 routes seção no módulo $edgeHub gêmeo. Atualize a sensorTofiltermodule rota para substituir input1 por inputFromSensor:

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

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

       "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 ficheiro de manifestos de implementação deployment.template.json. O manifesto de implementação descreve os módulos a configurar no dispositivo IoT Edge destinado. Antes da implementação, deve atualizar as suas credenciais de Azure Container Registry e as imagens dos seus módulos com os valores corretos de createOptions. Para mais informações sobre valores de createOptions, veja Como configurar opções de criação de contentores para módulos de IoT Edge.

Se usares um Azure Container Registry para guardar a imagem do teu módulo, adiciona as tuas credenciais à secção modulesContent > edgeAgent > settings > registryCredentials em 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 em formato de string ao valor de 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 filtermodule configuração 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 Visual Studio Code selecionando Terminal > Novo 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 dotnet publish comando.

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

Atualmente, o modelo de ferramenta iotedgedev tem como objetivo .NET 7.0, que chegou ao fim do suporte em maio de 2024. Atualize o projeto para o objetivo .NET 8.0 (LTS, suportado até novembro de 2026) editando o ficheiro filtermodule.csproj e alterando os valores TargetFramework e PackageReference. O teu ficheiro filtermodule.csproj deve ficar assim:

<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. Iniciar sessão em Docker com as credenciais 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 autenticação de registo de contentores de produção, utilize um principal de serviço ou tokens com escopo de repositório em vez de credenciais de administrador. Para mais informações, consulte Gerir acesso ao seu registo de contentores e na referência docker login.

  2. Iniciar sessão no Azure Container Registry. Deve instalar Azure CLI para usar o comando az. Este comando solicita o seu nome de utilizador e palavra-passe encontrados no registo do contentor em Definições > Chaves de acesso:

    az acr login -n <ACR registry name>

    Gorjeta

    Se estiver desconectado em algum momento deste tutorial, repita os passos de início de sessão do Docker e do Azure Container Registry 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 no registo de contentores. Por exemplo, se estiver a usar um Azure Container Registry myacr.azurecr.io e a 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 explorador de Visual Studio Code, clique com o botão direito no ficheiro deployment.template.json e selecione Build and Push IoT Edge Solution.

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, executa-se docker build para construir a imagem do contentor com base no Dockerfile apropriado para a sua arquitetura de destino. Em seguida, executa-se docker push para enviar o repositório de imagens para o registo de contentores.

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, deverá reconstruir e enviar a imagem do módulo para o registro do contêiner. Use as etapas nesta seção para atualizar o build e a imagem do contentor. 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 registryCredentials seção tem seu nome de usuário e senha de 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 ficheiro 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 as alterações em um pequeno conjunto de dispositivos antes de implantar atualizações na produção. Se não incrementares a versão do módulo antes de compilares e enviares, então substituirás o repositório no registo do contentor.

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

Crie e envie a imagem atualizada com uma tag de versão 0.0.2 . Por exemplo, para construir e enviar a imagem para o registo local ou para um registo de contentores 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 novamente com o botão direito no ficheiro deployment.template.json e selecione novamente Build and Push IoT Edge Solution novamente.

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

Para verificar melhor o que o comando build and push fez, vá ao portal Azure e navegue até ao registo do seu contentor. No registro do contêiner, selecione Repositórios e filtermodule. Verifique se ambas as versões da imagem são enviadas para o registo.

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? Estas credenciais são diferentes das que usa para iniciar sessão no Azure.
  • Seu repositório de contêiner está correto? Tem o nome correto do seu registo de contentor e o nome correto do seu módulo? Abra o arquivo module.json na pasta filtermodule para verificar. O valor do repositório deve ser semelhante a <nome do registo>.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, por isso Visual Studio Code deve dizer amd64 ou arm32v7 na barra lateral, e o Docker Desktop deve estar a correr contentores 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 o seu dispositivo IoT Edge está operacional.

Use o comando IoT Edge Azure CLI set-modules para implantar os módulos no Azure IoT Hub. Por exemplo, para implementar os módulos definidos no ficheiro deployment.template.json para o IoT Hub my-iot-hub para o dispositivo IoT Edge my-device, use o seguinte comando. Substitua os valores hub-name, device-id e login IoT Hub connection string pelos seus próprios.

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

Encontre o seu IoT Hub connection string, incluindo a chave de acesso partilhada, no portal Azure. Vai ao teu IoT Hub e seleciona definições de segurança > Políticas de acesso partilhado > iothubowner.

  1. No explorador Visual Studio Code, na secção Azure IoT Hub, expanda Dispositivos para ver a sua lista de dispositivos IoT.

  2. Clique com o botão direito no dispositivo IoT Edge onde quer implementar, depois selecione Criar Implementação para Dispositivo Único.

  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 runtime do IoT Edge recebe o seu novo manifesto de implementação, retira as imagens dos módulos do tempo de execução do contentor e depois inicia 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 envia através de sua fila de saída. O manifesto de implementação configura rotas que enviam mensagens para filtermodule a partir de tempSensor, e depois encaminham mensagens de filtermodule para IoT Hub. As extensões Azure IoT Edge e Azure IoT Hub permitem-lhe ver as mensagens à medida que chegam ao IoT Hub a partir do seu dispositivo.

  1. No explorador do Visual Studio Code, selecione o dispositivo IoT Edge que deseja monitorizar e depois selecione Iniciar Monitorização do Endpoint de Evento Incorporado.

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

    Captura de ecrã da janela de saída do Visual Studio Code mostrando mensagens de dispositivo para a nuvem em chegada.

Ver alterações no dispositivo

Para ver o que se passa no seu dispositivo, use os comandos nesta secção para inspecionar o runtime e os módulos do IoT Edge que estão a correr no seu dispositivo.

Estes comandos são para o seu dispositivo IoT Edge, não para a sua máquina de desenvolvimento. Se está a usar uma máquina virtual para o seu dispositivo IoT Edge, ligue-se a ela agora. No Azure, vai à página de visão geral da máquina virtual e seleciona Conectar para aceder à ligação segura do shell.

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

    iotedge list

    Vês quatro módulos: os dois módulos de execução IoT Edge, tempSensor e filtermodule. Todos os quatro devem ser listados como em execução.

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

    iotedge logs <module name>

    Os nomes dos módulos são sensíveis a maiúsculas e minúsculas.

    Os logs tempSensor e filtermodule mostram as mensagens que estão processando. O módulo edgeAgent inicia os outros módulos, para que seus logs tenham informações sobre o manifesto de implantação. Se um módulo não estiver listado ou não estiver em execução, verifique se há erros nos logs do edgeAgent. O módulo edgeHub gere a comunicação entre os módulos e a IoT Hub. Se os módulos estiverem a correr mas as mensagens não chegarem ao seu IoT Hub, verifique os registos edgeHub para erros.

Limpar recursos

Se quiser continuar para o próximo artigo recomendado, mantenha os recursos e as configurações que criou e reutilize-os. Também pode continuar a usar o mesmo dispositivo IoT Edge como dispositivo de teste. Caso contrário, para evitar cobranças, elimine a configuração local e os recursos do Azure que utilizou neste artigo.

Eliminar recursos do Azure

Não podes desfazer a eliminação de recursos e grupos de recursos do Azure. Certifique-se de que não elimina acidentalmente o grupo de recursos ou os recursos errados. Se criaste o IoT Hub dentro de um grupo de recursos existente que tem recursos que queres manter, elimina apenas o próprio recurso do IoT Hub, não o grupo de recursos.

Para eliminar os recursos:

  1. Inicie sessão no portal Azure e depois selecione Resource groups.
  2. Selecione o nome do grupo de recursos que contém os seus recursos de teste IoT Edge.
  3. Reveja a lista de recursos que o seu grupo de recursos contém. Se quiser excluir todos eles, selecione Excluir grupo de recursos. Se quiseres eliminar apenas alguns, seleciona cada recurso para os eliminar individualmente.

Próximos passos

Neste tutorial, configura o Visual Studio Code na sua máquina de desenvolvimento e implementa o seu primeiro módulo IoT Edge com código que filtra os dados brutos gerados pelo seu dispositivo IoT Edge.

Continue para os próximos tutoriais para aprender como o Azure IoT Edge lhe permite implementar serviços cloud do Azure para processar e analisar dados na edge.

Debug Azure IoT Edge módulosFunctionsStream AnalyticsCustom Vision Service

  • Last updated on