Use o Visual Studio 2022 para desenvolver e depurar módulos para Azure IoT Edge

1. No Solution Explorer, clique com o botão direito no nome do seu projeto principal e depois selecione Definir versão do runtime do IoT Edge.

   

2. Usa o menu suspenso para escolher a versão de runtime que os seus dispositivos IoT Edge estão a utilizar, depois seleciona OK para guardar as suas alterações. Se nenhuma alteração tiver sido feita, selecione Cancelar para sair.

   A extensão não inclui uma seleção para as versões de tempo de execução mais recentes. Para definir uma versão de tempo de execução superior a 1.2, abra o ficheiro de manifesto de implementação deployment.debug.template.json. 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, para usar o runtime do IoT Edge versão 1.5, altere as seguintes linhas no ficheiro de manifestos de implementação:

   "systemModules": {
      "edgeAgent": {
       //...
         "image": "mcr.microsoft.com/azureiotedge-agent:1.5"
       //...
      "edgeHub": {
      //...
         "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
      //...
   

3. Se mudaste a versão, regenera o teu manifesto de implementação clicando com o botão direito no nome do teu projeto, depois seleciona Gerar deployment para IoT Edge. Isto gera um manifesto de implementação baseado no seu modelo de implementação e coloca-o na pasta config do seu projeto Visual Studio.

1. Abra o ficheiro de manifesto de implantação deployment.debug.template.json. O manifesto de implantaçã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 tempo de execução do sistema edgeAgent e edgeHub. Por exemplo, para usar o runtime do IoT Edge versão 1.5, altere as seguintes linhas no ficheiro de manifestos de implementação:

   "systemModules": {
       "edgeAgent": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
       //...
       "edgeHub": {
       //...
           "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
       //...
   

Depurar usando o simulador

A Ferramenta de Desenvolvimento Azure IoT EdgeHub proporciona uma experiência local de desenvolvimento e depuração. A ferramenta ajuda a iniciar módulos IoT Edge sem o runtime IoT Edge, para que possa criar, desenvolver, testar, executar e depurar módulos e soluções IoT Edge localmente. Não é necessário enviar imagens por push para um registro de contêiner e implantá-las em um dispositivo para teste.

Para mais informações, consulte Azure IoT EdgeHub Dev Tool.

Para inicializar a ferramenta no Visual Studio:

1. Recupere o connection string do seu dispositivo IoT Edge (encontrado no seu IoT Hub) no portal Azure ou no Azure CLI.

   Se usar a CLI para recuperar o seu connection string, use este comando, substituindo "[device_id]" e "[hub_name]" pelos seus próprios valores:

   az iot hub device-identity connection-string show --device-id [device_id] --hub-name [hub_name]
   

2. No menu Tools no Visual Studio, selecione Azure IoT Edge Tools>Configurar o Simulador IoT Edge.

3. Cole a connection string e selecione OK.

Criar e depurar um único módulo

Normalmente, você deseja testar e depurar cada módulo antes de executá-lo em uma solução inteira com vários módulos. A ferramenta simuladora IoT Edge permite-lhe executar um único módulo isoladamente e enviar mensagens pela porta 53000.

1. Em Solution Explorer, selecione e destaque a pasta do projeto do módulo (por exemplo, IotEdgeModule1). Defina o módulo personalizado como o projeto de inicialização. Selecione Project>Definir como Projeto de Inicialização no menu.

2. Pressione F5 ou selecione o botão da barra de ferramentas executar para iniciar o simulador de IoT Edge para um único módulo. Pode demorar 10 a 20 segundos inicialmente.

   

3. Deverá ver aparecer uma janela da aplicação da consola .NET Core se o módulo tiver sido inicializado com sucesso.

4. Defina um ponto de interrupção para inspecionar o módulo.

   • Se estiver desenvolvendo em C#, defina um ponto de interrupção na PipeMessage() função em ModuleBackgroundService.cs.
   • Se estiver usando C, defina um ponto de interrupção na InputQueue1Callback() função em main.c.

5. Teste o módulo enviando uma mensagem. Quando estás a depurar um único módulo, o simulador ouve mensagens na porta padrão 53000. Para enviar uma mensagem para o módulo, execute o seguinte comando curl a partir de um shell de comando como Git Bash ou WSL Bash.

   curl --header "Content-Type: application/json" --request POST --data '{"inputName": "input1","data":"hello world"}' http://localhost:53000/api/v1/messages
   

   Se receberes o erro chaveta/colchete de fecho não coincidente num URL, tenta o seguinte comando:

   curl --header "Content-Type: application/json" --request POST --data "{\"inputName\": \"input1\", \"data\", \"hello world\"}"  http://localhost:53000/api/v1/messages
   

   

   O ponto de interrupção deve ser acionado. Pode observar variáveis na janela de Locals do Visual Studio, encontrada quando o depurador está em execução. Vá a Debug>Windows>Locals.

   No seu Bash ou shell, você deve ver uma {"message":"accepted"} confirmação.

   Na sua consola .NET deve ver:

   IoT Hub module client initialized.
   Received message: 1, Body: [hello world]
   

6. Pressione Ctrl + F5 ou selecione o botão Parar para parar a depuração.

Compilar e depurar vários módulos

Depois de concluir o desenvolvimento de um único módulo, convém executar e depurar uma solução inteira com vários módulos. A ferramenta IoT Edge Simulator permite-lhe executar todos os módulos definidos no manifesto de implementação, incluindo um edgeHub simulado para o encaminhamento de mensagens. Neste exemplo, você executa dois módulos personalizados e o módulo de sensor de temperatura simulado. As mensagens do módulo de sensor de temperatura simulado são encaminhadas para cada módulo personalizado.

1. Em Solution Explorer, adicione um segundo módulo à solução clicando com o botão direito na pasta principal do projeto. No menu, selecione Add>Novo Módulo IoT Edge.

   

2. Na janela Add module dá um nome ao teu novo módulo e substitui a parte localhost:5000 do URL do repositório pelo teu servidor de login Azure Container Registry, como fizeste antes.

3. Abra o arquivo deployment.debug.template.json para ver se o novo módulo foi adicionado na seção modules . Foi também adicionada uma nova rota à secção rotas em EdgeHub para enviar mensagens do novo módulo para IoT Hub. Para enviar dados do sensor de temperatura simulado para o novo módulo, adicione outra rota com a seguinte linha de JSON. Substitua <NewModuleName> (em dois lugares) pelo seu próprio nome de módulo.

   "sensorTo<NewModuleName>": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/<NewModuleName>/inputs/input1\")"
   

4. Clique com o botão direito do mouse no projeto principal (por exemplo, AzureIotEdgeApp1) e selecione Definir como Projeto de Inicialização. Ao definir o projeto principal como o projeto de inicialização, todos os módulos da solução são executados. Isso inclui os dois módulos que você adicionou à solução, o módulo de sensor de temperatura simulado e o hub Edge simulado.

5. Pressione F5 ou selecione o botão Executar barra de ferramentas para executar a solução. Inicialmente, pode demorar 10 a 20 segundos. Certifique-se de não ter outros contêineres do Docker em execução que possam vincular a porta necessária para este projeto.

6. Deves ver duas janelas de consola .NET Core, uma para cada módulo.

7. Defina um ponto de interrupção para inspecionar os módulos.

   • Se estiver desenvolvendo em C#, defina um ponto de interrupção na PipeMessage() função em ModuleBackgroundService.cs.
   • Se estiver usando C, defina um ponto de interrupção na InputQueue1Callback() função em main.c.

8. Crie pontos de interrupção em cada módulo e pressione F5 para executar e depurar vários módulos simultaneamente. Deves ver várias janelas de aplicações de consola .NET Core, com cada janela a representar um módulo diferente.

   

9. Pressione Ctrl + F5 ou selecione o botão Parar para parar a depuração.

Crie e envie imagens para o registro

Depois de desenvolver e depurar o seu módulo, construa e envie a imagem do módulo para o seu Azure Container Registry. Depois, implante o módulo no seu dispositivo IoT Edge.

1. Defina o projeto principal do IoT Edge como projeto inicial, e não como um dos módulos individuais.

2. Selecione Debug ou Release como a configuração a ser compilada para as imagens do módulo.

   Nota

   Quando escolhes Debug, Visual Studio usa Dockerfile.(amd64|windows-amd64).debug para construir imagens Docker. Isto inclui o depurador de linha de comandos .NET Core, VSDBG, na imagem do contentor. Para módulos de IoT Edge prontos para produção, use a configuração Release, que utiliza Dockerfile.(amd64|windows-amd64) sem VSDBG.

3. Se usar um registo privado como o Azure Container Registry (ACR), use o seguinte comando Docker para iniciar sessão. Obtenha o nome de utilizador e a palavra-passe na página Chaves de Acesso do seu registo no portal Azure.

   docker login <ACR login server>
   

4. Adicione a informação de login Azure Container Registry às definições de tempo de execução no ficheiro deployment.debug.template.json. Você pode adicionar suas credenciais de registro ao seu .env arquivo (mais seguro) ou adicioná-las diretamente ao seu deployment.debug.template.json arquivo.

   Adicione credenciais ao seu .env ficheiro:

   Em Solution Explorer, selecione o botão da barra de ferramentas Mostrar Todos os Ficheiros. O .env arquivo é exibido. Adicione o seu nome de utilizador Azure Container Registry e palavra-passe ao seu ficheiro .env. Encontre estas credenciais na página Chaves de Acesso do seu Azure Container Registry no portal Azure.

   

       DEFAULT_RT_IMAGE=1.5
       CONTAINER_REGISTRY_USERNAME_myregistry=<my-registry-name>
       CONTAINER_REGISTRY_PASSWORD_myregistry=<my-registry-password>
   

   Adicionar credenciais diretamente ao deployment.debug.template.json

   Se você quiser adicionar suas credenciais diretamente ao seu modelo de implantação, substitua os espaços reservados pelo nome de usuário, senha e nome do Registro do administrador do ACR.

         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "registry1": {
               "username": "<username>",
               "password": "<password>",
               "address": "<registry name>.azurecr.io"
             }
           }
         }
   

   Nota

   Este artigo utiliza credenciais de login de administrador para o Azure Container Registry, 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 com privilégios mínimos, como principais de serviço. Para obter mais informações, consulte Gerenciar o acesso ao registro de contêiner.

5. Se você usar um registro local, execute um registro local.

6. Finalmente, no Solution Explorer, clique com o botão direito na pasta principal do projeto e selecione Build e Push IoT Edge Modules para construir e empurrar a imagem Docker de cada módulo. Isto pode demorar um minuto. Quando vês Finished Build and Push IoT Edge Modules. na tua consola de saída de Visual Studio, estás feito.

Implementar a solução

Agora que já construiu e enviou as imagens dos seus módulos para o Azure Container Registry, implemente a solução no seu dispositivo IoT Edge. Você já tem um modelo de manifesto de implantação neste tutorial. Gera um manifesto de implementação a partir dele e depois usa um comando Azure CLI para implantar os teus módulos no teu dispositivo IoT Edge no Azure.

1. Clique com o botão direito no seu projeto principal em Visual Studio Solution Explorer e escolha Ger Deployment para IoT Edge.

   

2. Vá à pasta principal do seu projeto Visual Studio local e procura na pasta config. O caminho do arquivo pode ter esta aparência: C:\Users\<YOUR-USER-NAME>\source\repos\<YOUR-IOT-EDGE-PROJECT-NAME>\config. Aqui você encontra o manifesto de implantação gerado, como deployment.amd64.debug.json.

3. Abra o deployment.amd64.debug.json arquivo e confirme se a versão do edgeHub esquema está definida como 1.2.

    "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.2",
          "routes": {
            "IotEdgeModule2022ToIoTHub": "FROM /messages/modules/IotEdgeModule2022/outputs/* INTO $upstream",
            "sensorToIotEdgeModule2022": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/IotEdgeModule2022/inputs/input1\")",
            "IotEdgeModule2022bToIoTHub": "FROM /messages/modules/IotEdgeModule2022b/outputs/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      }
   

   Gorjeta

   O modelo de implementação do Visual Studio 2022 requer a versão do esquema 1.2. Se você precisar que ele seja 1.1 ou 1.0, aguarde até que a implantação seja gerada (não altere-a em deployment.debug.template.json). A geração de uma implantação cria um esquema 1.2 por padrão. No entanto, pode alterar manualmente deployment.amd64.debug.json, o manifesto gerado, se necessário, antes de o implementar para Azure.

   Importante

   Assim que o seu dispositivo IoT Edge for implementado, atualmente não será exibido corretamente no portal do Azure com a versão 1.2 do esquema (a versão 1.1 é aceitável). No entanto, isto não afetará o seu dispositivo, pois ele ainda está ligado no IoT Hub e pode ser comunicado a qualquer momento através da Azure CLI.

   

4. Agora vamos implementar o nosso manifesto com um comando Azure CLI. Abra o Visual Studio Developer Command Prompt e mude para o diretório config.

       cd config
   

5. Implemente o manifesto do seu dispositivo IoT Edge para o IoT Hub. O comando configura o dispositivo para utilizar módulos desenvolvidos na sua solução. O manifesto de implantação foi criado na etapa anterior e armazenado na pasta config . Na pasta config , execute o seguinte comando de implantação. Substitua o [device id], [hub name]e [file path] pelos seus valores. Se o ID do dispositivo IoT Edge não existir no IoT Hub, tem de ser criado.

       az iot edge set-modules --device-id [device id] --hub-name [hub name] --content [file path]
   

   Por exemplo, seu comando pode ter esta aparência:

   az iot edge set-modules --device-id my-device-name --hub-name my-iot-hub-name --content deployment.amd64.debug.json
   

6. Depois de executar o comando, você verá uma confirmação de implantação impressa em JSON no prompt de comando.

Imagem Docker do módulo de construção

Depois de desenvolver o seu módulo, crie a imagem do módulo para armazenar num registo de contentores para implementação no seu dispositivo IoT Edge.

Use o Dockerfile do módulo para criar a imagem do Docker do módulo.

docker build --rm -f "<DockerFilePath>" -t <ImageNameAndTag> "<ContextPath>" 

Por exemplo, se o seu shell de comandos estiver no diretório do projeto e o nome do seu módulo for IotEdgeModule1, use os seguintes comandos para construir a imagem para o registro local ou de um registro de contentores do Azure:

# Build the image for the local registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t localhost:5000/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Or build the image for an Azure Container Registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

Imagem do Docker do módulo Push

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/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure Container Registry
az acr login --name myacr
docker push myacr.azurecr.io/iotedgemodule1:0.0.1-amd64

Desloque o módulo para o dispositivo IoT Edge.

No Visual Studio, abra o ficheiro de manifestos de implementação deployment.debug.template.json no projeto principal. O manifesto de implementação é um documento JSON que descreve os módulos a configurar no dispositivo alvo IoT Edge. Antes da implementação, precisa de atualizar as suas credenciais de Azure Container Registry, as imagens dos seus módulos e os valores corretos de createOptions. Para mais informações sobre os valores createOption, veja Como configurar opções de criação de contentores para módulos IoT Edge.

1. Se estiveres a usar um Azure Container Registry para guardar a imagem do teu módulo, precisas de adicionar as tuas credenciais a deployment.debug.template.json nas definições edgeAgent. Por exemplo,

   "modulesContent": {
   "$edgeAgent": {
     "properties.desired": {
       "schemaVersion": "1.1",
       "runtime": {
         "type": "docker",
         "settings": {
           "minDockerVersion": "v1.25",
           "loggingOptions": "",
           "registryCredentials": {
             "myacr": {
               "username": "myacr",
               "password": "<your_acr_password>",
               "address": "myacr.azurecr.io"
             }
           }
         }
       },
   //...
   

2. Substitua o valor da propriedade image pelo nome da imagem do módulo publicado no registo. Por exemplo, se enviou uma imagem com a tag myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 para o módulo personalizado IotEdgeModule1, substitua o valor da propriedade da imagem pelo valor da tag.

3. Adicione ou substitua o valor createOptions por conteúdo serializado para cada sistema e módulo personalizado no modelo de implantação.

   Por exemplo, as configurações de imagem e createOptions do IotEdgeModule1 seriam semelhantes às seguintes:

   "IotEdgeModule1": {
   "version": "1.0.0",
   "type": "docker",
   "status": "running",
   "restartPolicy": "always",
   "settings": {
       "image": "myacr.azurecr.io/iotedgemodule1:0.0.1-amd64",
       "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
   }
   

Use o comando IoT Edge Azure CLI set-modules para implantar os módulos na Azure IoT Hub. Por exemplo, para implementar os módulos definidos no ficheiro deployment.debug.amd64.json para IoT Hub my-iot-hub para o dispositivo IoT Edge my-device, execute o seguinte comando:

az iot edge set-modules --hub-name my-iot-hub --device-id my-device --content ./deployment.debug.template.json --login "HostName=my-iot-hub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=<SharedAccessKey>"