教程：使用 .NET Aspire 和 Azure Developer CLI 操作部署 GitHub 项目

项目
12/15/2024

使用 Azure Developer CLI（azd），可以通过自动配置所需的身份验证和环境设置，使用 .NET Aspire 操作部署 GitHub 项目。本文介绍如何使用 .NET Aspire 和 Azure Container Apps Actions 在 azd 上创建和部署 GitHub 项目。你将了解以下概念：

了解 azd 集成如何与 .NET Aspire 项目和 GitHub 操作配合使用
使用 GitHub 为 .NET Aspire 项目创建和配置 azd 存储库
将 GitHub 操作工作流文件添加到 .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 应用。

初始化模板

打开新的终端窗口，并 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

扫描目录后，azd 会提示你确认它找到正确的 .NET.NET AspireAppHost 项目。选择 确认并继续初始化我的应用 选项。

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 操作工作流文件

尽管 azd 为你生成了一些基本模板文件，但项目仍需要 GitHub Actions 工作流文件来支持使用 CI/CD 进行预配和部署。

在你的项目根目录中创建一个空的 。github 文件夹。默认情况下，azd 使用此目录来发现 GitHub Actions 工作流文件。
提示

如果你使用 macOS 并且在创建以 .开头的文件夹时遇到困难，可以使用终端来创建文件夹。打开终端并导航到项目的根目录。运行以下命令以创建文件夹：
```
mkdir .github
```
在新 .github 文件夹中，创建名为 工作流 的另一个文件夹（最终你将获得 .github/workflows）。
将新的 GitHub 操作工作流文件添加到名为 azure-dev.yml的新文件夹中。 azd 初学者模板提供了一个示例 GitHub 操作工作流文件，你可以将其复制到项目中。

更新示例 GitHub 操作工作流，以包含安装 .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 Actions 工作流及部署

通过GitHub输出的链接导航到新的azd存储库。
选择操作选项卡以查看存储库工作流。应会看到新工作流正在运行或已完成。选择工作流以查看运行日志中的作业步骤和详细信息。例如，可以展开 安装 .NET.NET Aspire 工作负荷 或 部署应用程序 等步骤以查看已完成操作的详细信息。
选择“部署应用程序”以展开此步骤的日志。您应该看到打印出的 apiservice 和 webfrontend的两个端点地址。选择其中任一链接可在另一个浏览器选项卡中打开它们，并浏览已部署的应用程序。

祝贺！使用 .NET Aspire 和 Azure Developer CLI 操作成功部署了 GitHub 项目。

配置工作流文件

尽管 azd 为你生成了一些基本模板文件，但项目仍然需要一个 Azure Pipelines 工作流文件来支持使用 CI/CD 进行预配和部署。

在项目的根目录中创建空 .azdo 文件夹。默认情况下，azd 使用此目录来发现 Azure Pipelines 工作流文件。
在新的 .azdo 文件夹中，创建一个名为 pipelines 的文件夹（最终的路径是 .azdo/pipelines）。
将新的 Azure Pipelines 工作流文件添加到名为 azure-dev.yml的新文件夹中。 azd 初学者模板提供了一个示例 Azure 管道工作流文件，可以复制到项目中。
更新示例 Azure 管道工作流，以包含安装 .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 管道代替默认的 GitHub 操作配置。
```
azd pipeline config --provider azdo
```
选择要用于准备和部署应用资源的订阅。
选择Azure位置用于资源存储。
粘贴之前创建的个人访问令牌。
输入已创建或选择的 Azure DevOps 组织名称。
当系统提示在当前目录中创建新存储库时，请输入 y，然后按 Enter。
当系统提示配置 git 远程时，请选择 创建新的 Azure DevOps 项目。
为新存储库输入所选的唯一名称，例如 aspireazd。 azd 在 Azure Repos 中创建新的存储库，并使用 Azure进行身份验证所需的必要机密对其进行配置。
当提示您提交并推送本地更改以启动配置的管道时，输入 azd 以继续。

浏览管道和已部署的应用

使用由 Azure输出的状态链接导航到您的新 azd 管道。
选择已完成的管道运行以查看摘要。
选择视图底部的作业链接，导航到作业详细信息。
作业详细信息页显示所有各个阶段的状态。选择 预配基础结构 以查看该阶段的日志，其中详细介绍了 azd完成的所有预配步骤。在日志底部记下最终状态消息，并链接到预配的 Azure 资源组。
选择预配输出日志底部的链接，导航到新的 Azure 资源组。

注意

还可以通过在 Azure 门户中搜索它，直接导航到新资源组。您的资源组名称将是您提供给 azd 的环境名称，并以 rg-为前缀。
选择 webfrontend 容器应用，该应用托管网站的面向公众的部分。
在 Web前端 详细信息页面上，选择 应用 URL 链接以在浏览器中打开您的网站。

重要

如果在浏览器中查看站点时遇到 403 Forbidden 错误，请确保正确配置入口设置。在门户中的 Azure 应用页面上，从左侧导航转到 Ingress。请确保将 入口流量 设置为 接受来自任何地方的流量，并保存更改。

祝贺！使用 .NET Aspire 和 Azure Developer CLI 管道成功部署了 Azure 项目。

清理资源

运行以下 Azure CLI 命令，在不再需要创建的 Azure 资源时删除资源组。删除资源组也会删除其中包含的资源。

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

有关详细信息，请参阅清理 Azure中的资源。

通过