Samouczek: tworzenie modułów usługi IoT Edge przy użyciu programu Visual Studio Code

Dotyczy:IoT Edge 1.4 checkmark IoT Edge 1.4

Ważne

Azure IoT Edge1.4 jest obsługiwaną wersją. Jeśli korzystasz z wcześniejszej wersji, zobacz aktualizację Azure IoT Edge.

Ten samouczek przeprowadzi Cię przez proces tworzenia i wdrażania własnego kodu na urządzeniu usługi IoT Edge. Moduły usługi Azure IoT Edge umożliwiają wdrożenie kodu implementującego logikę biznesową bezpośrednio na urządzeniach usługi IoT Edge. W przewodniku Szybki start Wdrażanie kodu na urządzeniu z systemem Linux utworzono urządzenie usługi IoT Edge i wdrożono moduł z witryny Azure Marketplace.

Ten artykuł zawiera kroki dotyczące dwóch narzędzi deweloperskich usługi IoT Edge.

  • Wiersz polecenia (CLI) narzędzia deweloperskiego usługi Azure IoT Edge. To narzędzie jest preferowane do programowania.
  • Narzędzia usługi Azure IoT Edge dla rozszerzenia programu Visual Studio Code . Rozszerzenie jest w trybie konserwacji.

Użyj przycisku selektora narzędzi na początku tego artykułu, aby wybrać wersję narzędzia.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Skonfiguruj maszynę dewelopera.
  • Użyj narzędzi usługi IoT Edge, aby utworzyć nowy projekt.
  • Skompiluj projekt jako kontener platformy Docker i zapisz go w rejestrze kontenerów platformy Azure.
  • Wdróż kod na urządzeniu usługi IoT Edge.

Moduł usługi IoT Edge utworzony w tym samouczku filtruje dane temperatury generowane przez urządzenie. Komunikaty są wysyłane tylko wtedy, gdy temperatura przekroczy określony próg. Ten typ analizy brzegowej pomaga zmniejszyć ilość danych przekazywanych do chmury i w niej przechowywanych.

Wymagania wstępne

Maszyna deweloperna:

  • Użyj własnego komputera lub maszyny wirtualnej.
  • Maszyna deweloperów musi obsługiwać wirtualizację zagnieżdżonych na potrzeby uruchamiania aparatu kontenera.
  • Większość systemów operacyjnych, które mogą uruchamiać aparat kontenerów, może służyć do tworzenia modułów usługi IoT Edge dla urządzeń z systemem Linux. W tym samouczku jest używany komputer z systemem Windows, ale zwraca uwagę na znane różnice w systemie macOS lub Linux.
  • Instalacja programu Visual Studio Code
  • Zainstaluj interfejs wiersza polecenia platformy Azure.

Urządzenie usługi Azure IoT Edge:

Zasoby w chmurze:

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.

Napiwek

Aby uzyskać wskazówki dotyczące debugowania interaktywnego w programie Visual Studio Code lub Visual Studio 2022:

W tym samouczku przedstawiono kroki programistyczne dla programu Visual Studio Code.

Najważniejsze pojęcia

Ten samouczek przeprowadzi Cię przez proces tworzenia modułu usługi IoT Edge. Moduł usługi IoT Edge to kontener z kodem wykonywalnym. Możesz wdrożyć jeden lub więcej modułów na urządzeniu usługi IoT Edge. Moduły wykonują określone zadania, takie jak pozyskiwanie danych z czujników, czyszczenie i analizowanie danych lub wysyłanie komunikatów do centrum IoT. Aby uzyskać więcej informacji, zobacz Omówienie modułów usługi Azure IoT Edge.

Podczas tworzenia modułów usługi IoT Edge należy zrozumieć różnicę między maszyną deweloperską a docelowym urządzeniem usługi IoT Edge, na którym wdraża moduł. Kontener, który jest kompilowalny do przechowywania kodu modułu, musi być zgodny z systemem operacyjnym urządzenia docelowego. Na przykład najbardziej typowym scenariuszem jest utworzenie modułu na komputerze z systemem Windows, które ma być przeznaczone dla urządzenia z systemem Linux z uruchomioną usługą IoT Edge. W takim przypadku system operacyjny kontenera to Linux. Podczas pracy z tym samouczkiem należy pamiętać o różnicy między systemem operacyjnym maszyny dewelopera i systemem operacyjnym kontenera.

Napiwek

Jeśli używasz usługi IoT Edge dla systemu Linux w systemie Windows, urządzenie docelowe w twoim scenariuszu jest maszyną wirtualną z systemem Linux, a nie hostem systemu Windows.

Ten samouczek dotyczy urządzeń z usługą IoT Edge z kontenerami systemu Linux. Możesz użyć preferowanego systemu operacyjnego, o ile maszyna programistyjna uruchamia kontenery systemu Linux. Zalecamy używanie programu Visual Studio Code do tworzenia aplikacji za pomocą kontenerów systemu Linux, aby użyć tego samouczka. Można również użyć programu Visual Studio, chociaż istnieją różnice w obsłudze między dwoma narzędziami.

W poniższej tabeli wymieniono obsługiwane scenariusze programistyczne dla kontenerów systemu Linux w programach Visual Studio Code i Visual Studio.

Visual Studio Code Visual Studio 2019/2022
Architektura urządzenia z systemem Linux Linux AMD64
Linux ARM32v7
Linux ARM64
Linux AMD64
Linux ARM32
Linux ARM64
Usługi platformy Azure Azure Functions
Azure Stream Analytics
Azure Machine Learning
Języki C
C#
Java
Node.js
Python
C
C#
Więcej informacji Usługa Azure IoT Edge dla programu Visual Studio Code Azure IoT Edge Tools for Visual Studio 2019
Azure IoT Edge Tools for Visual Studio 2022

Instalowanie aparatu kontenera

Moduły usługi IoT Edge są pakowane jako kontenery, dlatego do kompilowania i zarządzania nimi potrzebny jest system zarządzania kontenerami zgodnymi z platformą Docker. Zalecamy programowanie aplikacji Docker Desktop ze względu na jego obsługę funkcji i popularność. Program Docker Desktop w systemie Windows umożliwia przełączanie się między kontenerami systemu Linux i kontenerami systemu Windows, dzięki czemu można tworzyć moduły dla różnych typów urządzeń usługi IoT Edge.

Użyj dokumentacji platformy Docker, aby zainstalować na maszynie deweloperów:

Konfigurowanie narzędzi

Zainstaluj narzędzie deweloperskie usługi Azure IoT Edge oparte na języku Python, aby utworzyć rozwiązanie usługi IoT Edge. Dostępne są dwie opcje:

Ważne

Rozszerzenia usługi Azure IoT Edge dla programu Visual Studio Code są w trybie konserwacji. Preferowane narzędzie programistyczne to narzędzie wiersza polecenia (CLI) usługi Azure IoT Edge Dev Tool.

Użyj rozszerzeń IoT dla programu Visual Studio Code do tworzenia modułów usługi IoT Edge. Te rozszerzenia oferują szablony projektów, automatyzują tworzenie manifestu wdrożenia i umożliwiają monitorowanie urządzeń usługi IoT Edge i zarządzanie nimi. W tej sekcji zainstalujesz program Visual Studio Code i rozszerzenie IoT, a następnie skonfigurujesz konto platformy Azure, aby zarządzać zasobami usługi IoT Hub z poziomu programu Visual Studio Code.

  1. Zainstaluj rozszerzenie usługi Azure IoT Edge .

  2. Zainstaluj rozszerzenie usługi Azure IoT Hub .

  3. Po zainstalowaniu rozszerzeń otwórz paletę poleceń, wybierając pozycję Wyświetl>paletę poleceń.

  4. W palecie poleceń ponownie wyszukaj i wybierz pozycję Azure IoT Hub: wybierz pozycję IoT Hub. Postępuj zgodnie z monitami, aby wybrać subskrypcję platformy Azure i usługę IoT Hub.

  5. Otwórz sekcję eksploratora programu Visual Studio Code, wybierając ikonę na pasku działań po lewej stronie lub wybierając pozycję Eksplorator widoków>.

  6. W dolnej części sekcji eksploratora rozwiń zwinięte menu Usługi Azure IoT Hub/Urządzenia . Powinny zostać wyświetlone urządzenia i urządzenia usługi IoT Edge skojarzone z usługą IoT Hub wybraną za pomocą palety poleceń.

Instalowanie narzędzi specyficznych dla języka

Zainstaluj narzędzia specyficzne dla języka, w którym programujesz:

Tworzenie rejestru kontenerów

W tym samouczku użyjesz rozszerzeń usług Azure IoT Edge i Azure IoT Hub do skompilowania modułu i utworzenia obrazu kontenera z plików. Następnie ten obraz zostanie wypchnięty do rejestru, w którym obrazy są przechowywane i zarządzane. Na koniec obraz zostanie wdrożony z rejestru w celu uruchomienia na urządzeniu usługi IoT Edge.

Ważne

Rozszerzenie programu Visual Studio Code usługi Azure IoT Edge jest w trybie konserwacji.

Do przechowywania obrazów kontenerów możesz użyć dowolnego rejestru zgodnego z platformą Docker. Dwie popularne usługi rejestru Docker to Azure Container Registry i Docker Hub. W tym samouczku używana jest usługa Azure Container Registry.

Jeśli nie masz jeszcze rejestru kontenerów, wykonaj następujące kroki, aby utworzyć nowy rejestr na platformie Azure:

  1. W witrynie Azure Portal wybierz kolejno pozycje Utwórz zasób>Kontenery>Container Registry.

  2. Podaj następujące wymagane wartości do utworzenia rejestru kontenerów:

    Pole Wartość
    Subskrypcja Wybierz subskrypcję z listy rozwijanej.
    Grupa zasobów Użyj tej samej grupy zasobów dla wszystkich zasobów testowych tworzonych podczas przewodników Szybki start i samouczków usługi IoT Edge. Na przykład IoTEdgeResources.
    Nazwa rejestru Podaj unikatową nazwę.
    Lokalizacja Wybierz bliską lokalizację.
    SKU Wybierz pozycję Podstawowa.
  3. Wybierz pozycję Przejrzyj i utwórz, a następnie pozycję Utwórz.

  4. Wybierz nowy rejestr kontenerów w sekcji Zasoby na stronie głównej witryny Azure Portal, aby go otworzyć.

  5. W lewym okienku rejestru kontenerów wybierz pozycję Klucze dostępu z menu znajdującego się w obszarze Ustawienia.

    Screenshot of the Access Keys menu location.

  6. Włącz Administracja użytkownika za pomocą przycisku przełącznika i wyświetl nazwę użytkownika i hasło dla rejestru kontenerów.

  7. Skopiuj wartości serwera logowania, nazwy użytkownika i hasła i zapisz je w dogodnym miejscu. Te wartości są używane w tym samouczku, aby zapewnić dostęp do rejestru kontenerów.

Tworzenie nowego projektu modułu

Rozszerzenie usługi Azure IoT Edge oferuje szablony projektów dla wszystkich obsługiwanych języków modułów usługi IoT Edge w programie Visual Studio Code. Te szablony mają wszystkie pliki i kod, które należy wdrożyć w module roboczym w celu przetestowania usługi IoT Edge, lub dają punkt wyjścia umożliwiający dostosowanie szablonu przy użyciu własnej logiki biznesowej.

Tworzenie szablonu projektu

Narzędzie deweloperskie usługi IoT Edge upraszcza programowanie usługi Azure IoT Edge w poleceniach opartych na zmiennych środowiskowych. Rozpoczynanie pracy z programowaniem usługi IoT Edge za pomocą kontenera deweloperskiego usługi IoT Edge i szkieletu rozwiązania usługi IoT Edge z domyślnym modułem i wszystkimi wymaganymi plikami konfiguracji.

  1. Utwórz katalog dla swojego rozwiązania przy użyciu wybranej ścieżki. Przejdź do iotedgesolution katalogu.

    mkdir c:\dev\iotedgesolution
    cd c:\dev\iotedgesolution
    
  2. Użyj polecenia init rozwiązania iotedgedev, aby utworzyć rozwiązanie i skonfigurować usługę Azure IoT Hub w wybranym języku programowania.

    iotedgedev solution init --template csharp
    

Skrypt inicjowania rozwiązania iotedgedev monituje o wykonanie kilku kroków, w tym:

  • Uwierzytelnianie na platformie Azure
  • Wybieranie subskrypcji platformy Azure
  • Wybieranie lub tworzenie grupy zasobów
  • Wybieranie lub tworzenie usługi Azure IoT Hub
  • Wybieranie lub tworzenie urządzenia usługi Azure IoT Edge

Użyj programu Visual Studio Code i rozszerzenia usługi Azure IoT Edge . Zacznij od utworzenia rozwiązania, a następnie wygenerowania pierwszego modułu w tym rozwiązaniu. Każde rozwiązanie może zawierać wiele modułów.

  1. Wybierz pozycję Wyświetl>paletę poleceń.
  2. W palecie poleceń wprowadź i uruchom polecenie Azure IoT Edge: nowe rozwiązanie usługi IoT Edge.
  3. Przejdź do folderu, w którym chcesz utworzyć nowe rozwiązanie, a następnie wybierz pozycję Wybierz folder.
  4. Wprowadź nazwę rozwiązania.
  5. Wybierz szablon modułu, aby preferowany język programowania był pierwszym modułem w rozwiązaniu.
  6. Wprowadź nazwę modułu. Wybierz unikatową nazwę w rejestrze kontenerów.
  7. Podaj nazwę repozytorium obrazów modułu. Program Visual Studio Code automatycznie wypełnia nazwę modułu nazwą localhost:5000/<nazwa modułu>. Zastąp je własnymi informacjami rejestru. Użyj hosta lokalnego , jeśli używasz lokalnego rejestru platformy Docker do testowania. Jeśli używasz usługi Azure Container Registry, użyj serwera logowania z ustawień rejestru. Serwer logowania wygląda jak <nazwa> rejestru.azurecr.io. Zastąp tylko część ciągu localhost:5000, tak aby wynik końcowy wyglądał następująco:< nazwa> rejestru.azurecr.io/< nazwa> modułu.

Program Visual Studio Code pobiera podane informacje, tworzy rozwiązanie usługi IoT Edge, a następnie ładuje je w nowym oknie.

Po utworzeniu rozwiązania te główne pliki znajdują się w rozwiązaniu:

  • Folder .vscode zawiera plik konfiguracji launch.json.

  • Folder modules zawierający podfoldery dla każdego modułu. W podfolderze dla każdego modułu plik module.json kontroluje sposób kompilowania i wdrażania modułów.

  • Plik env zawiera listę zmiennych środowiskowych. Zmienna środowiskowa rejestru kontenerów jest domyślnie localhost:5000 .

  • Dwa pliki wdrażania modułu o nazwie deployment.template.json i deployment.debug.template.json wyświetlić listę modułów do wdrożenia na urządzeniu. Domyślnie lista zawiera moduły systemowe usługi IoT Edge (edgeAgent i edgeHub) oraz przykładowe moduły, takie jak:

    • filtermodule to przykładowy moduł, który implementuje prostą funkcję filtru.
    • Moduł SimulatedTemperatureSensor , który symuluje dane, których można użyć do testowania. Aby uzyskać więcej informacji na temat sposobu działania manifestów wdrażania, zobacz Dowiedz się, jak używać manifestów wdrażania do wdrażania modułów i ustanawiania tras. Aby uzyskać więcej informacji na temat działania modułu symulowanej temperatury, zobacz kod źródłowy SimulatedTemperatureSensor.csproj.

    Uwaga

    Dokładne zainstalowane moduły mogą zależeć od wybranego języka.

Ustawianie wersji środowiska uruchomieniowego usługi IoT Edge

Najnowsza stabilna wersja modułu systemu usługi IoT Edge to 1.4. Ustaw moduły systemowe na wersję 1.4.

  1. W programie Visual Studio Code otwórz plik manifestu wdrożenia deployment.template.json . Manifest wdrożenia to dokument JSON opisujący moduły do skonfigurowania na docelowym urządzeniu usługi IoT Edge.

  2. Zmień wersję środowiska uruchomieniowego dla obrazów modułu środowiska uruchomieniowego systemu edgeAgent i edgeHub. Jeśli na przykład chcesz użyć środowiska uruchomieniowego usługi IoT Edge w wersji 1.4, zmień następujące wiersze w pliku manifestu wdrożenia:

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

Podaj poświadczenia rejestru agentowi usługi IoT Edge

W pliku środowiska przechowywane są poświadczenia rejestru kontenerów udostępniane środowisku uruchomieniowemu usługi IoT Edge. Środowisko uruchomieniowe wymaga tych poświadczeń, aby ściągnąć obrazy kontenerów na urządzenie usługi IoT Edge.

Rozszerzenie usługi IoT Edge próbuje ściągnąć poświadczenia rejestru kontenerów z platformy Azure i wypełnić je w pliku środowiska.

Uwaga

Plik środowiska jest tworzony tylko wtedy, gdy udostępnisz repozytorium obrazów dla modułu. Jeśli zaakceptowano domyślne ustawienia localhost do testowania i debugowania lokalnie, nie musisz deklarować zmiennych środowiskowych.

Sprawdź, czy twoje poświadczenia istnieją. Jeśli nie, dodaj je teraz:

  1. Jeśli usługa Azure Container Registry jest rejestrem, ustaw nazwę użytkownika i hasło usługi Azure Container Registry. Pobierz te wartości z menu Ustawienia> Klucze dostępu rejestru kontenerów w witrynie Azure Portal.

  2. Otwórz plik env w rozwiązaniu modułu.

  3. Dodaj wartości nazwy użytkownika i hasła skopiowane z rejestru kontenerów platformy Azure. Na przykład:

    CONTAINER_REGISTRY_SERVER="myacr.azurecr.io"
    CONTAINER_REGISTRY_USERNAME="myacr"
    CONTAINER_REGISTRY_PASSWORD="<registry_password>"
    
  4. Zapisz zmiany w pliku env .

Uwaga

W tym samouczku są używane poświadczenia logowania administratora dla usługi Azure Container Registry, które są wygodne w scenariuszach tworzenia i testowania. Gdy wszystko będzie gotowe do scenariuszy produkcyjnych, zalecamy użycie opcji uwierzytelniania z najmniejszymi uprawnieniami, takich jak jednostki usługi lub tokeny o zakresie repozytorium. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do rejestru kontenerów.

Architektura docelowa

Musisz wybrać architekturę docelową dla każdego rozwiązania, ponieważ ma to wpływ na sposób kompilowania i uruchamiania kontenera. Wartość domyślna to Linux AMD64. W tym samouczku używamy maszyny wirtualnej z systemem Ubuntu jako urządzenia usługi IoT Edge i zachowamy domyślną wartość amd64.

Jeśli musisz zmienić architekturę docelową rozwiązania, wykonaj następujące kroki.

  1. Otwórz paletę poleceń i wyszukaj pozycję Azure IoT Edge: ustaw domyślną platformę docelową rozwiązania Edge lub wybierz ikonę skrótu na pasku bocznym w dolnej części okna.

  2. Na palecie poleceń wybierz architekturę docelową z listy opcji.

Architektura docelowa jest ustawiana podczas tworzenia obrazu kontenera w późniejszym kroku.

Aktualizowanie modułu przy użyciu kodu niestandardowego

Każdy szablon zawiera przykładowy kod, który pobiera symulowane dane czujnika z modułu SimulatedTemperatureSensor i kieruje go do centrum IoT. Przykładowy moduł odbiera komunikaty, a następnie przekazuje je dalej. Funkcja potoku przedstawia ważną koncepcję w usłudze IoT Edge, która polega na tym, jak moduły komunikują się ze sobą.

Każdy moduł może mieć wiele kolejek wejściowych i wyjściowych zadeklarowanych w kodzie. Centrum usługi IoT Edge uruchomione na urządzeniu kieruje komunikaty z danych wyjściowych jednego modułu do danych wejściowych co najmniej jednego modułu. Określony kod do deklarowania danych wejściowych i wyjściowych różni się między językami, ale koncepcja jest taka sama we wszystkich modułach. Aby uzyskać więcej informacji na temat routingu między modułami, zobacz Deklarowanie tras.

Przykładowy kod języka C# dostarczany z szablonem projektu używa klasy ModuleClient z zestawu SDK usługi IoT Hub dla platformy .NET.

  1. W eksploratorze programu Visual Studio Code otwórz moduły>filtermodule>ModuleBackgroundService.cs.

  2. Przed przestrzenią nazw filtermodule dodaj trzy instrukcje using dla typów, które są używane później:

    using System.Collections.Generic;     // For KeyValuePair<>
    using Microsoft.Azure.Devices.Shared; // For TwinCollection
    using Newtonsoft.Json;                // For JsonConvert
    
  3. Dodaj zmienną temperatureThreshold do klasy ModuleBackgroundService . Za pomocą tej zmiennej jest ustawiana wartość zmierzonej temperatury, której przekroczenie spowoduje wysłanie danych do centrum IoT Hub.

    static int temperatureThreshold { get; set; } = 25;
    
  4. Dodaj klasy MessageBody, Machine i Ambient. Te klasy definiują oczekiwany schemat treści komunikatów przychodzących.

    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. Znajdź funkcję ExecuteAsync. Ta funkcja tworzy i konfiguruje obiekt ModuleClient , który umożliwia modułowi łączenie się z lokalnym środowiskiem uruchomieniowym usługi Azure IoT Edge w celu wysyłania i odbierania komunikatów. Po utworzeniu elementu ModuleClient kod odczytuje wartość temperatureThreshold z żądanych właściwości bliźniaczej reprezentacji modułu. Kod rejestruje wywołanie zwrotne w celu odbierania komunikatów z centrum usługi IoT Edge za pośrednictwem punktu końcowego o nazwie input1.

    Zastąp wywołanie metody ProcessMessageAsync nową metodą, która aktualizuje nazwę punktu końcowego i metodę wywoływaną po nadejściu danych wejściowych. Ponadto dodaj metodę SetDesiredPropertyUpdateCallbackAsync , aby zaktualizować żądane właściwości. Aby wprowadzić tę zmianę, zastąp ostatni wierszmetody ExecuteAsync następującym kodem:

    // 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. Dodaj metodę onDesiredPropertiesUpdate do klasy ModuleBackgroundService . Ta metoda odbiera aktualizacje odpowiednich właściwości z bliźniaczej reprezentacji modułu i aktualizuje zmienną temperatureThreshold, aby ją dopasować. Wszystkie moduły mają swoje bliźniacze reprezentacje, dzięki czemu można skonfigurować kod działający wewnątrz modułu bezpośrednio z poziomu chmury.

    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. Dodaj metodę FilterMessages . Ta metoda jest wywoływana za każdym razem, gdy moduł odbiera komunikat z centrum usługi IoT Edge. Odfiltrowuje ona komunikaty zgłaszające temperatury nie przekraczające wartości progowej temperatury ustawionej za pomocą bliźniaczej reprezentacji modułu. Dodaje ona również właściwość MessageType do komunikatu z wartością ustawioną na 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. Zapisz plik ModuleBackgroundService.cs.

  9. W eksploratorze programu Visual Studio Code otwórz plik deployment.template.json w obszarze roboczym rozwiązania usługi IoT Edge.

  10. Ponieważ zmieniliśmy nazwę punktu końcowego, na który nasłuchuje moduł, musimy również zaktualizować trasy w manifeście wdrożenia, aby usługa edgeHub wysyłała komunikaty do nowego punktu końcowego.

    Znajdź sekcję trasy w bliźniaczej reprezentacji modułu $edgeHub . Zaktualizuj trasę sensorTofiltermodule, aby zastąpić input1 ciąg ciągiem inputFromSensor:

    "sensorTofiltermodule": "FROM /messages/modules/tempSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/inputFromSensor\")"
    
  11. Dodaj bliźniacze reprezentację modułu filtermodule do manifestu wdrożenia. Wstaw następującą zawartość do pliku JSON na końcu sekcji modulesContent po bliźniaczej reprezentacji modułu $edgeHub:

       "filtermodule": {
           "properties.desired":{
               "TemperatureThreshold":25
           }
       }
    
  12. Zapisz plik deployment.template.json.

Kompilowanie i wypychanie rozwiązania

Zaktualizowano kod modułu i szablon wdrożenia, aby ułatwić zrozumienie niektórych kluczowych pojęć związanych z wdrażaniem. Teraz możesz skompilować obraz kontenera modułu i wypchnąć go do rejestru kontenerów.

W programie Visual Studio Code otwórz plik manifestu wdrożenia deployment.template.json . Manifest wdrożenia opisuje moduły do skonfigurowania na docelowym urządzeniu usługi IoT Edge. Przed wdrożeniem należy zaktualizować poświadczenia usługi Azure Container Registry i obrazy modułów przy użyciu odpowiednich createOptions wartości. Aby uzyskać więcej informacji na temat wartości createOption, zobacz How to configure container create options for IoT Edge modules (Jak skonfigurować opcje tworzenia kontenera dla modułów usługi IoT Edge).

Jeśli używasz usługi Azure Container Registry do przechowywania obrazu modułu, dodaj poświadczenia do sekcji modulesContent>edgeAgent>settings>registryCredentials w deployment.template.json. Zastąp ciąg myacr własną nazwą rejestru i podaj hasło i adres serwera logowania. Na przykład:

"registryCredentials": {
    "myacr": {
        "username": "myacr",
        "password": "<your_acr_password>",
        "address": "myacr.azurecr.io"
    }
}

Dodaj lub zastąp następującą zawartość ciągową wartością createOptions dla każdego systemu (edgeHub i edgeAgent) oraz modułu niestandardowego (filtermodule i tempSensor). W razie potrzeby zmień wartości.

"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"

Na przykład konfiguracja modułu filtermodule powinna być podobna do następującej:

"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\"}]}}}"
}

Kompilowanie obrazu platformy Docker modułu

Otwórz zintegrowany terminal programu Visual Studio Code, wybierając pozycję Terminal>Nowy terminal.

Użyj polecenia , dotnet publish aby skompilować obraz kontenera dla architektury systemów Linux i amd64. Zmień katalog na katalog filtermodule w projekcie i uruchom polecenie dotnet publish .

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

Obecnie szablon narzędzia iotedgedev jest przeznaczony dla platformy .NET 7.0. Jeśli chcesz określić inną wersję platformy .NET, możesz edytować plik filtermodule.csproj i zmienić wartości TargetFramework i PackageReference . Na przykład w celu kierowania pliku .NET 8.0 plik filtermodule.csproj powinien wyglądać następująco:

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

Oznacz obraz platformy Docker informacjami, wersją i architekturą rejestru kontenerów. Zastąp ciąg myacr własną nazwą rejestru.

docker tag filtermodule myacr.azurecr.io/filtermodule:0.0.1-amd64

Obraz platformy Docker modułu wypychania

Podaj poświadczenia rejestru kontenerów do platformy Docker, aby umożliwić wypchnięcie obrazu kontenera do magazynu w rejestrze.

  1. Zaloguj się do platformy Docker przy użyciu poświadczeń usługi Azure Container Registry (ACR).

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

    Może zostać wyświetlone ostrzeżenie o zabezpieczeniach, które zaleca użycie polecenia --password-stdin. Chociaż jest to zalecane najlepsze rozwiązanie dla scenariuszy produkcyjnych, wykracza poza zakres tego samouczka. Aby uzyskać więcej informacji, zobacz dokumentację logowania platformy Docker.

  2. Zaloguj się do usługi Azure Container Registry. Aby użyć polecenia , musisz zainstalować interfejs wiersza polecenia platformy az Azure. To polecenie prosi o podanie nazwy użytkownika i hasła znalezionego w rejestrze kontenerów w kluczach Ustawienia> Access.

    az acr login -n <ACR registry name>
    

    Napiwek

    Jeśli w dowolnym momencie tego samouczka wylogujesz się, powtórz kroki logowania do platformy Docker i usługi Azure Container Registry, aby kontynuować.

  3. Wypchnij obraz modułu do rejestru lokalnego lub rejestru kontenerów.

    docker push <ImageName>
    

    Na przykład:

    # 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
    

Aktualizowanie szablonu wdrożenia

Zaktualizuj szablon wdrożenia deployment.template.json za pomocą lokalizacji obrazu rejestru kontenerów. Jeśli na przykład używasz usługi Azure Container Registry myacr.azurecr.io , a obraz to filtermodule:0.0.1-amd64, zaktualizuj konfigurację modułu filtermodule na:

"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\"}]}}}"
    }
}

W eksploratorze programu Visual Studio Code kliknij prawym przyciskiem myszy plik deployment.template.json i wybierz polecenie Kompiluj i wypychaj rozwiązanie usługi IoT Edge.

Polecenie kompilacji i wypychania uruchamia trzy operacje. Najpierw tworzy nowy folder w rozwiązaniu o nazwie config , który zawiera pełny manifest wdrożenia, utworzony z informacji w szablonie wdrożenia i innych plikach rozwiązań. Po drugie uruchamia docker build polecenie w celu skompilowania obrazu kontenera na podstawie odpowiedniego pliku dockerfile dla architektury docelowej. Następnie zostanie uruchomione polecenie docker push , aby wypchnąć repozytorium obrazów do rejestru kontenerów.

Ten proces może potrwać kilka minut po raz pierwszy, ale jest szybszy przy następnym uruchomieniu poleceń.

Opcjonalnie: aktualizowanie modułu i obrazu

Jeśli wprowadzisz zmiany w kodzie modułu, musisz ponownie skompilować i wypchnąć obraz modułu do rejestru kontenerów. Wykonaj kroki opisane w tej sekcji, aby zaktualizować obraz kompilacji i kontenera. Możesz pominąć tę sekcję, jeśli nie wprowadzono żadnych zmian w kodzie modułu.

Otwórz plik deployment.amd64.json w nowo utworzonym folderze konfiguracji. Nazwa pliku odzwierciedla architekturę docelową, więc różni się, jeśli wybrano inną architekturę.

Zwróć uwagę, że dwa parametry, które miały symbole zastępcze, zawierają teraz odpowiednie wartości. Sekcja registryCredentials zawiera nazwę użytkownika rejestru i hasło pobrane z pliku env . Moduł filtermodule ma pełne repozytorium obrazów z nazwą, wersją i tagiem architektury z pliku module.json .

  1. Otwórz plik module.json w folderze filtermodule.

  2. Zmień numer wersji obrazu modułu. Na przykład zwiększ numer wersji poprawki tak "version": "0.0.2" , jakby wprowadzono niewielką poprawkę w kodzie modułu.

    Napiwek

    Wersje modułów umożliwiają kontrolę wersji i umożliwiają testowanie zmian na małym zestawie urządzeń przed wdrożeniem aktualizacji w środowisku produkcyjnym. Jeśli nie zwiększasz wersji modułu przed utworzeniem i wypchnięciem, zastąpisz repozytorium w rejestrze kontenerów.

  3. Zapisz zmiany w pliku module.json .

Skompiluj i wypchnij zaktualizowany obraz z tagiem wersji 0.0.2 . Aby na przykład skompilować i wypchnąć obraz dla rejestru lokalnego lub rejestru kontenerów platformy Azure, użyj następujących poleceń:


# 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

Ponownie kliknij prawym przyciskiem myszy plik deployment.template.json, a następnie ponownie wybierz pozycję Kompiluj i wypychaj rozwiązanie usługi IoT Edge.

Otwórz ponownie plik deployment.amd64.json. Zwróć uwagę, że system kompilacji nie tworzy nowego pliku podczas ponownego uruchamiania polecenia kompilacji i wypychania. Zamiast tego te same aktualizacje plików odzwierciedlają zmiany. Obraz filtermodule wskazuje teraz wersję 0.0.2 kontenera.

Aby dokładniej sprawdzić, co zrobiło polecenie kompilacji i wypychania, przejdź do witryny Azure Portal i przejdź do rejestru kontenerów.

W rejestrze kontenerów wybierz pozycję Repozytoria , a następnie filtrujmodule. Sprawdź, czy obie wersje obrazu są wypychane do rejestru.

Screenshot of where to view both image versions in your container registry.

Rozwiązywanie problemów

Jeśli podczas kompilowania i wypychania obrazu modułu wystąpią błędy, często trzeba to zrobić z konfiguracją platformy Docker na maszynie dewelopera. Aby przejrzeć konfigurację, wykonaj następujące testy:

  • Czy uruchomiono docker login polecenie przy użyciu poświadczeń skopiowanych z rejestru kontenerów? Te poświadczenia różnią się od tych, których używasz do logowania się na platformie Azure.
  • Czy używasz właściwego repozytorium kontenerów? Czy ma poprawną nazwę rejestru kontenerów i poprawną nazwę modułu? Otwórz plik module.json w folderze filtermodule, aby sprawdzić. Wartość repozytorium powinna wyglądać następująco: <nazwa> rejestru.azurecr.io/filtermodule.
  • Jeśli dla modułu użyto innej nazwy niż filtermodule , czy nazwa jest spójna w całym rozwiązaniu?
  • Czy maszyna korzysta z tego samego typu kontenerów, które tworzysz? Ten samouczek dotyczy urządzeń usługi IoT Edge z systemem Linux, więc program Visual Studio Code powinien powiedzieć amd64 lub arm32v7 na pasku bocznym, a program Docker Desktop powinien uruchamiać kontenery systemu Linux.

Wdrażanie modułów na urządzeniu

Sprawdzono, że istnieją wbudowane obrazy kontenerów przechowywane w rejestrze kontenerów, więc nadszedł czas, aby wdrożyć je na urządzeniu. Upewnij się, że urządzenie usługi IoT Edge jest uruchomione.

Użyj polecenia set-modules interfejsu wiersza polecenia platformy Azure usługi IoT Edge, aby wdrożyć moduły w usłudze Azure IoT Hub. Aby na przykład wdrożyć moduły zdefiniowane w pliku deployment.template.json w usłudze IoT Hub my-iot-hub dla urządzenia usługi IoT Edge my-device, użyj następującego polecenia. Zastąp wartości hub-name, device-id i login IoT Hub parametry połączenia własnymi.

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>"

Napiwek

Możesz znaleźć parametry połączenia usługi IoT Hub, w tym klucz dostępu współdzielonego w witrynie Azure Portal. Przejdź do ustawień>zabezpieczeń usługi IoT Hub >Zasady>dostępu współdzielonego iothubowner.

  1. W eksploratorze programu Visual Studio Code w sekcji Azure IoT Hub rozwiń węzeł Urządzenia , aby wyświetlić listę urządzeń IoT.

  2. Kliknij prawym przyciskiem myszy urządzenie usługi IoT Edge, do którego chcesz wdrożyć, a następnie wybierz pozycję Utwórz wdrożenie dla pojedynczego urządzenia.

  3. W Eksploratorze plików przejdź do folderu config , a następnie wybierz plik deployment.amd64.json .

    Nie używaj pliku deployment.template.json, który nie zawiera poświadczeń rejestru kontenerów ani wartości obrazu modułu. Jeśli docelowe jest urządzenie z systemem Linux ARM32, nazwa manifestu wdrożenia jest deployment.arm32v7.json.

  4. W obszarze urządzenia rozwiń węzeł Moduły , aby wyświetlić listę wdrożonych i uruchomionych modułów. Wybierz przycisk odświeżenia. Na urządzeniu powinny zostać wyświetlone nowe moduły tempSensor i filtermodule .

    Uruchomienie modułów może potrwać kilka minut. Środowisko uruchomieniowe usługi IoT Edge musi otrzymać nowy manifest wdrożenia, ściągnąć obrazy modułów ze środowiska uruchomieniowego kontenera, a następnie uruchomić każdy nowy moduł.

Wyświetlanie komunikatów z urządzenia

Przykładowy kod modułu odbiera komunikaty za pośrednictwem kolejki wejściowej i przekazuje je przez kolejkę wyjściową. Manifest wdrożenia zadeklarował trasy przekazujące komunikaty do modułu filtermodule z tempSensor, a następnie przekazywane komunikaty z modułu filtermodule do usługi IoT Hub. Rozszerzenia usługi Azure IoT Edge i Azure IoT Hub umożliwiają wyświetlanie komunikatów podczas ich docierania do usługi IoT Hub z poszczególnych urządzeń.

  1. W Eksploratorze programu Visual Studio Code kliknij prawym przyciskiem myszy urządzenie usługi IoT Edge, które chcesz monitorować, a następnie wybierz pozycję Rozpocznij monitorowanie wbudowanego punktu końcowego zdarzeń.

  2. Obejrzyj okno danych wyjściowych w programie Visual Studio Code, aby zobaczyć komunikaty przychodzące do centrum IoT.

    Screenshot showing where to view incoming device to cloud messages.

Wyświetlanie zmian na urządzeniu

Jeśli chcesz zobaczyć, co się dzieje na urządzeniu, użyj poleceń w tej sekcji, aby sprawdzić środowisko uruchomieniowe i moduły usługi IoT Edge uruchomione na urządzeniu.

Polecenia w tej sekcji dotyczą urządzenia usługi IoT Edge, a nie maszyny deweloperów. Jeśli używasz maszyny wirtualnej dla urządzenia usługi IoT Edge, połącz się z nim teraz. Na platformie Azure przejdź do strony przeglądu maszyny wirtualnej i wybierz pozycję Połączenie, aby uzyskać dostęp do bezpiecznego połączenia powłoki.

  • Wyświetl wszystkie moduły wdrożone na urządzeniu i sprawdź ich stan:

    iotedge list
    

    Powinny zostać wyświetlone cztery moduły: dwa moduły środowiska uruchomieniowego usługi IoT Edge, tempSensor i filtermodule. Wszystkie cztery powinny być wyświetlane jako uruchomione.

  • Sprawdź dzienniki dla określonego modułu:

    iotedge logs <module name>
    

    W modułach usługi IoT Edge uwzględniana jest wielkość liter.

    Dzienniki tempSensor i filtermodule powinny zawierać komunikaty, które przetwarzają. Moduł edgeAgent jest odpowiedzialny za uruchomienie innych modułów, dlatego jego dzienniki zawierają informacje o implementowaniu manifestu wdrożenia. Jeśli znajdziesz moduł nie ma na liście lub nie jest uruchomiony, dzienniki edgeAgent prawdopodobnie zawierają błędy. Moduł edgeHub odpowiada za komunikację między modułami a usługą IoT Hub. Jeśli moduły są uruchomione, ale komunikaty nie docierają do centrum IoT, dzienniki edgeHub prawdopodobnie zawierają błędy.

Czyszczenie zasobów

Jeśli zamierzasz przejść do kolejnego zalecanego artykułu, możesz zachować utworzone zasoby oraz konfiguracje i użyć ich ponownie. Możesz także nadal używać tego samego urządzenia usługi IoT Edge jako urządzenia testowego.

W przeciwnym razie możesz usunąć konfiguracje lokalne i zasoby platformy Azure użyte w tym artykule, aby uniknąć naliczania opłat.

Usuwanie zasobów platformy Azure

Usuwanie zasobów i grup zasobów platformy Azure jest nieodwracalne. Uważaj, aby nie usunąć przypadkowo niewłaściwych zasobów lub niewłaściwej grupy zasobów. Jeśli centrum IoT zostało utworzone w istniejącej grupie zasobów zawierającej zasoby, które chcesz zachować, usuń tylko sam zasób centrum IoT, a nie grupę zasobów.

Aby usunąć zasoby:

  1. Zaloguj się do witryny Azure Portal, a następnie wybierz pozycję Grupy zasobów.

  2. Wybierz nazwę grupy zasobów, która zawiera zasoby testowe usługi IoT Edge.

  3. Przejrzyj listę zasobów zawartych w grupie zasobów. Jeśli chcesz usunąć je wszystkie, możesz wybrać pozycję Usuń grupę zasobów. Jeśli chcesz usunąć tylko niektóre z nich, możesz kliknąć poszczególne zasoby, aby usunąć je pojedynczo.

Następne kroki

W tym samouczku skonfigurowano program Visual Studio Code na komputerze deweloperskim i wdrożono pierwszy moduł usługi IoT Edge zawierający kod do filtrowania nieprzetworzonych danych generowanych przez urządzenie usługi IoT Edge.

Możesz przejść do następnych samouczków, aby dowiedzieć się, jak usługa Azure IoT Edge może ułatwić wdrażanie usług w chmurze platformy Azure w celu przetwarzania i analizowania danych na urządzeniach brzegowych.