Desenvolver um módulo de IoT Edge C# para mover ficheiros no Azure Stack Edge Pro

APLICA-SE A:Azure Stack Edge Pro - GPUAzure Stack Edge Pro 2Azure Stack Edge Pro RAzure Stack Edge Mini R

Este artigo explica como criar um módulo de IoT Edge para implementação com o seu dispositivo Azure Stack Edge Pro. O Azure Stack Edge Pro é uma solução de armazenamento que lhe permite processar dados e enviá-lo através da rede para o Azure.

Pode utilizar módulos do Azure IoT Edge com o Azure Stack Edge Pro para transformar os dados à medida que são movidos para o Azure. O módulo utilizado neste artigo implementa a lógica para copiar um ficheiro de uma partilha local para uma partilha na cloud no seu dispositivo Azure Stack Edge Pro.

Neste artigo, vai aprender a:

• Crie um registo de contentor para armazenar e gerir os módulos (imagens do Docker).
• Crie um módulo IoT Edge para implementar no seu dispositivo Azure Stack Edge Pro.

Acerca do módulo IoT Edge

O seu dispositivo Azure Stack Edge Pro pode implementar e executar IoT Edge módulos. Os módulos edge são essencialmente contentores 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, irá criar um módulo que copia ficheiros de uma partilha local para uma partilha na cloud no seu dispositivo Azure Stack Edge Pro.

1. Os ficheiros são escritos na partilha local no seu dispositivo Azure Stack Edge Pro.
2. O gerador de eventos de ficheiros cria um evento de ficheiro para cada ficheiro escrito na partilha local. Os eventos de ficheiro também são gerados quando um ficheiro é modificado. Em seguida, os eventos de ficheiro são enviados para o Hub IoT Edge (em IoT Edge runtime).
3. O IoT Edge módulo personalizado processa o evento de ficheiro para criar um objeto de evento de ficheiro que também contém um caminho relativo para o ficheiro. O módulo gera um caminho absoluto com o caminho do ficheiro relativo e copia o ficheiro da partilha local para a partilha na cloud. Em seguida, o módulo elimina o ficheiro da partilha local.

Assim que o ficheiro estiver na partilha na cloud, este é carregado automaticamente para a sua conta de Armazenamento do Azure.

Pré-requisitos

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

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

  • O dispositivo também tem um recurso Hub IoT associado.
  • O dispositivo tem a função de computação edge configurada. Para obter mais informações, aceda a Configurar computação para o 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 de IoT Edge do Azure para Visual Studio Code.
  • SDK de .NET Core 2.1.
  • Docker CE. Poderá ter de criar uma conta para transferir e instalar o software.

Criar um registo de contentor

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 de registo populares do Docker disponíveis na cloud são Azure Container Registry e Docker Hub. Este artigo utiliza o Container Registry.

1. A partir de um browser, inicie sessão no portal do Azure.

2. Selecione Criar um recurso > Containers > Container Registry. Clique em Criar.

3. Indique:

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

   2. Escolha uma Subscrição.

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

   4. Selecione uma Localização. Recomendamos que esta localização seja a mesma que está associada ao recurso do 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. Utilize estes valores mais tarde para publicar a imagem do Docker no seu registo e para adicionar as credenciais de registo ao runtime de IoT Edge do Azure.

Criar um projeto do módulo do IoT Edge

Os passos seguintes criam um projeto de módulo IoT Edge baseado no SDK .NET Core 2.1. O projeto utiliza o Visual Studio Code e a extensão IoT Edge do Azure.

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 Ver > Paleta de Comandos para abrir a paleta de comandos do 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 o modelo de módulo.

   4. Substitua o nome do módulo predefinido pelo nome que pretende atribuir, neste caso, é FileCopyModule.

      

   5. Especifique o registo de contentor que criou na secção anterior como o repositório de imagens do seu primeiro módulo. Substitua localhost:5000 pelo valor do servidor de início de sessão que copiou.

      A cadeia final é semelhante <Login server name>/<Module name>a . Neste exemplo, a cadeia é: mycontreg2.azurecr.io/filecopymodule.

      

4. Aceda a Abrir Pasta de Ficheiros>.

   

5. Navegue e aponte para a pasta EdgeSolution que criou anteriormente. A janela do VS Code carrega a área de trabalho da solução IoT Edge com os cinco componentes de nível superior. Não irá editar a pasta, o .vscode ficheiro .gitignore , o ficheiro .env e o deployment.template.json** neste artigo.

   O único componente que modifica é a pasta módulos. Esta pasta tem o código C# para o módulo e os ficheiros do Docker para criar o módulo como uma imagem de contentor.

   

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 espaço de nomes FileCopyModule, adicione as seguintes instruções de utilização para tipos que são utilizados mais tarde. Microsoft.Azure.Devices.Client.Transport.Mqtt é um protocolo para enviar mensagens para IoT Edge Hub.

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

3. Adicione a variável 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 o passo 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 ligue ao runtime local do Azure IoT Edge com 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 regista uma chamada de retorno FileCopy para receber mensagens de um hub IoT Edge através do ponto final input1. Substitua o método Init pelo seguinte código.

   /// <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 do método PipeMessage e, no respetivo local, 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. Também pode transferir um exemplo de código existente para este projeto. Em seguida, pode validar o ficheiro que guardou no ficheiro program.cs neste exemplo.

Criar a sua solução do IoT Edge

Na secção anterior, criou uma solução IoT Edge e adicionou código ao FileCopyModule para copiar ficheiros da partilha local para a partilha na cloud. Agora, tem de criar a solução como uma imagem de contentor e enviá-la para o registo de contentor.

1. No VSCode, aceda a Terminal > Novo Terminal para abrir um novo terminal integrado do Visual Studio Code.

2. Inicie sessão no Docker ao introduzir o seguinte comando no terminal integrado.

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

   Utilize o servidor de início de sessão e o nome de utilizador que copiou do seu registo de contentor.

   

3. Quando lhe for pedida a palavra-passe, forneça a palavra-passe. Também pode obter os valores para o servidor de início de sessão, o nome de utilizador e a palavra-passe das Chaves de Acesso no seu registo de contentor no portal do Azure.

4. Assim que as credenciais forem fornecidas, pode enviar a imagem do módulo para o registo de contentor do Azure. No Explorador do VS Code, clique com o botão direito do rato no ficheiro module.json e selecione Compilar e Emitir IoT Edge solução.

   

   Quando diz ao Visual Studio Code para criar a sua solução, esta 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.

   Ser-lhe-á pedido para escolher a plataforma do módulo. Selecione amd64 correspondente a Linux.

   

   Importante

   Apenas os módulos do 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 utilizar o operador "await" para aguardar chamadas à API sem bloqueio ou "await Task.Run(...)" para realizar o trabalho vinculado à CPU num 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 é criado a partir de informações que estão no ficheiro module.json com o formato <repository>:<version>-<platform>. Para este artigo, deverá ter o aspeto mycontreg2.azurecr.io/filecopymodule:0.0.1-amd64de .

Passos seguintes

Para implementar e executar este módulo no Azure Stack Edge Pro, veja os passos em Adicionar um módulo.