共用方式為

使用 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 對多種語言的 Azure 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 (EFLOW) 上使用適用於 Linux 的 IoT Edge，在 Linux 容器中使用 Windows 開發電腦和偵錯模組。 如需使用 EFLOW 開發模組的詳細資訊，請參閱教學課程：在 Windows 上使用適用於 Linux 的 IoT Edge，並使用 Linux 容器開發 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

請新增下列延伸模組：

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

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

使用 IoT Edge 模擬器，在無容器的情況下偵錯

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

下列偵錯步驟假設您已建立自訂模組。 如果您未建立自訂模組，請遵循使用 Visual Studio Code 開發 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>settings>registryCredentials。 將兩處的 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: Build and Push IoT Edge solution 命令。
  2. 選取解決方案的 deployment.debug.template.json 檔案。
  3. 在 Visual Studio Code 總管檢視的 [Azure IoT 中樞]>[裝置] 區段中，以滑鼠右鍵按一下要部署的 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 login 參考。

  2. 登入 Azure Container Registry。 您可能需要安裝 Azure CLI，才能使用 az 命令。 這個命令會要求您提供使用者名稱和密碼，您可以在 [設定]>[存取金鑰] 的容器登錄中找到這些資訊。

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

提示

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

對模組進行偵錯

若要對遠端裝置上的模組進行偵錯，您可以在 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 (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 Studio Code 中開啟檔案，新增設定至 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 偵錯檢視中，選取偵錯設定 Remote Debug IoT Edge Module (.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 開發人員部落格文章。

下一步

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

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