技能使用指南

dotnet-aspire（.NETAspire集成技能）Skill 是什么？如何下载安装并快速上手？

详解 .NETAspire集成技能Skill：一键分析 .NET 解决方案结构，自动生成 AppHost 与 ServiceDefaults 项目，配置服务发现、连接字符串与 OpenTelemetry 遥测。本文含安装前提、分步使用指南、竞品对比表、典型场景与常见问题，帮 .NET 团队快速落地云原生编排，立即上手提升开发效率。

.NETAspire集成技能Skilldotnet-aspire
8 个章节 约 18 分钟阅读 AI 智能生成

.NETAspire集成技能Skill：一键为 .NET 解决方案装上云原生编排与服务发现

  • 一句话定位：这是一个面向 .NET 开发者的 AI 专家技能，能把现有的 .NET 解决方案（API、Web 应用、后台工作者）自动改造为基于 .NET Aspire 的云原生分布式应用。
  • 核心动作：分析解决方案结构 → 识别服务与外部依赖 → 创建 AppHost 与 ServiceDefaults 项目 → 配置服务发现与 NuGet 包 → 生成本地可运行的编排代码。
  • 开箱即用：输出以代码为主，交付物是可直接 dotnet run 的编排配置与改造后的 Program.cs，而不是长篇说明文档。
  • 适合谁用：正在把单体/多项目解决方案迁移到微服务、想补齐可观测性与服务发现、或要从零搭建云就绪分布式应用的 .NET 团队。
  • 门槛提示：本地需 .NET 8.0 SDK 及以上、Aspire 工作负载与 Docker Desktop，否则仪表盘与容器资源无法启动（以官方说明为准）。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 .NETAspire集成技能Skill
技能英文名 dotnet-aspire
技能ID 12919
许可证 MIT
技能角色 专家（领域：基础设施，范围：实施）
输出格式 代码
触发词 Aspire、.NET Aspire、AppHost、ServiceDefaults、服务发现、云原生、分布式应用、编排、遥测、可观测性

它解决什么问题

在真实的 .NET 项目里，要把一个"多项目解决方案"变成"可观测、可编排的分布式应用"，通常要踩这些坑：手工新建 AppHost 项目却不知道怎么组织资源依赖；每个服务都要重复写 OpenTelemetry、健康检查、服务发现的样板代码；HttpClient 里到处是 https://localhost:7001 这类硬编码地址；连接字符串散落在各服务的配置文件里。这个技能就是把这些"知道要做但每次都要重来一遍"的工程动作，变成一套可复用、可分步执行的实施路径。

一键安装的思路与步骤

第一步：准备环境前提（技能明确要求）。安装 .NET 8.0 SDK 或更高版本；安装 Aspire 工作负载；准备 Docker Desktop 用于容器资源。

# 安装 .NET Aspire 工作负载
dotnet workload install aspire

# 验证安装，应显示 "aspire"
dotnet workload list

第二步：在 AI 技能平台/插件市场中检索技能。可使用技能英文名 dotnet-aspire、中文名「.NETAspire集成技能Skill」或技能ID 进行搜索，找到后点击安装/启用。具体的市场入口、安装命令与是否需要授权，以官方说明为准。

第三步：在对话中触发技能。安装后，在支持该技能的环境中提出需求，例如"帮我给这个 .NET 解决方案添加 Aspire 编排"，或直接命中触发词（Aspire、AppHost、ServiceDefaults 等），技能即被激活。

第四步：验证是否生效。观察回答是否包含"分析解决方案 → 创建 AppHost/ServiceDefaults → 配置服务发现 → 添加 NuGet 包 → 运行验证"这一完整链路；落地验证则以 dotnet workload list 中出现 aspire、以及 dotnet run --project xxx.AppHost 能打开开发者仪表盘为准。

该技能的主要功能和特点

  • 解决方案结构分析：先识别解决方案里有哪些服务（API、Web 应用、工作者），列出外部依赖（数据库、Redis、消息队列），确定服务间通信模式，再决定编排范围——而不是上来就套模板。
  • 自动生成两类核心项目：AppHost（负责编排与提供开发者仪表盘）与 ServiceDefaults（负责 OpenTelemetry、健康检查、服务发现的共享配置），并按 [解决方案名称].AppHost 的惯例命名。
  • 编排代码生成：输出 DistributedApplication.CreateBuilder(args) 形式的组合代码，涵盖 AddRedis、AddPostgres().AddDatabase()、AddSqlServer、AddRabbitMQ、AddMongoDB、AddAzureStorage 等资源声明，以及 WithReference、WithExternalHttpEndpoints、WithReplicas、WithEnvironment 等服务配置方法。
  • 服务发现改造：把硬编码的 https://localhost:7001 替换为基于服务名的 http://api，由 Aspire 接管路由与连接。
  • 连接字符串自动注入：引导使用 builder.AddNpgsqlDbContext<AppDbContext>("appdb")、builder.AddRedisClient("cache") 等组件方法，替代手工读配置。
  • 典型架构模板：内置"Web API + 前端"“带消息队列的微服务”“多数据库系统”“API 网关模式”"带消息队列的工作者"等可直接照抄的组合范式。
  • 故障排查清单：针对"服务无法通信"“连接字符串未注入”“仪表盘无法启动”"健康检查失败"等高频问题给出定位路径。
  • 与普通"问答式 AI"的差异：普通 AI 往往只给一段泛泛的 Aspire 示例代码；这个技能有明确的实施范围（实施类、代码输出）、分步流程、待修改文件清单与验收清单，产物更接近"能直接合并进仓库"的改造方案。

如何使用该技能？

步骤 1：描述你的解决方案现状

给出解决方案名、项目清单、外部依赖与调用关系。示例输入：

“我的解决方案叫 ECommerceSystem，包含 OrderApi、InventoryWorker、Web 三个项目，使用 PostgreSQL 和 Redis，Web 通过 HttpClient 调用 OrderApi，地址写死为 https://localhost:7001。帮我接入 .NET Aspire。”

步骤 2：确认技能给出的澄清问题

技能会先确认：识别出的服务是否全部纳入编排、哪些资源由 Aspire 托管（容器还是连接字符串）、AppHost/ServiceDefaults 的命名偏好、服务间依赖与启动顺序。这一步建议如实回答，命名一旦确定会贯穿服务发现地址。

步骤 3：按输出创建两个 Aspire 项目

dotnet new aspire-apphost -n ECommerceSystem.AppHost
dotnet new aspire-servicedefaults -n ECommerceSystem.ServiceDefaults
dotnet sln add ECommerceSystem.AppHost/ECommerceSystem.AppHost.csproj
dotnet sln add ECommerceSystem.ServiceDefaults/ECommerceSystem.ServiceDefaults.csproj

步骤 4：为每个服务接入 ServiceDefaults

dotnet add ECommerceSystem.OrderApi reference ECommerceSystem.ServiceDefaults/ECommerceSystem.ServiceDefaults.csproj

并在各服务 Program.cs 中注册与映射：

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();   // 新增

var app = builder.Build();
app.MapDefaultEndpoints();      // 新增，放在 app.Run() 之前
app.Run();

后台工作者服务则使用 Host.CreateApplicationBuilder(args) 加 builder.AddServiceDefaults()。

步骤 5：在 AppHost 中完成编排

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");
var database = builder.AddPostgres("postgres").AddDatabase("appdb");

var api = builder.AddProject<Projects.OrderApi>("orderapi")
    .WithReference(database)
    .WithReference(cache);

var web = builder.AddProject<Projects.Web>("web")
    .WithReference(api)
    .WithExternalHttpEndpoints();

builder.Build().Run();

步骤 6：改造服务通信与数据访问

HttpClient 基址从 https://localhost:7001 改为 http://orderapi（名称与 AddProject<> 中的名称一致）；数据库访问从手工 UseNpgsql(Configuration.GetConnectionString(...)) 改为 builder.AddNpgsqlDbContext<AppDbContext>("appdb")；Redis 使用 builder.AddRedisClient("cache")。

步骤 7：运行与验收

dotnet run --project ECommerceSystem.AppHost
# 打开开发者仪表盘（默认 https://localhost:15001）

预期输出效果：仪表盘列出所有服务与资源容器并显示健康状态，跨服务调用产生分布式追踪遥测，订单 API 能正确连上 PostgreSQL 与 Redis。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
.NETAspire集成技能Skill（dotnet-aspire） AI 专家技能，指导并生成 Aspire 改造代码 结构分析、AppHost/ServiceDefaults 生成、服务发现改造、组件与部署指导 需 .NET 8 SDK、aspire 工作负载、Docker；技能本身在技能市场一键安装 存量 .NET 解决方案快速接入 Aspire、从零搭建云就绪分布式应用 优势：流程完整、带澄清问题与验收清单、输出可直接落地的代码；不足：仍需要开发者理解 Aspire 概念并逐项验证，不能替代真实联调
手动安装 .NET Aspire（官方文档 + 模板） 官方框架能力本身 编排、服务发现、遥测、仪表盘 需自行阅读文档、手工建项目并逐服务改造 有经验团队、定制化极强的项目 优势：完全可控、无中间层；不足：样板代码多、跨服务改造易漏项、排错靠经验
Docker Compose + 手工 OpenTelemetry 通用容器编排方案 容器编排、网络互通、日志收集 需写 Compose 文件并自建 OTel 采集链路 跨语言混合技术栈、简单容器化部署 优势：语言无关、生态成熟；不足：.NET 侧服务发现与遥测需自行接线，本地调试体验与仪表盘不可比
Microsoft Tye（历史实验项目） 早期 .NET 本地编排工具 本地一键启动多服务、简易仪表盘 需额外安装工具，社区维护已停滞 老项目的历史方案 优势：上手简单；不足：已被 Aspire 取代，缺少云原生组件与生产部署路径，不建议新项目采用

该技能的典型应用场景与实际体验情况

场景一：单体多项目解决方案的微服务化改造

角色：中小团队的 .NET 后端负责人。痛点是解决方案里 3~5 个项目互相写死端口，本地要手动开三个终端分别启动。使用技能后，按澄清问题确认服务清单，生成 AppHost 一次拉起全部服务，HttpClient 基址全部改为服务名。实际体验：上手难度中等，最大的收益是"漏改"变少了——技能的验收清单会逐条提醒每个服务的 AddServiceDefaults() 与 MapDefaultEndpoints() 是否补齐。注意点是资源名称必须与 AppHost、服务配置三处一致，否则连接字符串注入会静默失败。

场景二：新项目从零搭建云就绪分布式应用

角色：创业公司技术负责人。痛点是希望一开始就具备可观测性，但不想在 OpenTelemetry 接线上耗费一周。使用技能直接套用"Web API + 前端"或"带消息队列的微服务"范式，ServiceDefaults 一次性配好日志、指标、分布式追踪。实际体验：效果最直接，仪表盘能立刻看到跨服务调用链；注意提前安装 Docker Desktop，否则 Redis、PostgreSQL 等容器资源起不来，仪表盘会卡在启动阶段。

场景三：本地调试与生产部署的衔接准备

角色：DevOps 工程师。痛点是开发环境和生产环境的配置方式割裂。技能会区分开发态（appsettings.Development.json、.WithEnvironment()、用户机密）与生产态（Azure Key Vault 或托管机密、azd 自动配置 Azure 资源），并给出 Azure 容器应用、Kubernetes、Docker Compose 的部署方向。实际体验：这一部分更偏"路线图"而非"一键完成"，具体部署仍需按官方文档执行；但把机密不进源码、连接字符串自动注入这些规则前置，能显著减少后期的返工。

场景四：多数据库系统的统一编排

角色：平台架构师。痛点是用户库在 PostgreSQL、订单库在 MongoDB，本地要同时起两套容器并记住各自的端口。技能给出 AddPostgres("postgres").AddDatabase("users").AddDatabase("products") 与 AddMongoDB("mongo").AddDatabase("orders") 的组合方式，再用 WithReference 分别注入到对应服务。实际体验：结构清晰、可读性高；注意为数据库加 .WithDataVolume() 做持久化，否则重启后数据丢失会浪费时间重灌。

该技能能为用户带来的价值

  • 把"框架知识"变成"实施路径"：Aspire 的文档很全，但"我的解决方案该怎么改"这一步最耗时。技能把分析、建项目、改代码、验收串成一条链，开发者照单执行即可。
  • 显著压缩样板代码时间：服务发现、OpenTelemetry、健康检查的横切配置集中在 ServiceDefaults 一处，每个服务只需两行调用，新增服务时的边际成本接近零。
  • 降低云原生门槛：对于没接触过分布式追踪、服务发现的中级开发者，通过"照抄可运行代码 + 澄清问题"的方式理解概念，学习曲线被摊平。
  • 减少隐蔽缺陷：硬编码 URL、连接字符串手写、机密进源码这三类是分布式 .NET 项目的高频事故源，技能在实施步骤与最佳实践中逐条对齐，从源头规避。
  • 长期收益：编排代码即架构文档。AppHost 中的资源与服务依赖关系，就是团队理解系统拓扑的最短路径；仪表盘 + 分布式追踪则让线上问题定位从"翻日志"变为"看链路"。

常见问题 FAQ

Q1：这个技能怎么安装？收费吗？

技能本体通过 AI 技能平台/插件市场检索 dotnet-aspire 或技能中文名安装，具体入口与是否收费以官方说明为准。需要注意，技能所依赖的 .NET Aspire 工作负载本身采用 MIT 许可证免费，但本地必须自行安装 .NET 8.0 SDK 及以上版本与 Docker Desktop。

Q2：安装完技能就能直接跑起来吗？还需要做什么？

不能直接跑。技能输出的是改造方案与代码，落地仍需三步环境准备：dotnet workload install aspire 安装工作负载、启动 Docker Desktop、并在 AppHost 项目中 dotnet run。建议先用技能提供的入门清单逐条打勾，再交付测试。

Q3：它是只支持新项目，还是能改造已有解决方案？

两者都支持，但重心在"存量改造"。技能的定位就是"为现有 .NET 解决方案添加 .NET Aspire 云原生编排"，会先分析解决方案结构、识别服务与外部依赖，再决定编排范围；同时也能用于创建新的 Aspire 支持的分布式应用程序。

Q4：和直接看官方文档、或者用 Docker Compose 相比，怎么选？

如果你的技术栈是纯 .NET 且希望同时获得服务发现、可观测性和本地仪表盘，优先选这个技能配合 Aspire；如果是跨语言混合栈、只需要容器编排，Docker Compose 更合适；如果团队已经非常熟悉 Aspire，直接看官方文档即可，技能的价值主要在"少漏项、少走弯路"。已被 Aspire 取代的历史工具（如 Tye）不建议在新项目中采用。

Q5：运行后仪表盘打不开怎么办？

按技能给出的排查路径走：确认运行的是 AppHost 项目而不是单个服务；确认 Docker Desktop 正在运行；检查默认端口 15001 是否被占用；查看 AppHost 控制台输出中的实际仪表盘地址；若资源启动失败，检查本地端口冲突与 Docker 资源是否充足。