Aspire 9.1 新特性全解析：Dashboard 增强、本地开发改进与 Azure 集成升级

Aspire 9.1 新特性全解析Dashboard 增强、本地开发改进与 Azure 集成升级【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire本文基于仓库内官方发布说明 tools/ReleaseNotes/data/whats-new-91.md 整理撰写并结合 Aspire 仓库源码src/、tests/进行验证与深度展开。版本定位同时支持 .NET 8 与 .NET 9Aspire 9.1 是 Aspire 的下一个次版本minor发布与主版本对齐 .NET 大版本不同次版本发布频率更高、脱离 .NET 发布节奏独立发布。9.1 的核心价值在于同时支持两种运行时.NET 8.0 Long Term Support (LTS).NET 9.0 Standard Term Support (STS)也就是说无论你当前项目基于 .NET 8 还是 .NET 9都可以直接升级到 Aspire 9.1无需强制迁移运行时。这一特性极大降低了升级门槛。本版本的开发主题被官方概括为polish, polish, polish打磨、打磨、再打磨——即全平台范围内的质量与体验改进而非单一的杀手级功能。几个代表性亮点包括Dashboard 中的**资源关系resource relationships**展示对GitHub Codespaces的一等支持将资源以 **Dockerfile 形式发布publish as Dockerfile**的能力升级到 Aspire 9.1在次版本之间迁移非常简单只需三步第一步更新 AppHost 项目文件中的 SDK 版本在应用宿主项目文件如MyApp.AppHost.csproj中将 Aspire.AppHost.Sdk 更新为9.1.0Project SdkMicrosoft.NET.Sdk Sdk NameAspire.AppHost.Sdk Version9.1.0 / !-- 其余内容省略 -- /Project第二步更新 NuGet 包检查并更新所有相关 NuGet 包可使用 Visual Studio 的 NuGet 包管理器或 VS Code 中的Update NuGet Package命令。第三步更新 Aspire 模板运行以下 .NET CLI 命令更新所有已安装模板dotnet new update注意dotnet new update会将你的全部模板更新到最新版本。如果你的 AppHost 项目文件中还没有Aspire.AppHost.Sdk引用说明你可能仍在使用 Aspire 8需要先完成 8 → 9 的升级路径再执行上述 9.1 升级。改进的入门体验Codespaces 与 Dev ContainersAspire 9.1 针对新用户首次接触项目的痛点做了专门优化。团队创建了GitHub Codespaces 模板可自动安装 Aspire 所需的全部依赖——包括 Aspire 模板和 ASP.NET Core 开发证书让用户打开浏览器即可开始开发。同时新增了对Visual Studio Code Dev Containers的支持方便你在容器化开发环境中使用 Aspire。这两项能力面向同一目标将环境搭建从手动步骤清单压缩为一键启动。Dashboard 增强与自定义Dashboard 是 Aspire 开发体验的核心界面。9.1 版本为它带来了多项新能力资源关系Parent/ChildDashboard 的Resource资源页面现在支持父-子资源关系展示。典型场景当你创建一个 Postgres 实例并挂载多个数据库时这些数据库会嵌套显示在该实例下方资源的组织结构一目了然。例如AddPostgres后通过AddDatabase创建的多个数据库会以层级结构呈现。本地化覆盖Localization Overrides此前 Dashboard 的语言跟随浏览器设置。9.1 引入了语言下拉菜单允许用户独立于浏览器语言切换 Dashboard 显示语言——例如浏览器为英文但希望 Dashboard 显示中文现在可以分别控制。清除日志与遥测数据Console logs控制台日志、Structured logs结构化日志、Traces追踪和Metrics指标页面都新增了清除数据按钮设置弹窗中还有Remove all按钮一键清空全部数据。这使得开发者可以清空 Dashboard 至空白状态运行测试你的应用仅查看本次运行产生的相关日志与遥测循环往复。新的筛选功能Resource页面新增三种筛选维度Resource type资源类型State状态Health state健康状态更多资源详情在 Dashboard 中选中某个资源后详情面板现在展示更多数据点包括References引用——该资源引用了哪些其他资源Back references反向引用——哪些资源引用了该资源Volumes卷及其挂载类型mount types这让开发者无需翻阅代码即可快速理解资源的依赖关系全貌。CORS 支持自定义本地域名新增环境变量ASPIRE_DASHBOARD_CORS_ALLOWED_ORIGINS用于允许 Dashboard 接收来自其他浏览器应用的遥测数据——典型场景是资源运行在自定义 localhost 域名上时浏览器端的遥测上报会被 CORS 拦截此变量可配置允许的来源列表解除限制。控制台日志的灵活性Console logs 页面新增两个选项下载日志将日志导出到本地用自己熟悉的诊断工具分析时间戳开关按需显示或隐藏时间戳减少视觉杂乱。其他 UX 改进资源命令如Start/Stop按钮现在也出现在Console logs页面无需切回资源页即可控制资源启停单击即可在文本可视化器text visualizer中打开内容日志中的URL 自动可点击且端点中的逗号被自动移除切换不同资源时滚动位置自动重置避免视图错位。本地开发体验增强9.1 在本地开发方面投入了大量精力以下是关键改进按需启动资源WithExplicitStart通过WithExplicitStart()扩展方法可以让指定资源不随应用宿主一起自动启动而是在需要时从 Dashboard 内手动启动。这在数据库清理工具一次性初始化任务等场景非常有用。仓库源码验证该方法定义在 src/Aspire.Hosting/ResourceBuilderExtensions.cs实现为向资源附加一个ExplicitStartupAnnotation[AspireExport] public static IResourceBuilderT WithExplicitStartT(this IResourceBuilderT builder) where T : IResource { return builder.WithAnnotation(new ExplicitStartupAnnotation()); }其注释文档中给出的典型示例是数据库清理工具项目不随 app host 启动稍后通过资源启动命令按需运行var builder DistributedApplication.CreateBuilder(args); var pgsql builder.AddPostgres(postgres); builder.AddProjectProjects.CleanUpDatabase(dbcleanuptool) .WithReference(pgsql) .WithExplicitStart();ExplicitStartupAnnotation定义于 src/Aspire.Hosting/ApplicationModel/ExplicitStartupAnnotation.cs是一个空的标记注解运行时由 DCP 侧消费在 src/Aspire.Hosting/Dcp/ExecutableCreator.cs 和 src/Aspire.Hosting/Dcp/ContainerCreator.cs 中检测到该注解时不会在启动阶段自动创建/启动对应进程或容器。更好的 Docker 集成PublishAsDockerfile()PublishAsDockerfile()功能现在覆盖所有项目Project资源和可执行Executable资源允许在发布过程中完全自定义 Docker 容器与 Dockerfile。虽然该 API 在之前版本已存在但当时无法用于ProjectResource或ExecutableResource类型9.1 补上了这一缺口。从源码看src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs 中的PublishAsDockerfile在发布模式下将ProjectResource从应用模型中移除替换为等价命名的ContainerResourceProjectContainerResource并自动以项目目录为构建上下文context配置 Dockerfile清空原可执行参数因为其中常含容器内无效的物理路径将 http/https 端点的目标端口默认设为 8080与 ASP.NET 基础镜像端口一致支持可选的configure回调进一步定制容器资源。对应的 src/Aspire.Hosting/ExecutableResourceBuilderExtensions.cs 为ExecutableResource提供了三个重载无参数、带DockerBuildArg构建参数、带容器配置回调。仓库测试 tests/Aspire.Hosting.Tests/PublishAsDockerfileTests.cs 验证了该行为例如对 JavaScript 应用调用.PublishAsDockerFile()后应用模型中会出现同名ContainerResource且生成的发布清单为{ type: container.v1, build: { context: ., dockerfile: Dockerfile }, env: { NODE_ENV: development } }带buildArgs的版本则会在build节点下生成args字典布尔值与数字会序列化为字符串无值参数为null。清理 Docker 网络9.1 修复了一个长期困扰开发者的问题Aspire 创建的 Docker 网络在应用停止后仍然残留对应 Aspire GitHub issue #6504。现在 Docker 网络会在应用停止后得到妥善清理开发环境更加整洁、资源不泄漏。Socket 地址问题修复多个用户反馈重启 Aspire 应用宿主时出现问题包括协调错误reconciliation errors和 address already in use 报错对应 issue #6693、#6704、#7095。9.1 引入了更健壮的 socket 地址管理方式确保同一时刻每个地址只被一个实例使用同时改进了项目重启与资源释放流程避免挂起hanging问题显著提升了开发与测试期间应用宿主的稳定性。集成更新Azure 集成改进新增模拟器Emulators9.1 为三个 Azure 集成带来了新的本地模拟器方便离线开发var serviceBus builder.AddAzureServiceBus(servicebus) .RunAsEmulator(); #pragma warning disable ASPIRECOSMOSDB001 var cosmosDb builder.AddAzureCosmosDB(cosmosdb) .RunAsPreviewEmulator(); var signalr builder.AddAzureSignalR(signalr, AzureSignalRServiceMode.Serverless) .RunAsEmulator();Azure Service Bus新增模拟器支持Azure Cosmos DB新增基于 Linux 的模拟器预览Azure SignalR新增模拟器支持它们与此前已有的模拟器Azure Storage、Azure Event Hubs、Azure Cosmos DB并列工作覆盖了主流 Azure 消息与存储服务的本地开发需求。Cosmos DB 相关新能力默认支持 Entra ID 认证此前 Cosmos DB 集成使用访问密钥access key加 Key Vault 密钥连接服务9.1 起默认改用更安全的托管标识managed identities认证。若仍需访问密钥认证可调用WithAccessKeyAuthentication()恢复旧行为。在 app host 中建模数据库与容器现在可以直接在 app host 代码中定义 Cosmos DB 数据库和容器应用在模拟器与 Azure 中运行时这些资源都已就绪。这解决了此前应用自身可能没有创建权限却需要自建资源的痛点var cosmosDb builder.AddAzureCosmosDB(cosmosdb) .RunAsEmulator(); var database cosmosDb.AddCosmosDatabase(mydatabase); database.AddContainer(mycontainer, /id);支持 Azure Functions 的 Cosmos DB 触发器AzureCosmosDBResource被改造为支持 Azure Functions 应用中的 Cosmos DB 触发器消费。Cosmos DB 资源可初始化后作为引用加入 Functions 资源var funcApp builder.AddAzureFunctionsProjectProjects.AzureFunctionsEndToEnd_Functions(funcapp) .WithReference(cosmosDb) .WaitFor(cosmosDb);在 Functions 函数中即可直接使用[CosmosDBTrigger]public class MyCosmosDbTrigger(ILoggerMyCosmosDbTrigger logger) { [Function(nameof(MyCosmosDbTrigger))] public void Run([CosmosDBTrigger( databaseName: mydatabase, containerName: mycontainer, CreateLeaseContainerIfNotExists true, Connection cosmosdb)] IReadOnlyListDocument input) { logger.LogInformation( C# cosmosdb trigger function processed: {Count} messages, input.Count); } }Service Bus 与 Event Hubs与 Cosmos DB 类似Service Bus 和 Event Hubs 集成现在允许直接在 app host 代码中定义Service Bus 的队列queues、主题topics、订阅subscriptionsEvent Hubs 的实例instances与消费组consumer groups这简化了应用逻辑这些资源的创建与管理被移到应用外部应用只负责消费。连接现有 Azure 资源9.1 让连接已有 Azure 资源变得非常容易支持两种方式直接使用string名称或使用**应用模型参数app model parameters**在部署时动态替换。例如连接现有 Service Bus 账户var existingServiceBusName builder.AddParameter(serviceBusName); var existingServiceBusResourceGroup builder.AddParameter(serviceBusResourceGroup); var serviceBus builder.AddAzureServiceBus(messaging) .AsExisting(existingServiceBusName, existingServiceBusResourceGroup);上述代码从参数中读取名称与资源组在应用运行或部署时连接现有资源——参数可在部署时注入无需修改代码。源码侧对应实现位于 src/Aspire.Hosting.Azure/ExistingAzureResourceExtensions.cs提供RunAsExisting/AsExisting系列扩展其底层通过 src/Aspire.Hosting.Azure/AzureProvisioningResource.cs 的AddAsExistingResource机制将资源标记为引用现有基础设施从而跳过资源创建。Azure Container Apps 自定义域名实验性新增对 Azure Container AppsACA配置自定义域名的实验性支持#pragma warning disable ASPIREACADOMAINS001 var customDomain builder.AddParameter(customDomain); var certificateName builder.AddParameter(certificateName); builder.AddProjectProjects.AzureContainerApps_ApiService(api) .WithExternalHttpEndpoints() .PublishAsAzureContainerApp((infra, app) { app.ConfigureCustomDomain(customDomain, certificateName); });域名与证书名称均通过参数注入便于在不同环境复用同一份代码。更多集成更新OpenAI新增对 Microsoft.Extensions.AI NuGet 包的支持RabbitMQ 7 / MongoDB 3两者升级到新主版本并引入破坏性变更因此发布了带版本后缀的新包Aspire.RabbitMQ.Client.v7、Aspire.MongoDB.Driver.v3原包继续使用旧版本避免强制升级Dapr迁移至 CommunityToolkit 维护以加快创新速度AWSAspire.Hosting.AWS包与源码已迁移至 AWS 组织名下该变更实际发生在 9.09.1 中再次声明此外还有大量其他集成获得更新、修复与新特性。测试能力增强Aspire 9.1 简化了跨功能集成测试的编写方式。应用宿主允许在测试运行中无缝创建、评估和管理容器化环境并支持 xUnit、NUnit、MSTest 等主流测试框架。新增能力包括禁用端口随机化disable port randomization——解决固定端口场景下的测试需求启用 Dashboard——测试过程中可视化查看运行状态向 app host 传递参数Pass arguments to your app host——更灵活地控制测试环境。这些增强部分源于稳定性问题反馈例如 issue #6678某些资源因 address in use 错误启动失败。通过测试时禁用端口随机化等方式可有效规避此类问题。部署npm 应用到 Azure Container Apps9.1 对 ACA 部署流程做了显著改进同时增强了azdCLI 与 app host 两侧的部署选项。其中呼声最高的需求——支持将npm应用部署到 ACA——已在此版本实现。npm 应用现在可以像其他资源一样部署到 Azure Container Apps为前端应用接入 Aspire 全栈部署提供了统一路径。破坏性变更Aspire 演进很快随之而来的是破坏性变更。官方将破坏性变更分为三类类别含义你需要做什么二进制不兼容Binary incompatible程序集版本已变更需要重新编译你的代码源码不兼容Source incompatible源码已变更需要修改你的代码行为变更Behavioral change代码行为发生变化需要修改你的代码通常 API 会标注[Obsolete]特性在编译时给出警告为你留出调整代码的时间窗口。小结Aspire 9.1 是典型的细节制胜版本Dashboard 的可视化层级与可操作性显著增强WithExplicitStart与PublishAsDockerfile补齐了本地开发与发布流程的灵活性Azure 集成在认证安全Entra ID 默认、资源建模数据库/容器/队列在 app host 中声明与现有资源接入方面全面深化同时修复了 Docker 网络残留与 socket 地址冲突等稳定性顽疾。对于同时使用 .NET 8 与 .NET 9 的团队9.1 提供了一个平滑、低风险的升级目标。本仓库中还可进一步深入阅读的相关资料tools/ReleaseNotes/data/whats-new-91.md本文章所依据的官方发布说明原文src/Aspire.Hosting/ResourceBuilderExtensions.csWithExplicitStart、WaitForCompletion等资源编排扩展实现src/Aspire.Hosting/ApplicationModel/ExplicitStartupAnnotation.cs显式启动注解定义src/Aspire.Hosting/ProjectResourceBuilderExtensions.cs 与 src/Aspire.Hosting/ExecutableResourceBuilderExtensions.csPublishAsDockerFile系列实现src/Aspire.Hosting.Azure/ExistingAzureResourceExtensions.cs连接现有 Azure 资源的扩展实现tests/Aspire.Hosting.Tests/PublishAsDockerfileTests.csDockerfile 发布行为的测试验证docs/contributing.md贡献者指南若你希望参与 Aspire 的开发【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考