使用 Aspire 每日构建（Daily Build）：CLI 安装、VS Code 扩展、项目创建与升级完整指南

使用 Aspire 每日构建（Daily Build）：CLI 安装、VS Code 扩展、项目创建与升级完整指南

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire

本篇技术指南面向希望抢先体验 Aspire 最新开发成果的开发者，完整讲解如何在本机安装每日构建（daily build，亦称 dev build）的 Aspire CLI、搭配 VS Code 扩展使用、通过aspire new向导创建使用每日通道（channel）的新项目，以及如何用aspire update将既有项目平滑迁移到每日构建。全文以仓库文档 docs/using-latest-daily.md 为核心骨架，并结合 src/Aspire.Cli 的源码实现，为你揭示通道选择、NuGet 源切换、项目更新的底层机制。

前提说明：如果你只想使用 Aspire 的官方正式发布版（stable），完全不需要阅读本文，直接使用官方文档即可；本文仅面向希望尝鲜每日构建的开发者。每日构建属于“不受支持（unsupported）”的构建，仅用于体验最新特性。

一、准备机器环境：先满足运行前提

在安装每日构建之前，需要先准备好机器环境。Aspire 的 AppHost 在开发阶段依赖容器运行时来承载各类集成资源（数据库、消息队列、缓存等），因此机器上必须先安装受支持的容器运行时，具体参见仓库文档 docs/machine-requirements.md。

• Docker Desktop：支持 Windows、macOS、Linux；
• Podman：同样支持 Windows、macOS、Linux 三大平台。

容器运行时就绪后，开发环境可以选择以下任一方式：

需要说明：上述部分链接为外部官方地址，实际安装细节以各工具官方文档为准。此外，若在 Alpine Linux 上构建 Aspire 仓库，还需要apk add --no-cache grpc-plugins并设置PROTOBUF_PROTOC、GRPC_PROTOC_PLUGIN环境变量，且 Alpine 目前仅直接支持 x64/amd64 架构，且不在 CI 测试套件覆盖范围内。

二、仅安装每日构建的 CLI

Aspire 提供了官方安装脚本，通过-Quality dev（PowerShell 中为-Quality dev，bash 中简写为-q dev）即可安装每日构建（dev build）版本的 CLI。

Windows（PowerShell）：

iex "& { $(irm https://aspire.dev/install.ps1) } -Quality dev"

Linux 或 macOS：

curl -sSL https://aspire.dev/install.sh | bash -s -- -q dev

从仓库中 eng/scripts/get-aspire-cli.ps1 的脚本注释可以看出，-Quality参数支持三种取值，其含义分别为：

• release：下载当前平台/架构的最新正式发布版；
• staging：下载最新的 staging 版本，若无 staging 版本则回退到 release 版本；
• dev：从main分支下载最新的 dev 构建（即每日构建）。

这与 eng/scripts/README.md 中记录的--quality/-q参数说明一致，默认值为release。

三、安装每日构建的 CLI + VS Code 扩展

Aspire 的 VS Code 扩展在运行时依赖 Aspire CLI 位于 PATH 中才能正常工作，因此推荐用安装脚本一次性装好两者。

Windows（PowerShell）：

iex "& { $(irm https://aspire.dev/install.ps1) } -InstallExtension -Quality dev"

Linux 或 macOS：

curl -sSL https://aspire.dev/install.sh | bash -s -- --install-extension -q dev

提示：如果要把 Aspire 扩展安装到 VS Code Insiders，请在 PowerShell 中追加-UseInsiders标志，或在 bash 中追加--use-insiders标志。

安装完成后，需要确保aspire命令所在的目录已加入PATH，否则 VS Code 扩展无法找到 CLI。

四、创建新项目：在向导中选择 daily 通道

每日构建 CLI 安装完成后，即可在命令行创建一个全新的 Aspire 项目：

aspire new

运行该命令会启动交互式向导。向导会要求输入项目名称、输出路径，并允许选择模板的通道（channel）。以下是文档中的典型交互过程：

Enter the project name (aspire-projects): dailybuild0 Enter the output path (./dailybuild0): ./dailybuild0 ✔ Using Redis Cache for caching. Select a template version: 9.4.1 (nuget.org) > daily stable (Type to search)

从上面的输出可以看到，向导会列出可用的模板版本来源：既可以是 nuget.org 上的正式发布版（如9.4.1），也可以是daily、stable等通道。选择daily后，项目将使用每日构建对应的模板与包版本。

向导背后的实现细节

从源码看，aspire new由 src/Aspire.Cli/Commands/NewCommand.cs 实现，它注册了--name/-n、--output/-o、--source/-s、--version、--channel、--language等选项。其中--channel选项的描述会根据当前 CLI 是否启用了 staging 通道而动态调整。

关键行为（可追溯到 src/Aspire.Cli/Commands/NewCommand.cs 附近的实现逻辑）：

• 未显式传--channel时，优先选择与当前运行 CLI 的身份通道（stable、staging、daily、local或pr-<N>）相匹配的通道，其次回退到 Implicit（nuget.org）通道；
• 通道名只有在确实需要被“钉住（pin）”时才会持久化到项目的aspire.config.json（例如local、daily、staging、pr-<N>；stable通道被刻意排除）；
• 选择每日构建通道后，CLI 会在项目目录生成NuGet.config，确保后续 restore 从正确的 NuGet feed 拉取包。

为什么 daily 通道需要生成 NuGet.config

在 src/Aspire.Cli/Packaging/PackageChannel.cs 中，ShouldPersistChannelName()与ShouldCreateNuGetConfig()两个方法揭示了设计意图：

• stable通道将所有 Aspire 包映射到 nuget.org —— 这本身就是 NuGet 的默认源，因此生成一份基于<clear/>的配置文件反而多余，还会清除用户已经配置的其他 feed；
• daily（dnceng/dotnet9）、staging（darc-pub-microsoft-aspire-<sha>）、pr-<N>/本地 hive 等通道都指向自定义 feed，这些通道的映射必须持久化到NuGet.config，否则 restore 会失败。

也就是说：哪些通道名会被钉住，哪些通道会生成 NuGet.config，这两个集合完全一致——即所有携带自定义 feed 映射的通道。

[!TIP]aspire new会自动更新本地的 aspire 模板，更新后的模板会立即可用于 Visual Studio 和dotnet new。这意味着即使你不通过 CLI 新建项目，也能够在 IDE 中以每日构建模板为基础创建项目。

五、更新既有项目到每日构建：aspire update

如果已经有一个 Aspire 项目（可能是之前用 stable 通道创建的），想把它升级到最新的每日构建，只需在项目目录下执行：

aspire update

该命令会把项目更新为使用 daily 通道的包与 feed。

[!TIP]aspire update可以在任意时刻使用，将项目升级到当前可用的最新 Aspire 构建，包括每日构建。

update 命令的完整选项

从 src/Aspire.Cli/Commands/UpdateCommand.cs 可以看到，aspire update除了无参数运行外，还支持以下选项：

通道的解析优先级

源码中 UpdateCommand.cs 明确注释了通道解析的优先级顺序：

1. 显式传入的--channel（或隐藏的--quality）；
2. 距离所选 AppHost 项目最近的本地aspire.config.json中的channel配置（注意：是相对于被解析的 AppHost 项目目录，而非当前工作目录）；
3. 全局配置中的channel（只读路径，仅当用户显式执行过aspire config set -g channel <x>时才生效）；
4. 当存在多个 hive（PR 构建目录）时，交互式提示选择通道；
5. 上述均不满足时，回退到 Implicit（默认）通道。

此外还有一个值得注意的细节：如果当前运行的是pr-<N>或daily身份的 CLI，且项目没有配置任何channel，update会默认采用运行中 CLI 自身的身份通道，从而避免项目被静默地降级到 nuget.org 的默认通道。

包更新完成后的迁移检查

aspire update在完成包更新后，还会检查是否有待执行的迁移（migration），例如apphost.ts迁移到apphost.mts这类文件层面的约定变更。行为见 UpdateCommand.cs 的HandlePendingMigrationsAsync：

• 默认（不带--migrate）时仅打印非阻塞的提示信息，列出待执行的迁移，并提示可运行aspire update --migrate应用它们；
• 传入--migrate时会先列出全部待迁移项，确认（或--yes跳过确认）后按序应用；单个迁移失败只会告警，不会让已经成功的包更新回滚为失败。

该迁移检测复用了与aspire doctor相同的IMigration注册表，因此未来新增的任何迁移都会自动在aspire update中呈现。

CLI 自更新：aspire update --self

aspire update --self用于更新 CLI 本身。从源码实现看（UpdateCommand.cs 与 ExecuteSelfUpdateAsync），不同安装方式的处理策略不同：

• 通过dotnet tool安装的 CLI：直接打印对应的包管理器更新命令（如dotnet tool update）而非就地覆盖；
• 通过全局 npm 安装的 CLI：同样委托给 npm 的更新命令，避免覆盖 npm 管理的文件；
• 通过 Nix 安装：打印nix profile upgrade aspire-cli/nix flake update <input-name>指引；
• 通过官方安装脚本安装的原生二进制：会下载指定通道（默认跟随运行 CLI 的身份通道，或交互选择）的最新归档，备份当前可执行文件后原地替换，并在更新后校验版本、提示PATH情况。

此外，在项目更新成功后，如果当前通道有更新的 CLI 可用，aspire update还会询问是否顺带更新 CLI（此行为可被--yes自动接受）。

六、运行更新后的项目

项目更新完成后，直接运行：

aspire run

aspire run会启动 AppHost，拉起编排的各个资源与依赖服务，并打开 Aspire Dashboard 供你观察分布式应用的日志、追踪与指标。如果项目是从 daily 通道创建的，aspire run会按NuGet.config中记录的每日构建 feed 还原包并运行，保证与 daily 包版本一致。

七、常见问题与注意事项

• daily 构建不受官方支持：文档明确说明 daily 是“最新但不受支持（unsupported）”的构建，生产项目请使用 stable 通道的正式发布版。
• VS Code 扩展依赖 PATH：扩展无法在aspire不在 PATH 时工作；安装后如遇扩展报错，先确认aspire --version是否可用。
• 升级路径安全：aspire update被定位为“恢复工具（recovery tool）”——即使 AppHost 钉住的Aspire.AppHost.Sdk已无法解析（例如从一个 PR 构建升级到另一个 PR 构建），它也能通过配置记录定位 AppHost 并重写钉住版本，见 UpdateCommand.cs 的注释说明。
• 非交互场景：在 CI 等非交互环境使用aspire update时，必须显式传入--yes（源码中的校验器会强制该要求），并用--channel显式指定通道，避免交互式提示阻塞。
• 多通道并存：同一台机器上可以通过 hive 机制并存多个 PR/每日构建，update在存在多个 hive 时会交互式询问目标通道。

八、深入阅读

如果想进一步了解 Aspire CLI 的通道与包管理机制，可以在本仓库中继续阅读：

• docs/machine-requirements.md：机器环境完整要求（容器运行时、IDE、Alpine 特殊说明）；
• src/Aspire.Cli/Commands/UpdateCommand.cs：aspire update的完整实现（通道解析、迁移、自更新）；
• src/Aspire.Cli/Commands/NewCommand.cs：aspire new的向导与通道选择逻辑；
• src/Aspire.Cli/Packaging/PackageChannel.cs：通道模型、NuGet.config 生成决策、包质量过滤（stable/prerelease）的实现；
• eng/scripts/get-aspire-cli.ps1 与 eng/scripts/README.md：CLI 下载脚本中release/staging/dev三种质量档位的说明；
• docs/specs/cli-identity-sidecar.md：CLI 身份通道与 sidecar 机制的设计规格。

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire