Debugowanie modułów usługi Azure IoT Edge przy użyciu programu Visual Studio Code

  • Artykuł

Dotyczy:Znacznik wyboru usługi IoT Edge 1.5 IoT Edge 1.5 Znacznik wyboru usługi IoT Edge 1.4 IoT Edge 1.4

Ważne

Obsługiwane są wersje usługi IoT Edge 1.5 LTS i IoT Edge 1.4 LTS. Usługa IoT Edge 1.4 LTS kończy się 12 listopada 2024 r. Jeśli korzystasz z wcześniejszej wersji, zobacz aktualizację Azure IoT Edge.

W tym artykule pokazano, jak używać programu Visual Studio Code do debugowania modułów usługi IoT Edge w wielu językach. Na komputerze deweloperów możesz użyć programu Visual Studio Code do dołączania i debugowania modułu w lokalnym lub zdalnym kontenerze modułu.

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

  • Narzędzie wiersza 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.

Program Visual Studio Code obsługuje pisanie modułów usługi IoT Edge w następujących językach programowania:

  • C# i C# Azure Functions
  • C
  • Python
  • Node.js
  • Java

Usługa Azure IoT Edge obsługuje następujące architektury urządzeń:

  • AMD64
  • ARM32v7
  • ARM64

Aby uzyskać więcej informacji na temat obsługiwanych systemów operacyjnych, języków i architektur, zobacz Obsługa języka i architektury.

Korzystając z rozszerzenia usługi IoT Edge programu Visual Studio Code, możesz również uruchomić i debugować kod modułu w symulatorze usługi IoT Edge.

Można również użyć komputera deweloperskiego z systemem Windows i modułów debugowania w kontenerze systemu Linux przy użyciu usługi IoT Edge dla systemu Linux w systemie Windows (EFLOW). Aby uzyskać więcej informacji na temat używania platformy EFLOW do tworzenia modułów, zobacz Samouczek: tworzenie modułów usługi IoT Edge z kontenerami systemu Linux przy użyciu usługi IoT Edge dla systemu Linux w systemie Windows.

Jeśli nie znasz możliwości debugowania programu Visual Studio Code, zobacz Debugowanie programu Visual Studio Code.

Wymagania wstępne

Jako maszynę dewelopera można użyć komputera lub maszyny wirtualnej z systemem Windows, macOS lub Linux. Na komputerach z systemem Windows można opracowywać moduły systemu Windows lub Linux. Aby opracować moduły systemu Linux, użyj komputera z systemem Windows spełniającego wymagania dotyczące programu Docker Desktop.

Aby zainstalować wymagane narzędzia do programowania i debugowania, ukończ samouczek Tworzenie modułów usługi Azure IoT Edge przy użyciu programu Visual Studio Code .

Instalacja programu Visual Studio Code

Dodaj następujące rozszerzenia:

Do debugowania modułu na urządzeniu potrzebne są następujące elementy:

  • Aktywna usługa IoT Hub z co najmniej jednym urządzeniem usługi IoT Edge.
  • Fizyczne urządzenie usługi IoT Edge lub urządzenie wirtualne. Aby utworzyć urządzenie wirtualne na platformie Azure, wykonaj kroki opisane w przewodniku Szybki start dla systemu Linux.
  • Niestandardowy moduł usługi IoT Edge. Aby utworzyć moduł niestandardowy, wykonaj kroki opisane w samouczku Tworzenie modułów usługi Azure IoT Edge przy użyciu programu Visual Studio Code .

Debugowanie bez kontenera przy użyciu symulatora usługi IoT Edge

Symulator usługi IoT Edge to narzędzie, które działa na komputerze dewelopera i symuluje zachowanie jednego urządzenia usługi IoT Edge. Za pomocą symulatora usługi IoT Edge można opracowywać i testować moduły usługi IoT Edge bez fizycznego urządzenia lub pełnego środowiska uruchomieniowego urządzenia usługi IoT Edge.

W poniższych krokach debugowania założono, że utworzono już moduł niestandardowy. Jeśli nie utworzono modułu niestandardowego, wykonaj kroki opisane w samouczku Tworzenie modułów usługi Azure IoT Edge przy użyciu programu Visual Studio Code .

Debugowanie modułu bez kontenera nie jest dostępne w przypadku korzystania z języka C lub Python.

Debugowanie w trybie dołączania przy użyciu symulatora usługi IoT Edge

Debugowanie w trybie dołączania nie jest obsługiwane w języku C ani Python.

Debugowanie modułu za pomocą środowiska uruchomieniowego usługi IoT Edge

W każdym folderze modułu istnieje kilka plików platformy Docker dla różnych typów kontenerów. Użyj dowolnego pliku kończącego się rozszerzeniem .debug , aby skompilować moduł na potrzeby testowania.

Podczas debugowania modułów przy użyciu tej metody moduły są uruchamiane na podstawie środowiska uruchomieniowego usługi IoT Edge. Urządzenie usługi IoT Edge i program Visual Studio Code mogą znajdować się na tej samej maszynie lub zazwyczaj na maszynie deweloperów, a środowisko uruchomieniowe i moduły usługi IoT Edge działają na innej maszynie fizycznej. Aby debugować z poziomu programu Visual Studio Code, musisz:

  • Skonfiguruj urządzenie usługi IoT Edge, skompiluj moduły usługi IoT Edge przy użyciu pliku .debug dockerfile, a następnie wdróż je na urządzeniu usługi IoT Edge.
  • Zaktualizuj program launch.json Visual Studio Code do procesu w kontenerze na maszynie zdalnej. Ten plik można znaleźć w .vscode folderze w obszarze roboczym i jest aktualizowany za każdym razem, gdy dodasz nowy moduł obsługujący debugowanie.
  • Użyj zdalnego debugowania SSH, aby dołączyć do kontenera na maszynie zdalnej.

Kompilowanie i wdrażanie modułu na urządzeniu usługi IoT Edge

W programie Visual Studio Code otwórz plik manifestu wdrożenia deployment.debug.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).

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

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

  2. Dodaj lub zastąp następującą zawartość ciągową wartością createOptions dla każdego systemu (edgeHub i edgeAgent) oraz modułu niestandardowego (na przykład filtermodule). 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\"}]}}}"
}
  1. W palecie poleceń programu Visual Studio Code uruchom polecenie Azure IoT Edge: kompilowanie i wypychanie rozwiązania usługi IoT Edge.
  2. deployment.debug.template.json Wybierz plik rozwiązania.
  3. W sekcji Urządzenia usługi Azure IoT Hub>w widoku Eksploratora programu Visual Studio Code kliknij prawym przyciskiem myszy nazwę urządzenia usługi IoT Edge dla wdrożenia, a następnie wybierz polecenie Utwórz wdrożenie dla pojedynczego urządzenia.

    Napiwek

    Aby potwierdzić, że wybrane urządzenie jest urządzeniem usługi IoT Edge, wybierz je, aby rozwinąć listę modułów i zweryfikować obecność $edgeHub i $edgeAgent. Każde urządzenie usługi IoT Edge zawiera te dwa moduły.

  4. Przejdź do folderu konfiguracji rozwiązania, wybierz deployment.debug.amd64.json plik, a następnie wybierz pozycję Wybierz manifest wdrożenia usługi Edge.

Stan kontenera można sprawdzić z urządzenia lub maszyny wirtualnej, uruchamiając docker ps polecenie w terminalu. Po uruchomieniu polecenia powinien zostać wyświetlony kontener. Jeśli środowisko uruchomieniowe programu Visual Studio Code i usługi IoT Edge jest uruchomione na tej samej maszynie, możesz również sprawdzić stan w widoku platformy Docker programu Visual Studio Code.

Ważne

Jeśli używasz rejestru prywatnego, takiego jak Usługa Azure Container Registry dla obrazów, może być konieczne uwierzytelnienie w celu wypychania obrazów. Użyj polecenia docker login <Azure Container Registry login server> lub az acr login --name <Azure Container Registry name> , aby się uwierzytelnić.

Logowanie do platformy Docker

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 zapisanych po utworzeniu rejestru.

    docker login -u <Azure Container Registry username> -p <Azure Container Registry password> <Azure Container Registry 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 , może być konieczne zainstalowanie interfejsu 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 <Azure Container 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ć.

Kompilowanie obrazu platformy Docker modułu

Użyj pliku Dockerfile modułu, aby skompilować obraz platformy Docker modułu.

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

Aby na przykład skompilować obraz dla rejestru lokalnego lub usługi Azure Container Registry, użyj następujących poleceń:

# Build the image for the local registry

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

# Or build the image for an Azure Container Registry

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

Obraz platformy Docker modułu wypychania

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
az acr login --name myacr
docker push myacr.azurecr.io/filtermodule:0.0.1-amd64

Wdrażanie modułu na urządzeniu usługi IoT Edge

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.debug.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:

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

Napiwek

Klucz dostępu współdzielonego usługi IoT Hub można znaleźć w witrynie Azure Portal w ustawieniach>zabezpieczeń usługi IoT Hub >Zasady dostępu>współdzielonego iothubowner.

Debugowanie modułu

Aby debugować moduły na urządzeniu zdalnym, możesz użyć zdalnego debugowania SSH w programie Visual Studio Code.

Aby włączyć zdalne debugowanie programu Visual Studio Code, zainstaluj rozszerzenie Programowanie zdalne. Aby uzyskać więcej informacji na temat zdalnego debugowania programu Visual Studio Code, zobacz Programowanie zdalne programu Visual Studio Code.

Aby uzyskać szczegółowe informacje na temat korzystania z zdalnego debugowania SSH w programie Visual Studio Code, zobacz Programowanie zdalne przy użyciu protokołu SSH

W widoku Debugowanie programu Visual Studio Code wybierz plik konfiguracji debugowania dla modułu. Domyślnie plik .debuguj plik Dockerfile, ustawienia kontenera createOptions modułu i plik używa hosta lokalnegolaunch.json.

Wybierz pozycję Rozpocznij debugowanie lub wybierz pozycję F5. Wybierz proces, do których chcesz dołączyć. W widoku Debugowanie programu Visual Studio Code są widoczne zmienne w panelu po lewej stronie.

Debugowanie przy użyciu zdalnego protokołu SSH platformy Docker

Aparaty Platformy Docker i Moby obsługują połączenia SSH z kontenerami, co umożliwia debugowanie w programie Visual Studio Code połączonym z urządzeniem zdalnym. Przed użyciem tej funkcji należy spełnić następujące wymagania wstępne.

Wymagania wstępne debugowania zdalnego protokołu SSH mogą być różne w zależności od używanego języka. W poniższych sekcjach opisano konfigurację platformy .NET. Aby uzyskać informacje na temat innych języków, zobacz Remote Development using SSH (Programowanie zdalne przy użyciu protokołu SSH ), aby zapoznać się z omówieniem. Szczegółowe informacje na temat konfigurowania zdalnego debugowania znajdują się w sekcjach debugowania dla każdego języka w dokumentacji programu Visual Studio Code.

Konfigurowanie tunelowania SSH platformy Docker

  1. Wykonaj kroki opisane w temacie Tunelowanie SSH platformy Docker, aby skonfigurować tunelowanie SSH na komputerze dewelopera. Tunelowanie SSH wymaga uwierzytelniania pary kluczy publicznych/prywatnych i kontekstu platformy Docker definiującego punkt końcowy urządzenia zdalnego.

  2. Połączenie do platformy Docker wymaga uprawnień na poziomie głównym. Wykonaj kroki opisane w temacie Zarządzanie platformą Docker jako użytkownik niebędący użytkownikiem głównym, aby zezwolić na połączenie z demonem platformy Docker na urządzeniu zdalnym. Po zakończeniu debugowania możesz usunąć użytkownika z grupy platformy Docker.

  3. W programie Visual Studio Code użyj palety poleceń (Ctrl+Shift+P), aby wydać kontekst platformy Docker: użyj polecenia, aby aktywować kontekst platformy Docker wskazujący komputer zdalny. To polecenie powoduje, że zarówno program Visual Studio Code, jak i interfejs wiersza polecenia platformy Docker używają kontekstu maszyny zdalnej.

    Napiwek

    Wszystkie polecenia platformy Docker używają bieżącego kontekstu. Pamiętaj, aby zmienić kontekst z powrotem na domyślny po zakończeniu debugowania.

  4. Aby sprawdzić, czy zdalny kontekst platformy Docker jest aktywny, wyświetl listę uruchomionych kontenerów na urządzeniu zdalnym:

    docker ps

    Dane wyjściowe powinny zawierać listę kontenerów uruchomionych na urządzeniu zdalnym w podobny sposób:

    PS C:\> docker ps        
CONTAINER ID   IMAGE                                                             COMMAND                   CREATED        STATUS         PORTS                                                                                                                                   NAMES
a317b8058786   myacr.azurecr.io/filtermodule:0.0.1-amd64                         "dotnet filtermodule…"    24 hours ago   Up 6 minutes                                                                                                                                           filtermodule
d4d949f8dfb9   mcr.microsoft.com/azureiotedge-hub:1.5                            "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes   0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:5671->5671/tcp, :::5671->5671/tcp, 0.0.0.0:8883->8883/tcp, :::8883->8883/tcp, 1883/tcp   edgeHub
1f0da9cfe8e8   mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0   "/bin/sh -c 'echo \"$…"   24 hours ago   Up 6 minutes                                                                                                    
                                       tempSensor
66078969d843   mcr.microsoft.com/azureiotedge-agent:1.5                          "/bin/sh -c 'exec /a…"    24 hours ago   Up 6 minutes                                                                                                    
                                       edgeAgent

  5. W katalogu .vscode dodaj nową konfigurację, aby launch.json, otwierając plik w programie Visual Studio Code. Wybierz pozycję Dodaj konfigurację , a następnie wybierz pasujący szablon dołączania zdalnego dla modułu. Na przykład następująca konfiguracja dotyczy platformy .NET Core. Zmień wartość parametru -H w potoku PipeArgs na nazwę DNS lub adres IP urządzenia.

    "configurations": [
{
  "name": "Remote Debug IoT Edge Module (.NET Core)",
  "type": "coreclr",
  "request": "attach",
  "processId": "${command:pickRemoteProcess}",
  "pipeTransport": {
    "pipeProgram": "docker",
    "pipeArgs": [
      "-H",
      "ssh://user@my-device-vm.eastus.cloudapp.azure.com:22",
      "exec",
      "-i",
      "filtermodule",
      "sh",
      "-c"
    ],
    "debuggerPath": "~/vsdbg/vsdbg",
    "pipeCwd": "${workspaceFolder}",
    "quoteArgs": true
  },
  "sourceFileMap": {
    "/app": "${workspaceFolder}/modules/filtermodule"
  },
  "justMyCode": true
},

Zdalne debugowanie modułu

  1. W widoku Debugowanie programu Visual Studio Code wybierz konfigurację debugowania zdalnego debugowania Moduł usługi IoT Edge (.NET Core).

  2. Wybierz pozycję Rozpocznij debugowanie lub wybierz pozycję F5. Wybierz proces, do których chcesz dołączyć.

  3. W widoku Debugowanie programu Visual Studio Code zobaczysz zmienne w panelu po lewej stronie.

  4. W programie Visual Studio Code ustaw punkty przerwania w module niestandardowym.

  5. Po osiągnięciu punktu przerwania można sprawdzić zmienne, przejść przez kod i debugować moduł.

    Zrzut ekranu programu Visual Studio Code dołączony do kontenera platformy Docker na urządzeniu zdalnym wstrzymany w punkcie przerwania.

Uwaga

W poprzednim przykładzie pokazano, jak debugować moduły usługi IoT Edge w kontenerach zdalnych. W przykładzie dodano zdalny kontekst platformy Docker i zmiany uprawnień platformy Docker na urządzeniu zdalnym. Po zakończeniu debugowania modułów ustaw kontekst platformy Docker na domyślne i usuń uprawnienia z konta użytkownika.

Zobacz ten wpis w blogu dla deweloperów IoT, aby zapoznać się z przykładem użycia urządzenia Raspberry Pi.

Następne kroki

Po utworzeniu modułu dowiedz się, jak wdrożyć moduły usługi Azure IoT Edge z poziomu programu Visual Studio Code.

Aby opracowywać moduły dla urządzeń usługi IoT Edge, zapoznaj się z zestawami SDK usługi Azure IoT Hub i korzystaj z nich.