教學課程：建置高階應用程式

重要

這是 Azure Sphere （舊版） 檔。 Azure Sphere（舊版）將於 2027 年 9 月 27 日淘汰，且使用者此時必須移轉至 Azure Sphere（整合式）。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere （整合式） 檔。

高階應用程式會在 Azure Sphere OS 上執行、使用 Azure Sphere 應用程式連結庫，並可與因特網和雲端式服務通訊。 如需高階應用程式的基本資訊，請參閱 Azure Sphere 應用程式 概觀。

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

• 準備您的裝置以進行開發和偵錯
• 建置、執行及偵錯高階應用程式

必要條件

• 安裝適用於 Windows 或 Linux 的 CMake 和 Ninja。

• 安裝適用於 Windows 或 Linux 的 Visual Studio Code。
• 安裝適用於 Windows 或 Linux 的 CMake 和 Ninja。

• 安裝適用於 Visual Studio 的 Azure Sphere 擴充功能。

• 安裝適用於 Windows 或 Linux 的 SDK
• 選擇租使用者並宣告您的裝置
• 設定網路功能並更新裝置 OS

準備您的裝置以進行開發和偵錯

您必須先啟用開發和側載，才能在 Azure Sphere 裝置上建置範例應用程式，或為其開發新的應用程式。 根據預設，Azure Sphere 裝置會「鎖定」;也就是說，它們不允許從計算機載入開發中的應用程式，而且不允許對應用程式進行偵錯。 準備要側載的裝置會移除這項限制。

azsphere device enable-development 命令會將裝置設定為接受應用程式以進行偵錯、將偵錯伺服器載入裝置，並將裝置指派給不允許雲端應用程式更新的裝置群組。 在應用程式開發和偵錯期間，您應該讓裝置留在此群組中，讓雲端應用程式更新不會覆寫開發中的應用程式。

1. 請確定您的 Azure Sphere 裝置已連線到您的電腦，且您的電腦已連線到因特網。

2. 使用 PowerShell、Windows 命令提示字元或 Linux 命令殼層開啟命令行介面。

3. 輸入下列命令：

   azsphere device enable-development
   

   您應該會看到如下輸出：

   Getting device capability configuration for application development.
   Downloading device capability configuration for device ID '<device ID>'.
   Successfully downloaded device capability configuration.
   Successfully wrote device capability configuration file 'C:\Users\user\AppData\Local\Temp\tmpD732.tmp'.
   Setting device group ID 'a6df7013-c7c2-4764-8424-00cbacb431e5' for device with ID '<device ID>'.
   Successfully disabled over-the-air updates.
   Enabling application development capability on attached device.
   Applying device capability configuration to device.
   Successfully applied device capability configuration to device.
   The device is rebooting.
   Installing debugging server to device.
   Deploying 'C:\Program Files (x86)\Microsoft Azure Sphere SDK\DebugTools\gdbserver.imagepackage' to the attached device.
   Image package 'C:\Program Files (x86)\Microsoft Azure Sphere SDK\DebugTools\gdbserver.imagepackage' has been deployed to the attached device.
   Application development capability enabled.
   Successfully set up device '<device ID>' for application development, and disabled over-the-air updates.
   Command completed successfully in 00:00:38.3299276.
   

如果 azsphere device enable-development 命令失敗，請參閱針對 Azure Sphere 問題進行疑難解答以取得協助。

使用 Visual Studio Code 建置並執行高階應用程式

本教學課程使用 Azure Sphere Blink 範本，這是適用於 Visual Studio Code 的 Azure Sphere 延伸模組的一部分。 Blink 範本會閃爍 LED，讓您可以確認 Azure Sphere 裝置和工具已安裝並正確設定。

1. 啟動 Visual Studio Code。 選取 [檢視>命令選擇區]，然後輸入 Azure Sphere：產生新專案。

   

2. 從 [範本] 選單選擇 [閃爍]。

   

3. Visual Studio Code 接著會顯示 檔案總管 視窗。 瀏覽至您要放置 Blink 應用程式的資料夾。 Visual Studio Code 會在您選取的位置建立 Blink 資料夾，併產生 Blink 應用程式的組建檔案。 您應該會看到來自 CMake 的訊息。

4. 開啟CMakeLists.txt檔案，並變更TARGET_DIRECTORY設定，以指定包含您所使用硬體定義的資料夾。 根據預設，TARGET_DIRECTORY會指定 HardwareDefinitions/mt3620_rbd，其符合 Seeed Azure Sphere MT3620 開發工具包：

   azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
   

   範本會提供數個硬體定義。 例如，如果您使用 SEEED MT3620 Mini Dev Board，請改為指定 HardwareDefinitions/seeed_mt3620_mdb。

5. 按 F5 建置和偵錯專案。 如果專案先前尚未建置，或檔案已變更並重建是必要的，Visual Studio Code 會在偵錯開始之前建置專案。

6. 等候數秒，讓 Visual Studio Code 建置應用程式、建立映像套件、將其部署至面板，然後在偵錯模式中啟動它。 您會在一路上的 [輸出 ] 窗格中看到狀態更新。

   首先，CMake 會判斷是否需要建置應用程式。 如果是，焦點會轉移到輸出窗格，以顯示 CMake/Build 的輸出。

   接下來，輸出窗格會顯示 Azure Sphere 的輸出，因為它會將映像套件部署至裝置。 最後，偵錯控制台會接收焦點，並顯示 gdb 輸出。

   提示

   記下映射套件的位置，因為當您建立部署時需要它。 您應該會在 [輸出] 視窗中看到「建置檔案寫入<路徑>」之類的訊息，其中 <path> 是 Blink 應用程式建置資料夾的完整路徑，通常以 “out\ARM-Debug” 或 “out/ARM-Debug” 結尾。

7. 短暫延遲之後，您應該會看到LED閃爍。

8. 在 main.c 中的某處設定中斷點，並逐步執行應用程式，讓您可以探索 Azure Sphere 的 Visual Studio Code 偵錯功能。

使用 Visual Studio 建置並執行高階應用程式

本教學課程使用 Azure Sphere Blink 範本，這是適用於 Visual Studio 的 Azure Sphere 延伸模組的一部分。 Blink 範本會閃爍 LED，讓您可以確認 Azure Sphere 裝置和工具已安裝並正確設定。

1. 如果您不熟悉 Visual Studio，請考慮 快速入門 或 引導式導覽 ，以瞭解如何流覽和使用。

2. 開啟 Visual Studio，然後選取 [建立新專案]。 在 [搜尋] 方塊中，輸入 'azure sphere' 以取得 Azure Sphere 範本的清單。 從清單中選擇 [Azure Sphere Blink]。

3. 輸入項目的名稱和位置，然後選取 [ 建立]。

4. 開啟CMakeLists.txt檔案，並變更TARGET_DIRECTORY設定，以指定包含您所使用硬體定義的資料夾。 根據預設，TARGET_DIRECTORY會指定 HardwareDefinitions/mt3620_rbd，其符合 Seeed Azure Sphere MT3620 開發工具包：

   azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
   

   範本會提供數個硬體定義。 例如，如果您使用 SEEED MT3620 Mini Dev Board，請改為指定 HardwareDefinitions/seeed_mt3620_mdb。

5. 在 Visual Studio 中，選取 [檢視>輸出] 以顯示 [輸出] 窗格。

6. 確定您的裝置已透過USB連線到您的電腦。 在 [設定啟動專案] 功能表中，選取 Azure Sphere 應用程式 （HLCore），其中 Azure Sphere 應用程式是您目前高階應用程式的名稱，或按 F5。

   

7. 如果系統提示您建置專案，請選取 [ 是]。 Visual Studio 會編譯應用程式、建立映像套件、 側載 到面板上，並在偵錯模式中啟動它。 側載 表示應用程式會透過有線連線直接從電腦傳遞，而不是透過雲端傳遞。

   提示

   記下映射套件的位置，因為您在建立部署時需要它。 您應該會在 [檢視>輸出>顯示輸出來源： 組建] 的輸出中看到「輸出檔案位於：<路徑>」之類的訊息，其中<path>是 Blink 應用程式建置資料夾的完整路徑，通常以 “out/ARM-Debug” 結尾。

8. 根據預設，[ 輸出 ] 窗格會顯示 [ 裝置輸出] 的輸出。 若要查看調試程式的訊息，請從 [顯示輸出來源：] 下拉功能表中選取 [偵錯]。 您也可以透過 >[偵錯 Windows] 功能表檢查程式反組譯碼、緩存器或記憶體。

9. 當您執行程式時，應該會看到LED閃爍。

下載範例應用程式

您可以下載 HelloWorld 應用程式，如下所示：

1. 將瀏覽器指向 Microsoft範例瀏覽器。
2. 在 [搜尋] 方塊中輸入 “Azure Sphere”。
3. 從搜尋結果中選取 [Azure Sphere - Hello World ]。
4. 選取 [ 下載 ZIP]。
5. 開啟下載的檔案並解壓縮至本機目錄。

建置範例

若要為HelloWorld_HighLevelApp範例應用程式建立組建和 .imagepackage 檔案，請遵循下列步驟。

1. 視需要將範例更新為以您的硬體為目標。 根據預設，範例會以 MT3620 參考板設計 （RDB） 為目標的硬體，例如 Seeed Studios 的 MT3620 開發工具包。 範例應用程式的其他目標硬體定義可在 Azure Sphere 範例存放庫的 HardwareDefinitions 目錄中取得。 例如，Avnet MT3620 入門套件的硬體定義檔案位於 HardwareDefinitions/avnet_mt3620_sk 子目錄中。

   • 開啟CMakeLists.txt，並更新 azure_target_hardware_definition 函式中的 TARGET_DIRECTORY 參數，以指向硬體的子目錄。 例如：

     azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "../../../HardwareDefinitions/avnet_mt3620_sk" TARGET_DEFINITION "sample_appliance.json")
     

2. 使用 PowerShell、Windows 命令提示字元或 Linux 命令殼層開啟命令行介面。 流覽至您的專案組建目錄。

3. 從您的項目建置目錄，在命令提示字元中，使用下列參數執行 CMake：

   cmake --preset <preset-name> <source-path>
   

   • --preset <preset-name>

     CMakePresets.json中所定義的組建組態預設名稱。

   • --build <cmake-path>

     包含 CMake 快取的二進位目錄。 例如，如果您在 Azure Sphere 範例上執行 CMake，組建命令會是 cmake --build out/ARM-Debug。

   • <source-path>

     包含範例應用程式來源檔案之目錄的路徑。 在此範例中，Azure Sphere 範例存放庫已下載至名為 AzSphere 的目錄。

     CMake 參數會以空格分隔。 行接續字元 （^ for Windows 命令行、 \ for Linux 命令行或 ' for PowerShell） 可用於可讀性，但並非必要。

   下列範例顯示 Hello World 高階應用程式的 CMake 命令：

   Windows

   Windows 命令提示字元

    cmake ^
    --preset "ARM-Debug" ^
    "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
   

   Windows PowerShell

    cmake `
    --preset "ARM-Debug" `
    "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
   

   Linux

   cmake \
    --preset "ARM-Debug" \
    ./AzSphere/azure-sphere-samples/Samples/HelloWorld/HelloWorld_HighLevelApp
   

4. 執行 Ninja 以建置應用程式並建立映像套件檔案：

   ninja -C out/ARM-Debug
   

   Ninja 會將產生的應用程式和 .imagepackage 檔案放在指定的目錄中。

   您也可以使用下列命令透過 CMake 叫用 Ninja：

   cmake --build out/<binary-dir>
   

   設定 <binary-dir> 為包含 CMake 快取的二進位目錄。 例如，如果您在 Azure Sphere 範例上執行 CMake，組建命令會是 cmake --build out/ARM-Debug。

   進行疑難解答時，特別是在對 CMake 命令進行任何變更之後，請刪除整個組建，然後再試一次。

執行範例

1. 如果您的裝置已經執行應用程式，請刪除應用程式：

   azsphere device sideload delete
   

2. 變更為包含先前建立之組建和 .imagepackage 檔案的目錄。

3. 執行 azsphere device sideload deploy 命令並指定映像套件，以將映射套件載入您的裝置。 例如：

   Azure Sphere CLI

   azsphere device sideload deploy --image-package HelloWorld_HighLevelApp.imagepackage
   

   Azure Sphere 傳統 CLI

   azsphere device sideload deploy --imagepackage HelloWorld_HighLevelApp.imagepackage
   

   注意

   Azure Sphere 傳統 CLI 即將淘汰。 我們建議使用 Azure Sphere（整合）。

   此命令會載入映像套件並啟動應用程式。 您應該會看到LED閃爍。

   提示

   請注意映像套件的路徑。 您稍後會在部署快速入門中使用映像套件。

對範例進行偵錯

1. 變更為包含先前建立之組建和 .imagepackage 檔案的目錄。

2. 如果您還沒有元件識別碼，請取得它：

   Azure Sphere CLI

   azsphere image-package show --image-package HelloWorld_HighLevelApp.imagepackage
   

   Azure Sphere 傳統 CLI

   azsphere image-package show --filepath HelloWorld_HighLevelApp.imagepackage
   

   注意

   Azure Sphere 傳統 CLI 即將淘汰。 我們建議使用 Azure Sphere（整合）。

---

1. 如果應用程式正在執行，請停止它，然後使用 選項重新啟動它 --debug-mode ：

   Azure Sphere CLI

   azsphere device app stop --component-id <ComponentId>
   

   azsphere device app start --debug-mode --component-id <ComponentId>
   

   Azure Sphere 傳統 CLI

   azsphere device app stop --componentid <ComponentId>
   

   azsphere device app start --debug --componentid <ComponentId>
   

   注意

   Azure Sphere 傳統 CLI 即將淘汰。 我們建議使用 Azure Sphere（整合）。

---

您應該會看到：

 <ComponentId>
 App state   : debugging
 GDB port    : 2345
 Output port : 2342
 Core        : High-level

1. 使用終端機用戶端建立 Telnet 或原始 TCP 連線，以從進程讀取輸出數據流。 將 192.168.35.2 指定為 IP 位址，並將 2342 指定為埠。

2. 使用 PowerShell 或 Windows 上的標準命令提示字元或 Linux 上的命令殼層開啟命令行介面，並將 .out 應用程式二進制檔從組建傳遞為參數。 這會啟用完整的原始程式碼偵錯。

   Windows

   Windows 命令提示字元

   "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb" HelloWorld_HighLevelApp.out
   

   Windows PowerShell

   & "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb" HelloWorld_HighLevelApp.out
   

   Linux

    /opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-musleabi/arm-poky-linux-musleabi-gdb HelloWorld_HighLevelApp.out
   

   注意

   Azure Sphere SDK 隨附多個 sysroot，讓應用程式可以以不同的 API 集合為目標，如應用程式運行時間版本、sysroots 和 Beta API 中所述。 sysroots 會安裝在 Sysroots 下的 Azure Sphere SDK 安裝資料夾中。

3. 將遠端偵錯目標設定為埠 2345 上的 IP 位址 192.168.35.2：

   target remote 192.168.35.2:2345

4. 執行您選擇的任何其他 gdb 命令。 例如，下列命令會在main（） 項目時設定斷點，然後分別在斷點之後繼續執行。

   break main
   

   c
   

   如需使用 gdb 進行偵錯的詳細資訊，請參閱 GDB：GNU 專案調試程式 或主題上其他許多來源的其中一個。

下一步

您已建置高階應用程式，以在 Azure Sphere 裝置上執行。 您可能現在想要修改它。 硬體定義 描述如何編輯硬體定義 JSON 檔案，並重新產生相關聯的頭檔。

接下來，瞭解如何從雲端部署高階應用程式。

教學課程：建立雲端部署

另請參閱

流覽 Azure Sphere 資源庫，這是鼓舞人心、未經處理且可重複使用的 Azure Sphere 腳本、公用程式和函式集合。