教學課程：在 Windows 上使用適用於 Linux 的 IoT Edge，透過 Linux 容器開發 IoT Edge 模組

適用於： IoT Edge 1.5 IoT Edge 1.4

本教學課程將逐步引導您使用 Windows 和 Visual Studio 2022 上的適用於 Linux 的 IoT Edge，開發、偵錯及部署您自己的程式代碼至 Azure IoT Edge 裝置。 透過將 C# 模組部署到 Linux 裝置，您將了解 IoT Edge 解決方案最常見的開發人員案例。 您將部署和偵錯在 Windows 上 Linux 容器中執行的自訂 IoT Edge 模組。 即使您打算使用不同的語言或部署 Azure 服務，本教學課程仍適用於了解開發工具和概念。

本教學課程包含兩個IoT Edge 開發工具的步驟：

• Azure IoT Edge 開發工具 CLI 命令行介面 （CLI），這是開發慣用的工具
• 適用於 Visual Studio 的 Azure IoT Edge Tools 擴充功能，其處於 維護模式

使用本教學課程開頭的選取器按鈕來選取工具版本。

在本教學課程中，您會了解如何：

必要條件

本教學課程假設您使用執行 Windows 的電腦作為開發計算機。 在 Windows 電腦上，您可以開發 Windows 或 Linux 模組。 本教學課程會引導您完成 Linux 容器的開發，方法是在 Windows 上使用適用於 Linux 的 IoT Edge 來建置和部署模組。

在開始之前：

• 在 Windows 上安裝適用於 Linux 的 IoT Edge。

• 閱讀快速入門 ：將第一個IoT Edge模組部署至 Windows 裝置。

• 下載 .NET Core SDK。

• 在您的開發機器上安裝或修改 Visual Studio 2022。 選擇具有C++工作負載選項的 Azure 開發和桌面開發。

• Visual Studio 2022 安裝就緒之後，請從 Visual Studio Marketplace 下載並安裝 Azure IoT Edge Tools 。

  您可以使用 Azure IoT Edge Tools 延伸模組來建立和建置 IoT Edge 解決方案。 慣用的開發工具是 Azure IoT Edge 開發工具 CLI。 此延伸模組包含您用來建立 Visual Studio 專案的 Azure IoT Edge 專案範本。 目前，不論您使用的開發工具為何，都需要安裝擴充功能。

  提示

  如果您使用 Visual Studio 2019，請從 Visual Studio Marketplace 下載並安裝 適用於 Visual Studio 2019 的 Azure IoT Edge Tools。

• 在 Azure 中建立免費或標準層 IoT 中樞 作為雲端資源。

如果您沒有 Azure 訂閱，請在開始之前，先建立 Azure 免費帳戶。

重要概念

本教學課程會逐步解說IoT Edge模組的開發。 IoT Edge 模組是具有可執行程式碼的容器。 您可以在 IoT Edge 裝置中部署一或多個模組。 模組會執行特定工作，例如從感應器擷取資料、清除及分析資料，或對 IoT 中樞傳送訊息。 如需詳細資訊，請參閱了解 Azure IoT Edge 模組。

當您開發IoT Edge模組時，請務必瞭解開發機器與最終部署模組的目標IoT Edge裝置之間的差異。 為了保存模組程式碼所建置的容器必須符合「目標裝置」的作業系統 (OS)。

例如，最常見的案例是在打算以執行IoT Edge的Linux裝置為目標的 Windows 電腦上開發模組的人員。 在此情況下，容器OS是Linux。

當您進行本教學課程時，請牢記「開發機器 OS」和「容器 OS」之間的差異。 在本教學課程中，您將使用 Windows 主機進行開發，並使用適用於 Linux 的 IoT Edge 在 Windows 虛擬機 （VM） 上建置和部署模組。

本教學課程是以使用 Linux 容器執行 IoT Edge 的裝置為目標。 您可以使用慣用的作業系統，只要您的開發機器執行 Linux 容器即可。 建議您使用 Visual Studio 與 Linux 容器進行開發，本教學課程也是這麼做的。 您也可以使用 Visual Studio Code，雖然這兩個工具之間有不同支援。 如需深入了解，請參閱使用 Visual Studio Code 開發 Azure IoT Edge 模組。

設定 Docker CLI 和 Docker 引擎以進行遠端連線

IoT Edge 模組會封裝為容器，因此開發機器上必須有容器引擎才能建置和管理容器。

Windows VM 上的適用於 Linux 的 IoT Edge 已經包含 Docker 引擎的實例。 本教學課程說明如何在 Windows VM Docker 實例上從 Windows 開發人員電腦遠端連線到適用於 Linux 的 IoT Edge。 使用此遠端連線，您可以移除適用於 Windows 的 Docker Desktop 相依性。

設定 Docker CLI

第一個步驟是在 Windows 開發電腦上設定 Docker CLI，以便能夠連線到遠端 Docker 引擎：

1. 從 Chocolatey 下載 Docker CLI 的先行編譯docker.exe版本。 您也可以從 GitHub 下載官方 CLI 專案，並遵循存放庫指示加以編譯。

2. 擷取 docker.exe 至開發機器中的目錄，例如 C:\Docker\bin。

3. 開啟 [關於您的計算機>系統資訊>進階系統設定]。

4. 選取 [進階>環境變數]。 在 [用戶變數] 底下，選取 [路徑]。

5. 編輯Path變數，並新增的位置docker.exe。

6. 開啟提升權限的 PowerShell 工作階段。

7. 使用此指令檢查 Docker CLI 是否可供存取：

   docker --version
   

   如果您已成功設定所有專案，命令的輸出應該會顯示 Docker 版本。 您應該會看到類似於 Docker version 20.10.12, build e91ed57 的內容。

設定 Docker 引擎

第二個步驟是在 Windows VM Docker 引擎上設定適用於 Linux 的 IoT Edge，以接受外部連線，並新增適當的防火牆規則。

1. 開啟提升許可權的 PowerShell 工作階段，然後執行下列命令：

   # Configure the IoT Edge for Linux on Windows VM Docker engine to accept external connections, and add the appropriate firewall rules.
   Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   
   # Create a copy of the IoT Edge for Linux on Windows VM _docker.service_ in the system folder.
   Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   
   # Replace the service execution line to listen for external connections.
   Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g'  /etc/systemd/system/docker.service"
   
   # Reload the IoT Edge for Linux on Windows VM services configurations.
   Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   
   # Reload the Docker engine service.
   Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   
   # Check that the Docker engine is listening to external connections.
   Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   

   以下是範例輸出：

   PS C:\> # Configure the IoT Edge for Linux on Windows virtual machine Docker engine to accept external connections, and add the appropriate firewall rules.
   PS C:\> Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   PS C:\>
   PS C:\> # Create a copy of the IoT Edge for Linux on Windows VM docker.service in the system folder.
   PS C:\> Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Replace the service execution line to listen for external connections.
   PS C:\> Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g' /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Reload the IoT Edge for Linux on Windows VM services configurations.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   PS C:\>
   PS C:\> # Reload the Docker engine service.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   PS C:\>
   PS C:\> # Check that the Docker engine is listening to external connections.
   PS C:\> Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   tcp6       0      0 :::2375                 :::*                    LISTEN      2790/dockerd
   

測試連線

最後一個設定步驟是測試 Windows VM Docker 引擎上適用於 Linux 的 IoT Edge Docker 連線：

1. 取得 Windows VM 上適用於 Linux 的 IoT Edge IP 位址：

   Get-EflowVmAddr
   

   提示

   如果 Windows VM 上的 IoT Edge for Linux 部署時沒有靜態 IP，則 IP 位址可能會在 Windows 主機 OS 重新啟動或網路變更時變更。 請務必在每次想要建立與 Docker 引擎的遠端連線時，在 Windows VM 上針對適用於 Linux 的 IoT Edge 使用正確的 IP 位址。

   以下是範例輸出：

   PS C:\> Get-EflowVmAddr
   [03/15/2022 15:22:30] Querying IP and MAC addresses from virtual machine (DESKTOP-J1842A1-EFLOW)
    - Virtual machine MAC: 00:15:5d:6f:da:78
    - Virtual machine IP : 172.31.24.105 retrieved directly from virtual machine
   00:15:5d:6f:da:78
   172.31.24.105 
   

2. 聯機到 Windows VM Docker 引擎上的適用於 Linux 的 IoT Edge，並執行 hello-world 範例容器。 將 取代 <EFLOW-VM-IP> 為您在上一個步驟中取得的 Windows VM IP 位址上適用於 Linux 的 IoT Edge。

   docker -H tcp://<EFLOW-VM-IP>:2375 run --rm hello-world
   

   下載容器完成時，容器會執行併產生此輸出：

   PS C:\> docker -H tcp://172.31.24.105:2375 run --rm hello-world
   Unable to find image 'hello-world:latest' locally
   latest: Pulling from library/hello-world
   2db29710123e: Pull complete
   Digest: sha256:4c5f3db4f8a54eb1e017c385f683a2de6e06f75be442dc32698c9bbe6c861edd
   Status: Downloaded newer image for hello-world:latest
   
   Hello from Docker!
   This message shows that your installation appears to be working correctly.
   
   To generate this message, Docker took the following steps:
    1. The Docker client contacted the Docker daemon.
    2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
       (amd64)
    3. The Docker daemon created a new container from that image which runs the
       executable that produces the output you're currently reading.
    4. The Docker daemon streamed that output to the Docker client, which sent it
       to your terminal.
   
   To try something more ambitious, you can run an Ubuntu container with:
    $ docker run -it ubuntu bash
   
   Share images, automate workflows, and more with a free Docker ID:
    https://hub.docker.com/
   
   For more examples and ideas, visit:
    https://docs.docker.com/get-started/
   

建立 Azure IoT Edge 專案

Visual Studio 中的 IoT Edge 專案範本會建立可部署到 IoT Edge 裝置的解決方案。 使用下列步驟來建立 Azure IoT Edge 解決方案，然後在該解決方案中產生第一個模組。 每個 IoT Edge 解決方案都可以包含多個模組。

1. 在 Visual Studio 中，選取 [開始] 頁面上的 [建立新專案]，或選取工具列上的 [新增專案] 按鈕，以建立新的專案。

2. 在 [建立新專案] 分頁，搜尋 Azure IoT Edge。 選取符合IoT Edge裝置平臺 （Linux IoT Edge 模組） 和架構的專案，然後選取[ 下一步]。

3. 在 [ 設定新專案 ] 頁面上，輸入專案的名稱並指定位置，然後選取 [ 建立]。

4. 在 [ 新增模組] 對話框中，選取您要開發的模塊類型。 您也可以選取 [現有的模組]，將現有的 IoT Edge 模組新增至您的部署。

5. 在 [模組名稱] 中，指定您的模組名稱。

6. 在 [存放庫 URL] 中，提供模組映像存放庫的名稱。 Visual Studio 會自動以 localhost：5000/<您的模組名稱填入模組名稱>。 請使用您自己的登錄資訊加以取代。

   如果您使用本機 Docker 登錄來進行測試，請使用 localhost。 如果您使用 Azure Container Registry，則請使用登錄設定中的登入伺服器。 登入伺服器看起來像 *<登錄名稱>*.azurecr.io。 只 取代字串的localhost：5000 部分，讓最終結果看起來像 <登錄名稱>。azurecr.io/< 您的模組名稱>。

7. 選取 [新增] 將模組新增至專案。

   

   注意

   如果您有現有的 IoT Edge 專案，您可以開啟 module.json 檔案來變更存放庫 URL。 存放庫 URL 位於 repository JSON 檔案的 屬性中。

現在，您的 Visual Studio 解決方案中有 IoT Edge 專案和 IoT Edge 模組。

專案結構

您的方案有兩個專案層級資料夾：主要專案資料夾和模組資料夾。 例如，您可能有名為 AzureIotEdgeApp1 的主要項目資料夾，以及名為的 IotEdgeModule1模組資料夾。

主要專案資料夾包含您的 部署指令清單。 部署資訊清單是一份 JSON 文件，其中描述要在目標 IoT Edge 裝置上設定的模組。

模組資料夾包含模組程式代碼的檔案。 根據您選擇的語言，它會命名 Program.cs 為 或 main.c。 此資料夾也包含名為 module.json 的檔案，其中描述模組的中繼資料。 各種 Docker 檔案提供建置模組作為 Windows 或 Linux 容器的必要資訊。

專案的部署資訊清單

您編輯的部署指令清單名稱為 deployment.debug.template.json。 此檔案是IoT Edge部署指令清單的範本，可定義在裝置上執行的所有模組。 檔案也會定義模組彼此通訊的方式。 如需部署資訊清單的詳細資訊，請參閱了解如何部署模組及建立路由。

部署範本包括：

• 兩個執行時間模組 edgeAgent 和 edgeHub。
• 您在此 Visual Studio 專案中建立的自定義模組。
• 名為的 SimulatedTemperatureSensor模組。 此預設模組會產生仿真的數據，您可以用來測試模組（如果不需要的話，請加以刪除）。 若要查看模擬溫度感應器的運作方式，請檢視 SimulatedTemperatureSensor.csproj 原始程式碼。

設定 IoT Edge 執行時間版本

目前，最新的穩定執行階段版本是 1.4 版。 將 IoT Edge 執行時間版本更新為最新的穩定版本，或您想要針對裝置設定目標的版本：

開發您的模組

當您新增模組時，它隨附可建置並部署至裝置的預設程式碼，讓您可以開始測試，而不需要觸及任何程序代碼。 模組程式碼位於模組資料夾內名為 Program.cs (適用於 C#) 或 main.c (適用於 C) 的檔案中。

在預設解決方案中，模組中的 SimulatedTemperatureSensor 模擬數據會路由傳送至您的模組。 模組會接受輸入，然後將它傳送至 Azure IoT 中樞。

當您準備好使用自己的程式代碼自定義模組範本時，請使用 Azure IoT 中樞 SDK 來建置其他模組，以解決 IoT 解決方案的關鍵需求。 這些需求可能包括安全性、裝置管理和可靠性。

建置並發送單一模組

一般而言，您為想要先針對每個模組進行測試和偵錯，然後在使用多個模組的整個解決方案中執行。 因為解決方案會使用在 Windows VM 上適用於 Linux 的 IoT Edge 內執行的 Docker 引擎來建置或偵錯，因此第一個步驟是建置和發佈模組，以啟用遠端偵錯：

1. 在 方案總管 中，選取模組項目資料夾 （例如 ， myIotEdgeModule）。

2. 將自訂模組設定為啟始專案。 在功能表上，選取 [項目>設定為啟始專案]。

3. 若要對 C# Linux 模組進行偵錯，您必須更新 Dockerfile.amd64.debug 檔案以啟用 SSH 服務。 Dockerfile.amd64.debug更新檔案以使用下列範本：具有遠端偵錯支援的 Azure IoT Edge AMD64 C# 模組 Dockerfile。

   注意

   當您選取 [ 偵錯] 時，Visual Studio 會使用 Dockerfile.(amd64|windows-amd64).debug 來建置 Docker 映射。 此檔案會在建置容器映像中包含 .NET Core 命令行調試程式 VSDBG。 對於生產就緒 IoT Edge 模組，建議您使用 [發行] 設定，此設定會使用無 VSDBG 的 Dockerfile.(amd64|windows-amd64)。

   請確定在範本的最後一行中， ENTRYPOINT ["dotnet", "IotEdgeModule1.dll"]DLL 的名稱符合IoT Edge模組專案的名稱。

4. 若要建立與 Linux 模組的 SSH 連線，您需要建立 RSA 金鑰。 開啟提升權限的 PowerShell 工作階段，並執行下列命令以建立新的 RSA 金鑰。 將 RSA 金鑰儲存在相同的 IoT Edge 模組資料夾下，並確定金鑰的名稱為 id_rsa。

   ssh-keygen -t RSA -b 4096 -m PEM
   

   

5. 如果您使用 Azure Container Registry 之類的私人登錄，請使用下列 Docker 命令來登入它。 您可在 Azure 入口網站中，從您登錄的 [存取金鑰] 頁面取得使用者名稱和密碼。 如果您使用的是本機登錄，可以執行本機登錄。

   docker -H tcp://<EFLOW-VM-IP>:2375 login -u <Container Registry username> -p <Container Registry password> <Container Registry login server>
   

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

# Build the image for the local registry

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

# Or build the image for an Azure container registry

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

# Push the Docker image to the local registry

docker push localhost:5000/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure container registry
az acr login --name myacr
docker push myacr.azurecr.io/iotedgemodule1:0.0.1-amd64

對解決方案進行偵錯

1. 在提升許可權的 PowerShell 工作階段中，執行下列命令：

   1. moduleId根據 Linux C# 模組的名稱取得值。 以 <iot-edge-module-name> 模組的名稱取代 佔位元。

      $moduleId = Invoke-EflowVmCommand "sudo docker ps -aqf name=<iot-edge-module-name>"
      

   2. 檢查是否正確 $moduleId 。 如果變數是空的，請確定您使用的是正確的模組名稱。

   3. 在 Linux 容器內啟動 SSH 服務：

      Invoke-EflowVmCommand "sudo docker exec -it -d $moduleId service ssh start"
      

   4. 在 Windows VM 上開啟適用於 Linux 的 IoT Edge 上的模組 SSH 埠。 （本教學課程使用埠 10022。）

      Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 10022 -j ACCEPT"
      

   警告

   基於安全性考慮，每當 Windows VM 上的適用於 Linux 的 IoT Edge 重新啟動時，就會刪除 IP 資料表規則，並返回原始設定。 此外，您必須手動啟動模組的 SSH 服務。

2. 成功啟動 SSH 服務之後，請選取 [>偵錯附加至進程]、將 [連線類型] 設定為 [SSH]，然後將 [連線目標] 設定為 Windows VM 上適用於 Linux 的 IoT Edge IP 位址。 如果您不知道 Windows VM 上適用於 Linux 的 IoT Edge IP 位址，您可以使用 Get-EflowVmAddr PowerShell Cmdlet。

   輸入IP，然後選取 Enter 鍵。 在彈出視窗中，輸入下列設定：

   欄位	值
   主機名稱	Windows VM 上適用於 Linux 的 IoT Edge IP 位址
   通訊埠	10022 （或您在部署組態中使用的
   使用者名稱	根
   驗證類型	私鑰
   私密金鑰檔案	您在上一個步驟中建立之值的完整路徑id_rsa
   複雜密碼	用於您在上一個步驟中建立之金鑰的複雜密碼

3. 使用 SSH 成功連線到模組之後，您可以選擇程式並選取 [ 附加]。 針對 C# 模組，您必須選擇 [處理 dotnet] 和 [附加至受控] （CoreCLR）。 第一次可能需要 10 到 20 秒的時間。

4. 設定斷點以檢查模組：

   • 如果您要在 C# 中開發，請在 中的 ModuleBackgroundService.cs函PipeMessage()式中設定斷點。
   • 如果您使用 C，請在 中的 InputQueue1Callback() main.c函式中設定斷點。

5. 的輸出 SimulatedTemperatureSensor 應該重新導向至 input1 自定義 Linux C# 模組。 中斷點應該已觸發。 您可以在 Visual Studio [區域變數] 視窗中觀察變數。

   

6. 若要停止偵錯，請選取 Ctrl+F5 或選取 [ 停止] 按鈕。

清除資源

如果您打算繼續閱讀下一篇建議的文章，則可以保留您所建立的資源和組態，並加以重複使用。 您可以也繼續使用相同的 IoT Edge 裝置作為測試裝置。

否則，請刪除本文中使用的本機設定和 Azure 資源，以避免產生費用。

刪除 Azure 資源

刪除 Azure 資源和資源群組是無法回復的動作。 請確定您不會誤刪錯誤的資源群組或資源。 如果您在現有的資源群組內建立了 IoT 中樞，而該群組包含您想要保留的資源，則您只需刪除 IoT 中樞資源本身，而不要刪除資源群組。

若要刪除資源：

1. 登入 Azure 入口網站，然後選取 [資源群組]。

2. 選取您的 IoT Edge 測試資源所屬的資源群組名稱。

3. 檢閱資源群組所包含的資源清單。 若要將其全部刪除，您可以選取 [刪除資源群組]。 如果只想刪除某些部分，則可以選取各個資源以將其個別刪除。

後續步驟

在本教學課程中，您會在開發計算機上設定Visual Studio，並從中部署並偵錯第一個IoT Edge模組。 既然您已瞭解基本概念，請嘗試將功能新增至模組，以便分析通過它的數據：