教學課程：使用 Azure Developer CLI 和 GitHub 動作部署 .NET Aspire 專案

發行項
12/12/2024

Azure Developer CLI （azd）可讓您自動設定必要的驗證和環境設定，使用 GitHub Actions 部署 .NET Aspire 專案。本文將逐步引導您使用 azd 和 GitHub Actions 在 Azure Container Apps 上建立和部署 .NET Aspire 專案。您將瞭解下列概念：

探索 azd 整合如何與 .NET Aspire 專案和 GitHub 行動協同運作
使用 azd 建立及設定 .NET Aspire 專案的 GitHub 存放庫
將 GitHub Actions 工作流程檔案新增至您的 .NET Aspire 解決方案
監視和探索 GitHub 動作工作流程執行和 Azure 部署

先決條件

若要使用 .NET.NET Aspire，您需要在本機安裝下列項目：

.NET 8.0 或 .NET 9.0
符合 OCI 規範的容器運行時間，例如：
- Docker 桌面或 Podman。如需詳細資訊，請參閱容器運行時間。
整合式開發人員環境（IDE）或程式碼編輯器，例如：
- Visual Studio 2022 17.9 版或更高版本（選用）
- Visual Studio Code （選擇性）
  - C# Dev Kit：擴充功能（選擇性）
- JetBrains Rider 搭配 .NET.NET Aspire 外掛程式（選用）

如需詳細資訊，請參閱 .NET.NET Aspire 設定和工具和 .NET.NET Aspire SDK。

建立 Azure DevOps 組織或選擇現有的組織
建立 Azure DevOps 個人存取令牌（PAT），並儲存以供稍後使用。將權杖配置以下權限：
- 代理程式集區（讀取、管理）
- 建置（讀取並執行）
- 程式代碼（完整）
- 專案和團隊（讀取、寫入和管理）
- 發行（讀取、寫入、執行和管理）
- 服務連線（讀取、查詢和管理）

您也需要在本機安裝 Azure Developer CLI 版（1.5.1 版或更高版本）。常見的安裝選項包括下列各項：

winget install microsoft.azd

brew tap azure/azd && brew install azd

curl -fsSL https://aka.ms/install-azd.sh | bash

建立 .NET.NET Aspire 解決方案

本文假設您已從 .NET.NET Aspire 入門應用程式 範本建立 .NET.NET Aspire 解決方案。如需詳細資訊，請參閱快速入門：建置您的第一個 .NET.NET Aspire 應用程式。

初始化範本

開啟新的終端機視窗，並 cd 您 .NET 解決方案的 .NET Aspire 項目目錄。
執行 azd init 命令，以使用 azd初始化專案，這會檢查本機目錄結構，並判斷應用程式的類型。
```
azd init
```
如需 azd init 命令的詳細資訊，請參閱 azd init。

當提示您使用兩個應用程式初始化選項時，請選取 azd。

? How do you want to initialize your app?  [Use arrows to move, type to filter]
> Use code in the current directory
  Select a template

掃描目錄之後，會提示您確認它找到正確的 appHost 專案。選取 [確認並繼續初始化我的應用程式 選項。

Detected services:

  .NET (Aspire)
  Detected in: D:\source\repos\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj

azd will generate the files necessary to host your app on Azure using Azure Container Apps.

? Select an option  [Use arrows to move, type to filter]
> Confirm and continue initializing my app
  Cancel and exit

輸入環境名稱，用來命名 Azure 中布建的資源，以及管理不同的環境，例如 dev 和 prod。

Generating files to run your app on Azure:

  (✓) Done: Generating ./azure.yaml
  (✓) Done: Generating ./next-steps.md

SUCCESS: Your app is ready for the cloud!
You can provision and deploy your app to Azure by running the azd up command in this directory. For more information on configuring your app, see ./next-steps.md

azd 會產生數個檔案，並將其放在工作目錄中。這些檔案包括：

azure.yaml：描述應用程式的服務，例如 .NET Aspire AppHost 專案，並將其對應至 Azure 資源。
.azure/config.json：向 azd 通知目前作用中的環境的組態檔。
。azure/aspireazddev/.env：包含環境特定的覆寫。

新增 GitHub Actions 工作流程檔案

雖然 azd 為您產生一些基本範本檔案，但專案仍然需要 GitHub Actions 工作流程檔案，以支援使用 CI/CD 的佈建和部署。

建立一個位於專案根目錄的空 github 資料夾。 azd 預設會使用此目錄來探索 GitHub Actions 工作流程檔案。
提示

如果您是 macOS 的使用者，並且在建立以 .開頭的資料夾時遇到困難，您可以使用終端來建立該資料夾。開啟終端機，並流覽至專案的根目錄。執行下列命令以建立資料夾：
```
mkdir .github
```
在新的 .github 資料夾內，建立另一個名為 工作流程 的資料夾（最終結果將是 .github/workflows）。
將新的 GitHub Actions 工作流程檔案新增至名為 azure-dev.yml的新資料夾中。 azd 入門範本提供範例 GitHub 動作工作流程檔案，您可以複製到專案中。

更新範例 GitHub Actions 工作流程，以包含安裝 .NET Aspire 工作負載的步驟。這可確保執行 .NET Aspire 動作的作業可以使用 GitHub 工具和命令。已完成的工作流程檔案必須符合下列內容：

on:
  workflow_dispatch:
  push:
    # Run when commits are pushed to mainline branch (main or master)
    # Set this to the mainline branch you are using
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
      AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}
      AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
      AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install azd
        uses: Azure/setup-azd@v1.0.0

      - name: Install .NET Aspire workload
        run: dotnet workload install aspire

      - name: Log in with Azure (Federated Credentials)
        if: ${{ env.AZURE_CLIENT_ID != '' }}
        run: |
          azd auth login `
            --client-id "$Env:AZURE_CLIENT_ID" `
            --federated-credential-provider "github" `
            --tenant-id "$Env:AZURE_TENANT_ID"
        shell: pwsh

      - name: Log in with Azure (Client Credentials)
        if: ${{ env.AZURE_CREDENTIALS != '' }}
        run: |
          $info = $Env:AZURE_CREDENTIALS | ConvertFrom-Json -AsHashtable;
          Write-Host "::add-mask::$($info.clientSecret)"

          azd auth login `
            --client-id "$($info.clientId)" `
            --client-secret "$($info.clientSecret)" `
            --tenant-id "$($info.tenantId)"
        shell: pwsh

      - name: Provision Infrastructure
        run: azd provision --no-prompt
        # Required when 
        # env:
        #   AZD_INITIAL_ENVIRONMENT_CONFIG: ${{ secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}

      # Required when provisioning and deploying are defined in separate jobs.
      # - name: Refresh azd env (pulls latest infrastructure provision)
      #  run: azd env refresh
      #  env:
      #    AZURE_LOCATION: ${{ env.AZURE_LOCATION }}

      - name: Deploy Application
        run: azd deploy --no-prompt

此外，您可能會注意到布建和部署步驟會合併成單一作業。如果您想要將這些步驟分成不同的作業，您可以在工作流程檔案中建立兩個不同的作業來執行此作業。布建作業應該先執行，後面接著部署作業。部署作業應包含 AZD_INITIAL_ENVIRONMENT_CONFIG 秘密，以確保部署作業能夠存取環境設定。您還需要將部署作業中 azd env refresh 步驟的註解移除，以確保部署作業能夠存取最新的基礎設施配置。

建立 GitHub 存放庫和管線

Azure Developer CLI 可讓您使用正確的配置和許可權，自動建立 CI/CD 管線，以佈建和部署資源到 Azure。如果應用程式不存在，azd 也可以為您的應用程式建立 GitHub 存放庫。

執行 azd pipeline config 命令來設定部署管線，並安全地將它連線至 Azure：
```
azd pipeline config
```
選取要配置和部署應用程式資源的訂用帳戶。
選取要用於資源的 Azure 位置。
當系統提示您是否要在目錄中建立新的 Git 存放庫時，請輸入 y，然後按 Enter。

注意

建立 GitHub 存放庫時，您必須登入 GitHub。有幾個選擇會根據您的喜好設定而有所不同。登入之後，系統會提示您在目前目錄中建立新的存放庫。
選擇 建立新的私人 GitHub 存放庫 來設定遠端 git。
為新的 GitHub 存放庫輸入您選擇的名稱，或按 enter 鍵以使用預設名稱。 azd 會在 GitHub 中建立新的存放庫，並使用驗證至 Azure所需的必要秘密進行設定。
輸入 和，當 azd 提示您提交並推送本機變更以啟動已設定的管線時繼續。

探索 GitHub 動作工作流程和部署

請使用由 GitHub提供的連結來瀏覽新的 azd 存放庫。
選取 [動作] 索引標籤，以檢視存放庫工作流程。您應該會看到新的工作流程正在執行或已完成。選取工作流程以檢視執行記錄中的作業步驟和詳細數據。例如，您可以展開步驟，例如 安裝 .NET.NET Aspire 工作負載 或 部署應用程式，以查看已完成動作的詳細數據。
選取 部署應用程式 以展開該步驟的日誌。您應該會看到兩個針對 apiservice 和 webfrontend列印出的端點 URL。選取其中一個連結，以在另一個瀏覽器索引標籤中開啟連結，並探索已部署的應用程式。

祝賀！您已使用 Azure Developer CLI 和 GitHub Actions 成功部署 .NET Aspire 專案。

設定工作流程檔案

雖然 azd 為您產生一些基本範本檔案，但專案仍然需要 Azure Pipelines 工作流程檔案，以支援使用 CI/CD 的佈建和部署。

在專案的根目錄建立空白 .azdo 資料夾。 azd 預設會使用此目錄來尋找 Azure 管線的工作流程檔案。
在新的 .azdo 資料夾中，建立另一個名為 pipelines 的資料夾（這樣就會得到 .azdo/pipelines）。
將新的 Azure Pipelines 工作流程檔案新增至名為 azure-dev.yml的新資料夾中。 azd 入門範本提供範例 Azure Pipelines 工作流程檔案，您可以複製到專案中。
更新範例 Azure Pipelines 工作流程，以包含安裝 .NET Aspire 工作負載的步驟。已完成的工作流程檔案必須符合下列內容：

trigger:
  - main
  - master

pool:
  vmImage: ubuntu-latest

steps:

  - task: Bash@3
    displayName: Install azd
    inputs:
      targetType: 'inline'
      script: |
        curl -fsSL https://aka.ms/install-azd.sh | bash

  # azd delegate auth to az to use service connection with AzureCLI@2
  - pwsh: |
      azd config set auth.useAzCliAuth "true"
    displayName: Configure `azd` to Use AZ CLI Authentication.

  - task: Bash@3
    displayName: Install .NET Aspire workload
    inputs:
      targetType: 'inline'
      script: |
        dotnet workload install aspire

  - task: AzureCLI@2
    displayName: Provision Infrastructure
    inputs:
      azureSubscription: azconnection
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        azd provision --no-prompt
    env:
      AZURE_SUBSCRIPTION_ID: $(AZURE_SUBSCRIPTION_ID)
      AZURE_ENV_NAME: $(AZURE_ENV_NAME)
      AZURE_LOCATION: $(AZURE_LOCATION)

  - task: AzureCLI@2
    displayName: Deploy Application
    inputs:
      azureSubscription: azconnection
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        azd deploy --no-prompt
    env:
      AZURE_SUBSCRIPTION_ID: $(AZURE_SUBSCRIPTION_ID)
      AZURE_ENV_NAME: $(AZURE_ENV_NAME)
      AZURE_LOCATION: $(AZURE_LOCATION)

建立 Azure DevOps 存放庫和管道

重要

如必要條件中所述，您必須建立 Azure DevOps 組織，或選取現有的組織來完成後續步驟。您也必須使用必要條件所列的許可權建立個人存取令牌（PAT）。

Azure Developer CLI 可讓您自動建立具備正確組態和許可權的管線，以便將資源布建和部署至 Azure。如果 azd 管線存放庫不存在，Azure 也可以為您的應用程式建立一個。

執行 azd pipeline config 命令來設定部署管線，並安全地將它連線至 Azure。包含 --provider azdo 選項，以使用 Azure Pipelines，而不是預設的 GitHub Actions 組態。
```
azd pipeline config --provider azdo
```
選取要配置和部署應用程式資源的訂用帳戶。
選取要用於資源的 Azure 位置。
貼上您稍早建立的個人存取令牌。
輸入您所建立或選取 Azure DevOps 組織名稱。
當系統提示您在目前目錄中建立新的存放庫時，請輸入 y，然後按 Enter。
當系統提示您設定 git 遙控器時，請選擇 [建立新的 Azure DevOps Project]。
為新的存放庫輸入您選擇的唯一名稱，例如 aspireazd。 azd 會在 Azure Repos 中建立新的存放庫，並設定必要的秘密以完成對 Azure的驗證。
輸入 和，當 azd 提示您提交並推送本機變更以啟動已設定的管線時繼續。

探索管線和已部署的應用程式

使用 Azure的狀態鏈接，導航至您的新 azd 管線。
選取已完成的管線執行以檢視摘要。
選取檢視底部的作業連結，以流覽至作業詳細數據。
[作業詳細數據] 頁面會顯示所有個別階段的狀態。選取 [[布建基礎結構] 以檢視該階段的記錄，其中詳述 azd完成的所有布建步驟。在日誌的底部記下最終狀態訊息，並連結到配置的 Azure 資源群組。
選取布建輸出記錄底部的連結，以流覽至新的 Azure 資源群組。

注意

您也可以在 Azure 入口網站中搜尋並直接導航到您的新資源群組。您的資源組名會是您提供給 azd 前面加上 rg-的環境名稱。
選取 webfrontend 容器應用程式，其中裝載您網站的公用面向部分。
在 [webfrontend 詳細數據] 頁面上，選取 [應用程式 URL] 連結，以在瀏覽器中開啟您的網站。

重要

如果您在瀏覽器中檢視您的網站時遇到 403 Forbidden 錯誤，請確保入口設定已正確配置。在入口網站的 Azure 應用程式頁面上，導航至左側導覽的輸入。請確定 入口流量 設定為 接受來自任何地方的流量， 並儲存變更。

祝賀！您已成功使用 Azure Developer CLI 和 Azure Pipelines 部署 .NET Aspire 專案。

清除資源

當您不再需要您所建立 Azure 資源時，請執行下列 Azure CLI 命令來刪除資源群組。刪除資源群組也會刪除其內含的資源。

az group delete --name <your-resource-group-name>

如需詳細資訊，請參閱中的清除資源。

共用方式為