使用 Visual Studio Code 對 Azure IoT Edge 模組進行偵錯

  • 發行項

適用於：IoT Edge 1.5 複選標記 IoT Edge 1.5 IoT Edge 1.4 複選標記 IoT Edge 1.4

重要

支援 IoT Edge 1.5 LTS 和 IoT Edge 1.4 LTS 版本。 IoT Edge 1.4 LTS 於 2024 年 11 月 12 日結束生命週期。 如果您是舊版，請參閱更新 IoT Edge。

本文說明如何使用 Visual Studio Code 對多種語言的 IoT Edge 模組進行偵錯。 在您的開發電腦上，您可以使用 Visual Studio Code 在本機或遠端模組容器中連結和偵錯模組。

本文包含兩個IoT Edge開發工具的步驟。

  • Azure IoT Edge 開發工具 命令行工具 （CLI）。 此工具是開發慣用的工具。
  • 適用於 Visual Studio Code 擴充功能的 Azure IoT Edge 工具。 延伸模組處於 維護模式。

使用本文開頭的工具選取器按鈕來選取工具版本。

Visual Studio Code 支援以下列程式設計語言撰寫 IoT Edge 模組：

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

Azure IoT Edge 支援下列裝置架構：

  • AMD64
  • ARM32v7
  • ARM64

如需所支援作業系統、語言和架構的詳細資訊，請參閱 語言和架構支援。

使用 Visual Studio Code IoT Edge 擴充功能時，您也可以在 IoT Edge 模擬器中啟動和偵錯模組程式代碼。

您也可以在 Windows 上使用適用於 Linux 的 IoT Edge，在 Linux 容器中使用 Windows 開發電腦和偵錯模組（EFLOW）。 如需使用EFLOW開發模組的詳細資訊，請參閱 教學課程：使用適用於Linux的IoT Edge在 Windows 上使用適用於Linux的IoT Edge容器開發IoT Edge模組。

如果您不熟悉 Visual Studio Code 的偵錯功能，請參閱 Visual Studio Code 偵錯。

必要條件

您可以使用執行 Windows、macOS 或 Linux 的電腦或虛擬機器作為開發電腦。 在 Windows 電腦上，您可以開發 Windows 或 Linux 模組。 若要開發 Linux 模組，請使用符合 Docker Desktop 需求的 Windows 電腦。

若要安裝開發和偵錯所需的工具，請完成 使用Visual Studio Code 開發 Azure IoT Edge 模組教學課程。

安裝 Visual Studio Code

新增下列延伸模組：

  • Azure IoT Edge 擴充功能。 適用於 Visual Studio Code 的 Azure IoT Edge 工具擴充功能處於維護模式。
  • Azure IoT 中樞擴充功能。

若要在裝置上對模組進行偵錯，您需要：

  • 具有至少一個IoT Edge裝置的作用中 IoT 中樞。
  • 實體IoT Edge裝置或虛擬設備。 若要在 Azure 中建立虛擬設備，請遵循 Linux 快速入門中的步驟。
  • 自訂IoT Edge模組。 若要建立自定義模組，請遵循使用Visual StudioCode開發 Azure IoT Edge 模組教學課程中的步驟。

使用IoT Edge模擬器在沒有容器的情況下進行偵錯

IoT Edge 模擬器是在開發電腦上執行的工具，並模擬單一 IoT Edge 裝置的行為。 您可以使用IoT Edge 模擬器來開發及測試IoT Edge模組，而不需要實體裝置或完整的IoT Edge裝置運行時間。

下列偵錯步驟假設您已建立自定義模組。 如果您尚未建立自定義模組，請遵循使用Visual StudioCode開發 Azure IoT Edge 模組教學課程中的步驟。

使用 C 或 Python 時，無法使用沒有容器的模組進行偵錯。

使用IoT Edge模擬器在附加模式中偵錯

C 或 Python 不支援以附加模式進行偵錯。

使用 IoT Edge 執行階段對模組進行偵錯

在每個模組資料夾中，有數個適用於不同容器類型的 Docker 檔案。 請使用任何副檔名為 .debug 的檔案來建置測試用模組。

當您使用此方法對模組進行偵錯時，您的模組會在IoT Edge執行時間之上執行。 IoT Edge 裝置和 Visual Studio Code 可以位於同一部電腦上，或者往往是 Visual Studio Code 位於開發電腦上，而 IoT Edge 執行階段和模組則是在另一部實體電腦上執行。 若要從 Visual Studio Code 進行偵錯，您必須：

  • 設定 IoT Edge 裝置、使用 .debug Dockerfile 建置 IoT Edge 模組，然後部署至 IoT Edge 裝置。
  • 更新 launch.json ，讓Visual Studio Code 可以附加至遠端電腦上容器中的進程。 您可以在工作區的資料夾中找到此檔案 .vscode ，並在每次新增支援偵錯的新模組時更新。
  • 使用遠端 SSH 偵錯連結至遠端電腦上的容器。

建置模組並將其部署至IoT Edge裝置

在 Visual Studio Code 中 ，開啟deployment.debug.template.json 部署指令清單檔案。 部署指令清單描述要設定在目標 IoT Edge 裝置上的模組。 部署之前，您必須使用適當的 createOptions 值來更新 Azure Container Registry 認證和模組映射。 如需 createOption 值的詳細資訊，請參閱 如何設定 IoT Edge 模組的容器建立選項。

  1. 如果您使用 Azure Container Registry 來儲存模組映像，請將認證新增至 deployment.debug.template.json 中的 edgeAgent>設定>登錄Credentials 區段。 將 myacr 取代為您在兩個位置的登錄名稱，並提供您的密碼和登入伺服器位址。 例如：

    "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. 將下列字串化內容新增或取代至 每個系統 （edgeHub 和 edgeAgent） 和自定義模組 （例如 filtermodule） 的 createOptions 值。 視需要變更值。

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

    例如，filtermodule 組態應該類似：

    "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. 在 Visual Studio Code 命令選擇區中，執行 Azure IoT Edge：建置和推送 IoT Edge 解決方案命令。
  2. 選取解決方案的 deployment.debug.template.json 檔案。
  3. 在 Visual Studio Code Explorer 檢視的 [Azure IoT 中樞> Devices] 區段中，以滑鼠右鍵按兩下要部署的 IoT Edge 裝置名稱，然後選擇 [建立單一裝置的部署]。

    提示

    若要確認您選擇的裝置是IoT Edge裝置，請選取它以展開模組清單，並確認$edgeHub和$edgeAgent是否存在。 每個 IoT Edge 裝置都包含這兩個模組。

  4. 瀏覽至您解決方案的 config 資料夾，選取 deployment.debug.amd64.json 檔案，然後選取 [選取 Edge 部署資訊清單]。

您可以在終端機中執行 docker ps 命令，從您的裝置或虛擬機檢查容器狀態。 您應該會在執行 命令之後看到您的容器列出。 如果您的 Visual Studio Code 和 IoT Edge 執行階段在同一部電腦上執行，您也可以檢查 Visual Studio Code Docker 檢視中的狀態。

重要

如果您針對映像使用 Azure Container Registry 之類的私人登錄，您可能需要進行驗證才能推送映像。 使用 docker login <Azure Container Registry login server> 或 az acr login --name <Azure Container Registry name> 進行驗證。

登入 Docker

將您的容器登錄認證提供給 Docker，以便將容器映像推送至登錄中的記憶體。

  1. 使用您在建立登錄後儲存的 Azure Container Registry 認證登入 Docker。

    docker login -u <Azure Container Registry username> -p <Azure Container Registry password> <Azure Container Registry login server>

    您可能會收到建議使用 --password-stdin的安全性警告。 雖然這是生產案例的建議最佳做法，但本教學課程的範圍並不相同。 如需詳細資訊，請參閱 docker 登入 參考。

  2. 登入 Azure Container Registry。 您可能需要 安裝 Azure CLI 才能使用 az 命令。 此命令會要求您在容器登錄中找到的使用者名稱和密碼，>設定 Access 金鑰。

    az acr login -n <Azure Container Registry name>

提示

如果您在本教學課程中的任何時間點註銷，請重複 Docker 和 Azure Container Registry 登入步驟以繼續。

建置模組 Docker 映像

使用模組的 Dockerfile 來 建置 模組 Docker 映射。

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

例如，若要建置本機登錄或 Azure Container Registry 的映射，請使用下列命令：

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

推送模組 Docker 映像

將您的模組映像推送 至本機登錄或容器登錄。

docker push <ImageName>

例如：

# 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

將模組部署至IoT Edge裝置

使用 IoT Edge Azure CLI set-modules 命令，將模組部署至 Azure IoT 中樞。 例如，若要將 deployment.debug.template.json 檔案中定義的模組部署到ioT Edge裝置 my-device IoT 中樞 my-iot-hub，請使用下列命令：

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

提示

您可以在 IoT 中樞 安全性設定>[共用存取原則 iothubowner] 的 [Azure 入口網站 中找到您的 IoT 中樞> 共用存取>密鑰。

對模組進行偵錯

若要對遠端裝置上的模組進行偵錯，您可以在 Visual Studio Code 中使用遠端 SSH 偵錯。

若要啟用 Visual Studio Code 遠端偵錯，請安裝 遠端開發延伸模組。 如需 Visual Studio Code 遠端偵錯的詳細資訊，請參閱 Visual Studio Code 遠端開發。

如需如何在 Visual Studio Code 中使用遠端 SSH 偵錯的詳細資訊，請參閱 使用 SSH 進行遠端開發

在 Visual Studio Code 偵錯檢視中，選取模組的偵錯組態檔。 根據預設， .debug Dockerfile、模組的容器 createOptions 設定，以及 launch.json 檔案會使用 localhost。

選取 [ 開始偵錯] 或選取 F5。 選取要附加的目標處理程序。 在 Visual Studio Code 偵錯檢視中，您會在左面板中看到變數。

使用 Docker 遠端 SSH 進行偵錯

Docker 和 Moby 引擎支援對容器的 SSH 連線，讓您在連線到遠端裝置的 Visual Studio Code 中偵錯。 您必須先符合下列必要條件，才能使用此功能。

視您使用的語言而定，遠端 SSH 偵錯必要條件可能會有所不同。 下列各節說明 .NET 的設定。 如需其他語言的相關信息，請參閱 使用 SSH 進行遠端開發以取得概觀。 有關如何設定遠端偵錯的詳細數據包含在Visual Studio Code 檔中每個語言的偵錯區段。

設定 Docker SSH 通道

  1. 請遵循 Docker SSH 通道中的步驟，在開發電腦上設定 SSH 通道。 SSH 通道需要公用/私鑰組驗證，以及定義遠端裝置端點的 Docker 內容。

  2. 連線 Docker 需要根層級許可權。 請遵循以非根使用者身分管理 Docker 中的步驟，以允許連線到遠端裝置上的 Docker 精靈。 當您完成偵錯時，您可能會想要從 Docker 群組中移除您的使用者。

  3. 在 Visual Studio Code 中，使用命令選擇區 （Ctrl+Shift+P） 發出 Docker 內容：使用 命令來啟動指向遠端電腦的 Docker 內容。 此命令會讓 Visual Studio Code 和 Docker CLI 使用遠端電腦內容。

    提示

    所有 Docker 命令都會使用目前的內容。 當您完成偵錯時，請記得將內容變更回 預設值 。

  4. 若要確認遠端 Docker 內容為作用中，請列出遠端裝置上執行中的容器：

    docker ps

    輸出應該會列出在遠端裝置上執行的容器，如下所示：

    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. 在 .vscode 目錄中，藉由在Visual StudioCode中開啟檔案，將新的組態新增至 launch.json 。 選取 [ 新增組態 ]，然後選擇模組的相符遠端附加範本。 例如，下列組態適用於 .NET Core。 將 PipeArgs 中 -H 參數的值變更為裝置 DNS 名稱或 IP 位址。

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

遠端偵錯模組

  1. 在 Visual Studio Code 偵錯檢視中，選取偵錯組態 遠端偵錯 IoT Edge 模組 （.NET Core） 。

  2. 選取 [ 開始偵錯] 或選取 F5。 選取要附加的目標處理程序。

  3. 在 Visual Studio Code 偵錯檢視中，您會在左面板中看到變數。

  4. 在 Visual Studio Code 中，設定自定義模組中的斷點。

  5. 叫用斷點時，您可以檢查變數、逐步執行程式代碼，以及對模組進行偵錯。

    連結至遠端裝置上 Docker 容器的 Visual Studio Code 螢幕快照，這些容器在斷點暫停。

注意

上述範例示範如何在遠端容器上偵錯 IoT Edge 模組。 此範例會將遠端 Docker 內容和變更新增至遠端裝置上的 Docker 許可權。 完成模組偵錯之後，請將 Docker 內容設定為 預設值 ，並從您的使用者帳戶移除許可權。

如需使用Raspberry Pi裝置的範例，請參閱此 IoT開發人員部落格文章 。

下一步

建置模組之後，請 瞭解如何從 Visual Studio Code 部署 Azure IoT Edge 模組。

若要開發IoT Edge裝置的模組，請瞭解和使用 Azure IoT 中樞 SDK。