使用容器建置 Azure Sphere 應用程式

發行項
09/27/2024

重要

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

注意

本主題描述如何使用適用於 Windows 的 Docker Desktop 在容器中建置 Azure Sphere 應用程式。若要在Linux上的Docker容器中建置應用程式，您可以從 Microsoft 成品登錄或 MAR 使用相同的 azurespheresdk 容器（也稱為 Microsoft Container Registry 或 MCR）。

安裝 Docker Desktop

您可以使用 Docker 來執行預安裝 Azure Sphere SDK 的獨立 Linux 容器。此映像也可以作為您自己的部署基底。映射標籤是指它所包含的 SDK 版本。

您必須先在 Windows 或 Linux 上安裝 Docker Desktop，才能下載並執行 Docker 容器。

安裝適用於 Windows 的 Docker Desktop 之後，請確定您啟用 Hyper-V 和容器 Windows 功能。您可能需要在安裝之後重新啟動。

安裝之後，請從 Windows [開始] 功能表或從新增至桌面的快捷方式圖示啟動 Docker Desktop。

Linux 是 Windows 上 Docker Desktop 的預設容器類型。 Azure Sphere 使用 Linux 容器。為了執行 Linux 容器，您必須確定 Docker 將正確精靈設為目標。若要確認 Linux 是目前的預設容器類型，請以滑鼠右鍵按兩下系統匣中的 Docker 鯨魚圖示。如果您看到 [切換至 Windows 容器]，則表示您已經以 Linux 精靈為目標。如果您是在 Windows 容器上，您可以在系統匣中的 Docker 鯨魚圖示上按滑鼠右鍵時，從動作功能表中選取 [切換至 Linux 容器 ] 來切換此選項。如需詳細資訊，請參閱在 Windows 與 Linux 容器之間切換。

注意

等到 Docker Desktop 鯨魚圖示動畫停止為止。圖示可能位於隱藏的 [通知] 區域中。將滑鼠停留在圖示上方，以查看 Docker Desktop 狀態。

使用 Azure Sphere SDK 建置環境容器來建置範例應用程式

您可以輸入容器並發出命令，以互動方式使用容器;不過，擷取在 Docker 可用來根據原始 Azure Sphere 映射建置自定義映像的檔案中建置應用程式所需的步驟會更有效率。這可確保建置程式可重複且一致。根據預設，此檔案必須命名為 Dockerfile，且位於執行 docker 命令的$PATH中。

下列步驟提供建立 Dockerfile 指示以建置 Azure Sphere 範例的大綱。您可以調整這些步驟以符合自己的需求。

根據 mcr.microsoft.com/azurespheresdk 容器建立新的容器。
從 GitHub 複製 Azure Sphere 範例存放庫。
建立目錄，以在建置範例時儲存您的範例。
建立環境變數以指定您想要建置的範例。
執行 CMake 來建置範例，並將它放在指定的目錄中。

建立用於建置範例的 Dockerfile

若要根據 Azure Sphere 映射建置 Docker 映射，但具有自定義建置功能，請使用下列 Docker 指示建立文字檔（不含擴展名）：

FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo

RUN git clone https://github.com/Azure/azure-sphere-samples.git

FROM azsphere-samples-repo AS azsphere-sampleapp-build

RUN mkdir /build
WORKDIR /build

ENV sample=HelloWorld/HelloWorld_HighLevelApp

CMD cmake -G "Ninja" \
-DCMAKE_TOOLCHAIN_FILE="/opt/azurespheresdk/CMakeFiles/AzureSphereToolchain.cmake" \
-DAZURE_SPHERE_TARGET_API_SET="latest-lts" \
-DCMAKE_BUILD_TYPE="Debug" \
/azure-sphere-samples/Samples/${sample} && \
ninja

此檔案會 使用 ENV 環境變數來指定要建置的範例。設定 ENV 的新值，以建置與 HelloWorld/HelloWorld_HighLevelApp 不同的範例。

如需 Dockerfile 指示的詳細資訊，請參閱 Dockerfile 指示的逐行討論。

使用 Dockerfile 建置預設範例應用程式

使用自訂 Dockerfile 建置範例應用程式需要三個步驟：

使用 PowerShell、Windows 命令提示字元或 Linux 命令殼層等命令行介面，從 Dockerfile 建置映射：
```
docker build --target azsphere-sampleapp-build --tag azsphere-sampleapp-build .
```
選項 --target 會指定要使用多階段組建的哪個部分。選項 --tag 會指定映像的名稱，而且必須只有小寫。 Docker 映像一律只能使用小寫字母。如果您未使用指定名稱 --tag，則影像會有一個 12 位數的數位，並不容易使用。不要忘記命令結尾的句號。您可以使用命令列出影像 docker images 。

Docker 會根據名為 “Dockerfile” 的檔案，建置名為 azsphere-sampleapp-build 的映射。如果您的 Dockerfile 命名為其他名稱，請使用 --file 選項來指定名稱。
使用 --name 選項為容器提供更簡單的名稱。此命令run會輸入容器，並建置 ENV 環境變數所指定的範例。使用命令列介面來輸入此指令：
```
docker run --name hello_hl azsphere-sampleapp-build
```
範例應用程式（HelloWorld/HelloWorld_HighLevelApp）將會建置，並將放在 /build 容器內的目錄中。當容器完成執行時，它會結束並帶您回到命令行介面。

注意

此命令會建置應用程式，而不需要任何互動，並在建置完成後結束容器。結束之後，容器仍在作用中。這是因為您未指定 -it 或 --rm 選項。只要 Docker Desktop 正在執行，您就可以在容器上再次使用 docker run 命令，而不需要重建它。
將組建的結果從容器內部複製到主計算機環境。使用命令列介面來輸入此指令：
```
docker cp hello_hl:/build .
```
此命令會將你好_h1 容器內的目錄內容/build複製到您發出命令的主計算機上目錄。目錄 /build 會指定為要編譯範例的工作目錄（WORKDIR）。請注意，您仍在容器外部，但使用 docker cp 命令向容器發出命令。不要忘記命令結尾的句號。

使用自定義 Dockerfile 建置不同的範例

若要建置不同的範例，例如 GPIO 範例，請提供 GPIO 範例的路徑。

docker run --name gpio_hl --env sample=GPIO/GPIO_HighLevelApp azsphere-sampleapp-build

建置完成之後，將結果從容器內部複製到主計算機環境：

docker cp gpio_hl:/build .

不要忘記命令結尾的句號。

將套件複製到主計算機環境之後，您可以使用來自 Windows 或 Linux 的 Azure Sphere CLI 命令來部署應用程式。如需詳細資訊，請參閱部署應用程式。

不支援透過 USB 從容器進行裝置互動。

Dockerfile 指示的逐行討論

以下說明在建立 Dockerfile 來建置範例中建立之 Dockerfile 的每個部分。

準備多個組建

FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo

此行會根據原始 microsoft.com/azurespheresdk 容器來設定新的組建 azsphere-samples-repo。

下載 Azure Sphere 範例

RUN git clone https://github.com/Azure/azure-sphere-samples.git

這一行會從 Azure Sphere 範例存放庫複製所有範例。

新增另一個可設定目標的多階段組建

FROM azsphere-samples-repo AS azsphere-sampleapp-build

這一行會根據 azsphere-samples-repo 組建新增組建。

在容器內設定工作目錄

RUN mkdir /build
WORKDIR /build

這幾行會建立新的工作目錄。

建立預設環境變數以指定範例

ENV sample=HelloWorld/HelloWorld_HighLevelApp

這一行會建立環境變數，指定要建置的範例。在此情況下，這是HelloWorld_HighLevelApp範例。您可以覆寫環境變數，以指定任何範例名稱和路徑。

執行 CMake 和 Ninja 來建置套件

CMD cmake -G "Ninja" \
-DCMAKE_TOOLCHAIN_FILE="/opt/azurespheresdk/CMakeFiles/AzureSphereToolchain.cmake" \
-DAZURE_SPHERE_TARGET_API_SET="latest-lts" \
-DCMAKE_BUILD_TYPE="Debug" \
/azure-sphere-samples/Samples/${sample} && \
ninja

本節會使用 CMake 來指定叫用 Ninja 來建置套件時所使用的參數。

建置完成之後，容器將會停止執行。

Docker 秘訣

這些秘訣可協助您更有效地使用 Docker。

使用 docker run 命令以互動方式探索基底容器

使用命令列介面來輸入此指令：

docker run --rm -it mcr.microsoft.com/azurespheresdk

在此範例中， mcr.microsoft.com/azurespheresdk 是建立容器的來源映像名稱。請注意， --rm 選項會在容器執行之後關閉容器，而 -it 選項會指定對容器的互動式存取。

Azure Sphere SDK 建置環境 Docker 容器是由 Microsoft 成品登錄（MAR）提供，可供公眾使用。

如果容器已在本機計算機上，則不會再次下載。

下載和設定可能需要幾分鐘的時間。建置環境包含使用 Azure Sphere Linux SDK 建置套件所需的所有專案。

run命令完成之後，您的命令提示字元會變更為「#」符號。您現在位於以Linux為基礎的Docker容器內。輸入 ls 會顯示容器內的目前 Linux 目錄，類似於下列清單：

bin   cmake-3.14.5-Linux-x86_64  etc   lib    makeazsphere.sh  mnt    opt   root  sbin  sys  usr
boot  dev                        home  lib64  media            ninja  proc  run   srv   tmp  var

輸入 exit 以離開容器。容器將不再可供您使用，您必須使用此命令再次建立容器：

docker run --rm -it mcr.microsoft.com/azurespheresdk

如果您沒有使用 --rm 選項，當您結束時，將不會刪除容器。

容器識別

當您建置新的容器時，它會有一個標識碼，例如 a250ade97090 （您的標識符會不同）。對於許多 Docker 命令，您必須使用識別碼，而不是 microsoft.com/azurespheresdk 位址。

以下是使用此命令來說明系統上容器的基本資訊一般清單：

docker ps --all

結果看起來會像這樣：

CONTAINER ID        IMAGE                   COMMAND             CREATED             STATUS              PORTS               NAMES
a250ade97090        microsoft.com/azurespheresdk   "/bin/bash"         15 minutes ago      Up 9 seconds                            pedantic_kilby

您的標識碼將會不同。請注意，Docker 會為容器擁有者構成隨機名稱。請注意，在此範例中，只有一個容器。

在容器內工作

如果您想要在機器上的容器內工作而不使用 run 命令，請使用 exec 命令搭配容器識別碼，以及您要執行容器中的腳本（/bin/bash） 輸入：

docker exec -t a250ade97090 /bin/bash

您的命令提示字元會變更為「#」符號。您現在位於以 Linux 為基礎的 Docker 容器中。輸入 ls 會顯示容器內的目前 Linux 目錄：

bin   cmake-3.14.5-Linux-x86_64  etc   lib    makeazsphere.sh  mnt    opt   root  sbin  sys  usr
boot  dev                        home  lib64  media            ninja  proc  run   srv   tmp  var

若要離開容器，請輸入 exit 命令。

Azure Sphere SDK 建置容器限制

Azure Sphere SDK 建置容器是設計來僅建置 Azure Sphere 套件。 它並非針對執行 Azure Sphere CLI 命令、復原或側載裝置或偵錯而設計。容器無法存取 USB 函式。

Docker Linux 容器限制

Docker Linux 容器與Linux的完整安裝不同。例如，您無法在 Docker Linux 容器中執行 Linux GUI 應用程式。

使用多階段建置容器來減少相依性

Docker 多階段建置功能可讓您在 Dockerfile 中使用多個 FROM 語句來減少相依性。每個FROM指令都可以使用不同的基底，而且每個指令都會開始組建的新階段。

如需 Docker 多階段組建的詳細資訊，請參閱使用多階段組建。

Docker 建議使用多階段組建作為最佳做法。如需 Docker 最佳做法的詳細資訊，請參閱 Dockerfile 最佳做法簡介指南。

使用 AS 自變數將有意義的名稱新增至階段

根據預設，階段不會命名，但有標識符。您可以藉由附加 AS 和名稱，將有意義的名稱新增至階段，讓 Dockerfile 更容易閱讀。例如：

FROM mcr.microsoft.com/azurespheresdk AS azsphere-samples-repo

如需在多階段命令中使用 AS 自變數的詳細資訊，請參閱為建置階段命名。

以有意義的名稱作為最佳做法來建置目標

當您建置目標時，可以使用 --tag 選項為它指定有意義的名稱。有意義的名稱很有用。例如：

docker build --target azsphere-sampleapp-build --tag azsphere-sampleapp-build .

如需搭配 Docker 建置命令使用名稱的詳細資訊，請參閱 Docker 組建參考。

共用方式為