Desenvolver um módulo C# IoT Edge para mover arquivos com o Azure Stack Edge Pro FPGA

Importante

Os dispositivos FPGA do Azure Stack Edge Pro atingiram o fim da vida útil em fevereiro de 2024.

Este artigo orienta você sobre como criar um módulo IoT Edge para implantação com seu dispositivo FPGA Azure Stack Edge Pro. O Azure Stack Edge Pro FPGA é uma solução de armazenamento que permite processar dados e enviá-los pela rede para o Azure.

Você pode usar os módulos do Azure IoT Edge com seu FPGA do Azure Stack Edge Pro para transformar os dados à medida que eles são movidos para o Azure. O módulo usado neste artigo implementa a lógica para copiar um arquivo de um compartilhamento local para um compartilhamento de nuvem em seu dispositivo FPGA Azure Stack Edge Pro.

Neste artigo, vai aprender a:

• Crie um registro de contêiner para armazenar e gerenciar seus módulos (imagens do Docker).
• Crie um módulo IoT Edge para implantar em seu dispositivo FPGA Azure Stack Edge Pro.

Sobre o módulo IoT Edge

Seu dispositivo FPGA do Azure Stack Edge Pro pode implantar e executar módulos do IoT Edge. Os módulos de borda são essencialmente contêineres do Docker que executam uma tarefa específica, como ingerir uma mensagem de um dispositivo, transformar uma mensagem ou enviar uma mensagem para um Hub IoT. Neste artigo, você criará um módulo que copia arquivos de um compartilhamento local para um compartilhamento de nuvem em seu dispositivo FPGA do Azure Stack Edge Pro.

1. Os arquivos são gravados no compartilhamento local em seu dispositivo FPGA do Azure Stack Edge Pro.
2. O gerador de eventos de arquivo cria um evento de arquivo para cada arquivo gravado no compartilhamento local. Os eventos de arquivo também são gerados quando um arquivo é modificado. Os eventos de arquivo são enviados para o IoT Edge Hub (em tempo de execução do IoT Edge).
3. O módulo personalizado do IoT Edge processa o evento file para criar um objeto de evento de arquivo que também contém um caminho relativo para o arquivo. O módulo gera um caminho absoluto usando o caminho do arquivo relativo e copia o arquivo do compartilhamento local para o compartilhamento na nuvem. Em seguida, o módulo exclui o arquivo do compartilhamento local.

Quando o arquivo estiver no compartilhamento de nuvem, ele será carregado automaticamente em sua conta de Armazenamento do Azure.

Pré-requisitos

Antes de começar, certifique-se de que tem:

• Um dispositivo FPGA do Azure Stack Edge Pro em execução.

  • O dispositivo também tem um recurso do Hub IoT associado.
  • O dispositivo tem a função de computação Edge configurada. Para obter mais informações, vá para Configurar computação para seu FPGA do Azure Stack Edge Pro.

• Os seguintes recursos de desenvolvimento:

  • Visual Studio Code.
  • Extensão C# para Visual Studio Code (com tecnologia da OmniSharp).
  • Extensão Azure IoT Edge para o Visual Studio Code.
  • SDK de .NET Core 2.1.
  • Docker CE. Poderá ter de criar uma conta para descarregar e instalar o software.

Criar um registo de contentores

Um registo de contentor do Azure é um registo do Docker privado no Azure, onde pode armazenar e gerir as imagens privadas de contentor do Docker. Os dois serviços populares de registro do Docker disponíveis na nuvem são o Azure Container Registry e o Docker Hub. Este artigo usa o Registro de contêiner.

1. Em um navegador, conecte-se ao portal do Azure.

2. Selecione Criar um Registro de Contêiner de Contêineres > de Recursos>. Clique em Criar.

3. Fornecer:

   1. Um nome de Registro exclusivo no Azure que contém de 5 a 50 caracteres alfanuméricos.

   2. Escolha uma Subscrição.

   3. Crie um novo grupo de Recursos ou escolha um existente.

   4. Selecione uma Localização. Recomendamos que esse local seja o mesmo associado ao recurso Azure Stack Edge.

   5. Mude Utilizador administrador para Ativar.

   6. Defina o SKU como Básico.

      

4. Selecione Criar.

5. Depois de o registo de contentores ser criado, navegue para o mesmo e selecione Chaves de acesso.

   

6. Copie os valores de Servidor de início de sessão, Nome de utilizador e Palavra-passe. Use esses valores posteriormente para publicar a imagem do Docker em seu registro e adicionar as credenciais do Registro ao tempo de execução do Azure IoT Edge.

Criar um projeto do módulo do IoT Edge

As etapas a seguir criam um projeto de módulo IoT Edge baseado no SDK do .NET Core 2.1. O projeto usa o Visual Studio Code e a extensão do Azure IoT Edge.

Criar uma nova solução

Crie um modelo de solução C# que pode personalizar com o seu próprio código.

1. No Visual Studio Code, selecione View > Command Palette para abrir a paleta de comandos VS Code.

2. Na paleta de comandos, introduza e execute o comando Azure: Iniciar sessão e siga as instruções para iniciar sessão na sua conta do Azure. Se já iniciou sessão, pode ignorar este passo.

3. Na paleta de comandos, introduza e execute o comando Azure IoT Edge: Nova solução do IoT Edge. Na paleta de comandos, indique as seguintes informações para criar a sua solução:

   1. Selecione a pasta onde quer criar a solução.

   2. Indique um nome para a sua solução ou aceite a predefinição EdgeSolution.

      

   3. Selecione Módulo C# como modelo de módulo.

   4. Substitua o nome do módulo padrão pelo nome que você deseja atribuir, neste caso, é FileCopyModule.

      

   5. Especifique o registro de contêiner que você criou na seção anterior como o repositório de imagens para seu primeiro módulo. Substitua localhost:5000 pelo valor do servidor de início de sessão que copiou.

      A cadeia de caracteres final se parece com <Login server name>/<Module name>. Neste exemplo, a cadeia de caracteres é: mycontreg2.azurecr.io/filecopymodule.

      

4. Vá para Pasta de abertura de arquivo>.

   

5. Procure e aponte para a pasta EdgeSolution que você criou anteriormente. A janela VS Code carrega seu espaço de trabalho da solução IoT Edge com seus cinco componentes de nível superior. Você não editará a pasta .vscode, o arquivo .gitignore, o arquivo .env e as deployment.template.json neste artigo.

   O único componente que você modifica é a pasta modules. Esta pasta tem o código C# para seu módulo e arquivos do Docker para construir seu módulo como uma imagem de contêiner.

   

Atualizar o módulo com o código personalizado

1. No explorador do VS Code, abra os módulos > FileCopyModule > Program.cs.

2. Na parte superior do namespace FileCopyModule, adicione as instruções using a seguir para tipos usados posteriormente. Microsoft.Azure.Devices.Client.Transport.Mqtt é um protocolo para enviar mensagens para o IoT Edge Hub.

   namespace FileCopyModule
   {
       using Microsoft.Azure.Devices.Client.Transport.Mqtt;
       using Newtonsoft.Json;
   

3. Adicione as variáveis InputFolderPath e OutputFolderPath à classe Program.

   class Program
       {
           static int counter;
           private const string InputFolderPath = "/home/input";
           private const string OutputFolderPath = "/home/output";
   

4. Imediatamente após a etapa anterior, adicione a classe FileEvent para definir o corpo da mensagem.

   /// <summary>
   /// The FileEvent class defines the body of incoming messages. 
   /// </summary>
   private class FileEvent
   {
       public string ChangeType { get; set; }
   
       public string ShareRelativeFilePath { get; set; }
   
       public string ShareName { get; set; }
   }
   

5. No método Init, o código cria e configura um objeto ModuleClient. Este objeto permite que o módulo se conecte ao tempo de execução local do Azure IoT Edge usando o protocolo MQTT para enviar e receber mensagens. A cadeia de ligação utilizada no método Init é dada ao módulo através do runtime do IoT Edge. O código registra um retorno de chamada FileCopy para receber mensagens de um hub IoT Edge por meio do ponto de extremidade input1 . Substitua o método Init pelo código a seguir.

   /// <summary>
   /// Initializes the ModuleClient and sets up the callback to receive
   /// messages containing file event information
   /// </summary>
   static async Task Init()
   {
       MqttTransportSettings mqttSetting = new MqttTransportSettings(TransportType.Mqtt_Tcp_Only);
       ITransportSettings[] settings = { mqttSetting };
   
       // Open a connection to the IoT Edge runtime
       ModuleClient ioTHubModuleClient = await ModuleClient.CreateFromEnvironmentAsync(settings);
       await ioTHubModuleClient.OpenAsync();
       Console.WriteLine("IoT Hub module client initialized.");
   
       // Register callback to be called when a message is received by the module
       await ioTHubModuleClient.SetInputMessageHandlerAsync("input1", FileCopy, ioTHubModuleClient);
   }
   

6. Remova o código para o método PipeMessage e, em seu lugar, insira o código para FileCopy.

       /// <summary>
       /// This method is called whenever the module is sent a message from the IoT Edge Hub.
       /// This method deserializes the file event, extracts the corresponding relative file path, and creates the absolute input file path using the relative file path and the InputFolderPath.
       /// This method also forms the absolute output file path using the relative file path and the OutputFolderPath. It then copies the input file to output file and deletes the input file after the copy is complete.
       /// </summary>
       static async Task<MessageResponse> FileCopy(Message message, object userContext)
       {
           int counterValue = Interlocked.Increment(ref counter);
   
           try
           {
               byte[] messageBytes = message.GetBytes();
               string messageString = Encoding.UTF8.GetString(messageBytes);
               Console.WriteLine($"Received message: {counterValue}, Body: [{messageString}]");
   
               if (!string.IsNullOrEmpty(messageString))
               {
                   var fileEvent = JsonConvert.DeserializeObject<FileEvent>(messageString);
   
                   string relativeFileName = fileEvent.ShareRelativeFilePath.Replace("\\", "/");
                   string inputFilePath = InputFolderPath + relativeFileName;
                   string outputFilePath = OutputFolderPath + relativeFileName;
   
                   if (File.Exists(inputFilePath))                
                   {
                       Console.WriteLine($"Moving input file: {inputFilePath} to output file: {outputFilePath}");
                       var outputDir = Path.GetDirectoryName(outputFilePath);
                       if (!Directory.Exists(outputDir))
                       {
                           Directory.CreateDirectory(outputDir);
                       }
   
                       File.Copy(inputFilePath, outputFilePath, true);
                       Console.WriteLine($"Copied input file: {inputFilePath} to output file: {outputFilePath}");
                       File.Delete(inputFilePath);
                       Console.WriteLine($"Deleted input file: {inputFilePath}");
                   } 
                   else
                   {
                       Console.WriteLine($"Skipping this event as input file doesn't exist: {inputFilePath}");   
                   }
               }
           }
           catch (Exception ex)
           {
               Console.WriteLine("Caught exception: {0}", ex.Message);
               Console.WriteLine(ex.StackTrace);
           }
   
           Console.WriteLine($"Processed event.");
           return MessageResponse.Completed;
       }
   

7. Guarde este ficheiro.

8. Você também pode baixar um exemplo de código existente para este projeto. Em seguida, você pode validar o arquivo salvo em relação ao arquivo program.cs neste exemplo.

Criar a sua solução do IoT Edge

Na seção anterior, você criou uma solução IoT Edge e adicionou código ao FileCopyModule para copiar arquivos do compartilhamento local para o compartilhamento na nuvem. Agora, tem de criar a solução como uma imagem de contentor e enviá-la para o registo de contentor.

1. No VSCode, vá para Terminal > New Terminal para abrir um novo terminal integrado do Visual Studio Code.

2. Faça login no Docker inserindo o seguinte comando no terminal integrado.

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

   Use o servidor de login e o nome de usuário que você copiou do registro do contêiner.

   

3. Quando for solicitada a senha, forneça a senha. Você também pode recuperar os valores para servidor de logon, nome de usuário e senha das Chaves de Acesso em seu registro de contêiner no portal do Azure.

4. Depois que as credenciais forem fornecidas, você poderá enviar por push a imagem do módulo para o registro de contêiner do Azure. No VS Code Explorer, clique com o botão direito do mouse no arquivo de module.json e selecione Build and Push IoT Edge solution.

   

   Quando você diz ao Visual Studio Code para criar sua solução, ele executa dois comandos no terminal integrado: docker build e docker push. Estes dois comandos criam o código, colocam o CSharpModule.dll em contentores e enviam-no para o registo de contentor que especificou quando inicializou a solução.

   Você será solicitado a escolher a plataforma do módulo. Selecione amd64 correspondente ao Linux.

   

   Importante

   Apenas os módulos Linux são suportados.

   Poderá ver o seguinte aviso que pode ignorar:

   Program.cs(77,44): aviso CS1998: Este método assíncrono não tem operadores 'await' e será executado de forma síncrona. Considere usar o operador 'await' para aguardar chamadas de API sem bloqueio, ou 'await Task.Run(...)' para fazer trabalho vinculado à CPU em um thread em segundo plano.

5. Pode ver o endereço da imagem de contentor completo com a etiqueta no terminal integrado do VS Code. O endereço da imagem é construído a partir de informações que estão no arquivo module.json com o formato <repository>:<version>-<platform>. Para este artigo, deve ser parecido com mycontreg2.azurecr.io/filecopymodule:0.0.1-amd64.

Próximos passos

Para implantar e executar este módulo no Azure Stack Edge Pro FPGA, consulte as etapas em Adicionar um módulo.