使用容器建立 Azure 球體應用程式

發行項
08/09/2023

注意

本主題說明如何使用 Windows 版 Docker Desktop 在容器中建置 Azure 球體應用程式。若要在 Linux 的 Docker 容器中建置應用程式，您可以從Microsoft 成品登錄或 MAR (也稱為 Microsoft Container Registry 或 MCR) 使用相同的 azurespheresdk 容器。

安裝 Docker Desktop

您可以使用 Docker 來執行已預先安裝 Azure 球體 SDK 的獨立 Linux 容器。此影像也可以做為您自己部署的基座。影像標籤是指其中所含的 SDK 版本。

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

安裝 Windows 版 Docker Desktop 之後，請確定您啟用 Hyper-V 和 Containers Windows 功能。您可能需要在安裝後重新開機。

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

Linux 是 Windows 上 Docker Desktop 的預設容器類型。 Azure 球體使用 Linux 容器。若要執行 Linux 容器，您必須確定 Docker 是以正確的 daemon 為目標。若要確認 Linux 是目前的預設容器類型，請以滑鼠右鍵按一下系統匣中的 Docker whale 圖示。如果您看到 [切換到 Windows 容器]，表示您已將目標鎖定在 Linux daemon。如果您在 Windows 容器上，當您以滑鼠右鍵按一下系統匣中的 Docker whale 圖示時，可以從動作功能表中選取 [切換到 Linux 容器 ]，藉此切換此選項。如需詳細資訊，請參閱在 Windows 和 Linux 容器之間切換。

注意

等到 Docker 桌面鯨魚圖示動畫停止。圖示可能在隱藏的 [通知] 區域中。將游標暫留在圖示上以查看 Docker 桌面狀態。

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

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

下列步驟提供建立 Dockerfile 指示以建立 Azure 球體範例的大綱。您可以根據自己的需求來調整這些步驟。

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

建立建築物樣本的 Dockerfile

若要根據 Azure 球體影像建立 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 HelloWorld_HighLevelApp) 的範例應用程式將會建置在容器內的目錄中 /build 。容器完成執行後，就會結束並帶您回到命令列介面。

注意

此命令會在不進行任何互動的情況下建立應用程式，並在完成組建後結束容器。容器在您結束之後仍處於使用中狀態。這是因為您沒有指定 -it 或 --rm 選項。只要 Docker Desktop 正在執行，您稍後就可以在容器上再次使用 docker run 命令而不重新建立命令。
將組建的結果從容器內複製到主機電腦環境。使用命令列介面輸入此命令：
```
docker cp hello_hl:/build .
```
此命令會將hello_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 CLI 命令來部署應用程式。如需詳細資訊，請參閱部署應用程式。

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

Dockerfile 指示的逐行討論

以下說明在建立 Dockerfile 中建立的 Dockerfile 每個部分以供建築物樣本使用。

準備多個組建

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

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

下載 Azure 球體範例

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

此線條會複製 Azure 球體樣本檢視的所有樣本。

新增另一個目標多階段組建

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 執行命令以互動方式探索基座容器

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

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

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

Azure 球體 SDK 建置環境 Docker 容器由Microsoft 成品登錄 (MAR) 提供，可供大眾使用。

如果容器已經在本機電腦上，將不會再次下載。

下載和設定可能需要幾分鐘的時間。建置環境包含使用 Azure 球體 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 會為容器擁有者編列隨機名稱。請注意，在此範例中，只有一個容器。

在容器內工作

如果您想要在電腦上的容器內工作，而不使用 執行命令， 請使用 執行命令搭配 容器識別碼，以及您要執行的容器中的腳本， (/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 球體 SDK 組建容器限制

Azure 球體 SDK 建置容器是專為僅建置 Azure 球體套件所設計。它並非專為執行 Azure 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 引數的詳細資訊，請參閱命名您的組建階段。

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

當您建立目標時，您可以使用 --標籤 選項，為它取一個有意義的名稱。有意義的名稱很有用。例如：

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

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

共用方式為