升级 Aspire
更新: 2026-10-16 15:20:09 字数: 0 字 时长: 0 分钟
Aspire 迭代速度较快，包之间又需要版本对齐，因此「怎么升级」值得单独讲一讲。
两个 update 不要混淆
| 命令 | 作用 | 什么时候用 |
|---|---|---|
aspire update --self | 更新 Aspire CLI 自身。 | CLI 有新版本时。 |
aspire update | 更新项目中的 Aspire 包、模板与 SDK。 | 升级某个应用解决方案时。 |
bash
aspire --version # 先看当前版本
aspire update --self # 更新 CLI
cd ./MyApp
aspire update # 更新项目依赖aspire update --self 的行为差异
不同安装方式下行为不同：
| 安装方式 | 行为 |
|---|---|
| 安装脚本 / WinGet | 直接下载并替换二进制。 |
| npm | 打印 npm install -g @microsoft/aspire-cli@latest，由您执行。 |
| .NET 全局工具 | 打印对应的 dotnet tool update 命令。 |
| Nix | 打印 Nix 更新命令（Nix store 只读，无法原地替换）。 |
| Homebrew | 打印 brew upgrade 命令。 |
| mise | 打印 mise 更新命令。 |
aspire update 会做什么
- 检测过时的 Aspire 集成、模板与 SDK 版本。
- 按当前配置的发布渠道更新 SDK 与集成版本。
- 处理在代码中、
aspire.config.json中或集中式版本文件中声明的版本。
请整体升级
AppHost 包与客户端集成包必须版本一致。混搭版本常见症状是运行时找不到方法（MissingMethodException）或配置解析异常。
升级检查清单
- [ ]
aspire --version与项目依赖的 Aspire 版本是否匹配设计预期。 - [ ]
aspire update后执行dotnet build，确认没有因 API 变更导致的编译错误。 - [ ] 运行
dotnet test，确认集成测试仍然通过。 - [ ] 本地
aspire run跑一遍，确认仪表板、服务发现与健康检查正常。 - [ ] 检查标记为 Preview 的命令（
aspire deploy、aspire publish、aspire otel、aspire dashboard、aspire do）是否有行为变化。 - [ ] 更新 CI 中固定版本的地方（工具安装版本、镜像标签）。
版本渠道
Aspire 通过**渠道（channel）**管理版本来源。aspire update 会遵循当前配置的渠道。可以通过 CLI 配置查看与调整：
bash
aspire config list
aspire config set <key> <value>生产项目建议固定在稳定渠道
预览渠道能更早用上新特性，但也更容易遇到行为变更。生产项目请谨慎评估。
从其他编排方案迁移
从 Docker Compose 迁移
Aspire 提供了从 Docker Compose 迁移的路径：
bash
aspire init迁移建议循序渐进，先迁移后备服务，再迁移应用：
- 添加后备服务（PostgreSQL、Redis 等），用
WithImageTag()固定版本。 - 按需添加持久化存储，使用
WithDataVolume()。 - 把 .NET 应用转换为项目引用：用
AddProject<T>()替代build:指令，获得调试与热重载能力。 - 把 Dockerfile 构建的容器转换为
AddDockerfile()，对应原来的build:。 - 把预构建镜像转换为
AddContainer()，对应原来的image:。 - 用
WithReference表达依赖，替代depends_on；需要等待就绪时补上WaitFor。
不要一次全迁完
每次只迁移一个服务，保持应用始终可运行。Compose 文件与 AppHost 可以在一段时间内共存。
常见升级问题
升级后 builder.AddXxx 找不到
通常是因为只更新了 AppHost 包，没有同步更新客户端集成包，或反之。执行 aspire update 让版本对齐，然后重新还原依赖。
仪表板配置项不生效
不同版本的配置键可能有调整。请以当前版本的配置参考为准，并检查是否使用了正确的环境变量命名（: → __）。
原来的环境变量读不到了
请检查环境变量命名约定。特别是资源名中连字符与下划线的可移植编码规则——my-db 与 my_db 会映射到同一个物理变量名。
