Opracowywanie modułu usługi IoT Edge w języku C# w celu przenoszenia plików za pomocą fpGA usługi Azure Stack Edge Pro

Ważne

Urządzenia FPGA usługi Azure Stack Edge Pro osiągną koniec użytkowania w lutym 2024 r. Jeśli rozważasz nowe wdrożenia, zalecamy zapoznanie się z urządzeniami gpu Azure Stack Edge Pro 2 lub Azure Stack Edge Pro dla obciążeń.

W tym artykule opisano sposób tworzenia modułu usługi IoT Edge na potrzeby wdrażania przy użyciu urządzenia FPGA usługi Azure Stack Edge Pro. Azure Stack Edge Pro FPGA to rozwiązanie magazynu, które umożliwia przetwarzanie danych i wysyłanie ich za pośrednictwem sieci na platformę Azure.

Moduły usługi Azure IoT Edge można używać z układem FPGA usługi Azure Stack Edge Pro, aby przekształcić dane w miarę przenoszenia ich na platformę Azure. Moduł używany w tym artykule implementuje logikę kopiowania pliku z udziału lokalnego do udziału w chmurze na urządzeniu FPGA usługi Azure Stack Edge Pro.

W tym artykule omówiono sposób wykonywania następujących zadań:

• Utwórz rejestr kontenerów do przechowywania modułów i zarządzania nimi (obrazy platformy Docker).
• Utwórz moduł usługi IoT Edge do wdrożenia na urządzeniu FPGA usługi Azure Stack Edge Pro.

Informacje o module usługi IoT Edge

Urządzenie FPGA usługi Azure Stack Edge Pro może wdrażać i uruchamiać moduły usługi IoT Edge. Moduły usługi Edge to zasadniczo kontenery platformy Docker, które wykonują określone zadanie, takie jak pozyskiwanie komunikatu z urządzenia, przekształcanie komunikatu lub wysyłanie komunikatu do usługi IoT Hub. W tym artykule utworzysz moduł, który kopiuje pliki z udziału lokalnego do udziału w chmurze na urządzeniu FPGA usługi Azure Stack Edge Pro.

1. Pliki są zapisywane w udziale lokalnym na urządzeniu FPGA usługi Azure Stack Edge Pro.
2. Generator zdarzeń pliku tworzy zdarzenie pliku dla każdego pliku zapisanego w udziale lokalnym. Zdarzenia pliku są również generowane po zmodyfikowaniu pliku. Zdarzenia plików są następnie wysyłane do usługi IoT Edge Hub (w środowisku uruchomieniowym usługi IoT Edge).
3. Niestandardowy moduł usługi IoT Edge przetwarza zdarzenie pliku w celu utworzenia obiektu zdarzenia pliku, który zawiera również ścieżkę względną dla pliku. Moduł generuje ścieżkę bezwzględną przy użyciu względnej ścieżki pliku i kopiuje plik z udziału lokalnego do udziału w chmurze. Następnie moduł usuwa plik z udziału lokalnego.

Gdy plik znajduje się w udziale w chmurze, zostanie on automatycznie przekazany do konta usługi Azure Storage.

Wymagania wstępne

Zanim się zacznie, upewnij się, że masz:

• Uruchomione urządzenie FPGA usługi Azure Stack Edge Pro.

  • Urządzenie ma również skojarzony zasób usługi IoT Hub.
  • Na urządzeniu skonfigurowano rolę obliczeniową usługi Edge. Aby uzyskać więcej informacji, zobacz Configure compute for your Azure Stack Edge Pro FPGA (Konfigurowanie obliczeń dla fpga usługi Azure Stack Edge Pro).

• Następujące zasoby programistyczne:

  • Program Visual Studio Code
  • Rozszerzenie C# for Visual Studio Code (obsługiwane przez technologię OmniSharp)
  • Rozszerzenie usługi Azure IoT Edge dla programu Visual Studio Code
  • Zestaw .NET Core 2.1 SDK.
  • Program Docker CE. Może być konieczne utworzenie konta w celu pobrania i zainstalowania oprogramowania.

Tworzenie rejestru kontenerów

Usługa Azure Container Registry to rejestr prywatny platformy Docker na platformie Azure, w którym można przechowywać prywatne obrazy kontenerów Docker i zarządzać nimi. Dwie popularne usługi rejestru platformy Docker dostępne w chmurze to Azure Container Registry i Docker Hub. W tym artykule jest używany rejestr kontenerów.

1. W przeglądarce przejdź do witryny Azure Portal.

2. Wybierz pozycję Utwórz zasób > Container > Registry. Kliknij pozycję Utwórz.

3. Zapewnić:

   1. Unikatowa nazwa rejestru na platformie Azure zawierająca od 5 do 50 znaków alfanumerycznych.

   2. Wybierz subskrypcję.

   3. Utwórz nową lub wybierz istniejącą grupę zasobów.

   4. Wybierz lokalizację. Zalecamy, aby ta lokalizacja jest taka sama jak ta, która jest skojarzona z zasobem usługi Azure Stack Edge.

   5. Przełącz pozycję Administrator na wartość Włącz.

   6. Dla jednostki SKU ustaw wartość Podstawowa.

      

4. Wybierz pozycję Utwórz.

5. Po utworzeniu rejestru kontenerów przejdź do niego i wybierz pozycję Klucze dostępu.

   

6. Skopiuj wartości w polach Serwer logowania, Nazwa użytkownika i Hasło. Te wartości będą później używane do publikowania obrazu platformy Docker w rejestrze i dodawania poświadczeń rejestru do środowiska uruchomieniowego usługi Azure IoT Edge.

Tworzenie projektu modułu usługi IoT Edge

Poniższe kroki umożliwiają utworzenie projektu modułu usługi IoT Edge na podstawie zestawu .NET Core 2.1 SDK. Projekt korzysta z programu Visual Studio Code i rozszerzenia usługi Azure IoT Edge.

Utwórz nowe rozwiązanie

Utwórz szablon rozwiązania w języku C#, który można dostosować przy użyciu własnego kodu.

1. W programie Visual Studio Code wybierz pozycję Wyświetl > paletę poleceń, aby otworzyć paletę poleceń programu VS Code.

2. W palecie poleceń wprowadź i uruchom polecenie Azure: zaloguj się, a następnie postępuj zgodnie z instrukcjami, aby zalogować się na koncie platformy Azure. Jeśli już się zalogowano, można pominąć ten krok.

3. W palecie poleceń wprowadź i uruchom polecenie Azure IoT Edge: nowe rozwiązanie usługi IoT Edge. W palecie poleceń podaj następujące informacje, aby utworzyć rozwiązanie:

   1. Wybierz folder, w którym chcesz utworzyć rozwiązanie.

   2. Podaj nazwę rozwiązania lub zaakceptuj nazwę domyślną EdgeSolution.

      

   3. Wybierz szablon modułu C# Module (Moduł języka C#).

   4. Zastąp domyślną nazwę modułu nazwą, którą chcesz przypisać, w tym przypadku jest to FileCopyModule.

      

   5. Określ rejestr kontenerów utworzony w poprzedniej sekcji jako repozytorium obrazów dla pierwszego modułu. Zastąp ciąg localhost:5000 skopiowaną wartością serwera logowania.

      Ostatni ciąg wygląda następująco: <Login server name>/<Module name>. W tym przykładzie ciąg to: mycontreg2.azurecr.io/filecopymodule.

      

4. Przejdź do pozycji Plik > Otwórz folder.

   

5. Przejdź do utworzonego wcześniej folderu EdgeSolution i wskaż go. Okno programu VS Code ładuje obszar roboczy rozwiązania usługi IoT Edge z pięcioma składnikami najwyższego poziomu. Nie będziesz edytować folderu .vscode , pliku gitignore , pliku env i deployment.template.json w tym artykule.

   Jedynym składnikiem, który modyfikujesz, jest folder modules. Ten folder zawiera kod języka C# dla modułu i plików platformy Docker w celu skompilowania modułu jako obrazu kontenera.

   

Aktualizowanie modułu przy użyciu kodu niestandardowego

1. W eksploratorze programu VS Code otwórz moduły > FileCopyModule > Program.cs.

2. W górnej części przestrzeni nazw FileCopyModule dodaj następujące instrukcje using dla typów, które są używane później. Microsoft.Azure.Devices.Client.Transport.Mqtt to protokół do wysyłania komunikatów do usługi IoT Edge Hub.

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

3. Dodaj zmienną InputFolderPath i OutputFolderPath do klasy Program.

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

4. Bezpośrednio po poprzednim kroku dodaj klasę FileEvent , aby zdefiniować treść komunikatu.

   /// <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. W metodzie Init kod tworzy i konfiguruje obiekt ModuleClient. Ten obiekt umożliwia modułowi łączenie się z lokalnym środowiskiem uruchomieniowym usługi Azure IoT Edge przy użyciu protokołu MQTT do wysyłania i odbierania komunikatów. Parametry połączenia używane w metodzie Init są dostarczane do modułu za pośrednictwem środowiska uruchomieniowego usługi IoT Edge. Kod rejestruje wywołanie zwrotne narzędzia FileCopy w celu odbierania komunikatów z centrum usługi IoT Edge za pośrednictwem punktu końcowego input1 . Zastąp metodę Init następującym kodem.

   /// <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. Usuń kod metody PipeMessage i w jego miejscu wstaw kod narzędzia 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. Zapisz ten plik.

8. Możesz również pobrać istniejący przykładowy kod dla tego projektu. Następnie możesz zweryfikować plik zapisany w pliku program.cs w tym przykładzie.

Kompilowanie rozwiązania usługi IoT Edge

W poprzedniej sekcji utworzono rozwiązanie usługi IoT Edge i dodano kod do modułu FileCopyModule w celu skopiowania plików z udziału lokalnego do udziału w chmurze. Teraz należy skompilować to rozwiązanie jako obraz kontenera i wypchnąć go do rejestru kontenerów.

1. W programie VSCode przejdź do pozycji Terminal > Nowy terminal, aby otworzyć nowy zintegrowany terminal programu Visual Studio Code.

2. Zaloguj się do platformy Docker, wprowadzając następujące polecenie w zintegrowanym terminalu.

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

   Użyj serwera logowania i nazwy użytkownika skopiowanej z rejestru kontenerów.

   

3. Po wyświetleniu monitu o podanie hasła podaj hasło. Możesz również pobrać wartości serwera logowania, nazwy użytkownika i hasła z kluczy dostępu w rejestrze kontenerów w witrynie Azure Portal.

4. Po podaniu poświadczeń możesz wypchnąć obraz modułu do rejestru kontenerów platformy Azure. W Eksploratorze programu VS Code kliknij prawym przyciskiem myszy plik module.json i wybierz pozycję Kompiluj i wypychaj rozwiązanie usługi IoT Edge.

   

   Gdy poinformujesz program Visual Studio Code o utworzeniu rozwiązania, uruchamia dwa polecenia w zintegrowanym terminalu: kompilacja platformy Docker i wypychanie platformy Docker. Te dwa polecenia kompilują kod, konteneryzują plik CSharpModule.dll i wypychają go do rejestru kontenerów określonego podczas inicjowania rozwiązania.

   Zostanie wyświetlony monit o wybranie platformy modułu. Wybierz pozycję amd64 odpowiadającą systemowi Linux.

   

   Ważne

   Obsługiwane są tylko moduły systemu Linux.

   Może zostać wyświetlone następujące ostrzeżenie, które można zignorować:

   Program.cs(77,44): ostrzeżenie CS1998: Ta metoda asynchroniczna nie zawiera operatorów "await" i zostanie uruchomiona synchronicznie. Rozważ użycie operatora "await", aby oczekiwać na nieblokacyjne wywołania interfejsu API lub "await Task.Run(...)", aby wykonać pracę związaną z procesorem CPU w wątku w tle.

5. Pełny adres obrazu kontenera możesz wyświetlić za pomocą tagu w zintegrowanym terminalu programu VS Code. Adres obrazu jest tworzony na podstawie informacji w pliku module.json o formacie <repository>:<version>-<platform>. W tym artykule powinien wyglądać następująco: mycontreg2.azurecr.io/filecopymodule:0.0.1-amd64.

Następne kroki

Aby wdrożyć i uruchomić ten moduł w usłudze Azure Stack Edge Pro FPGA, zobacz kroki opisane w temacie Dodawanie modułu.