必须用 dotnet new aspire 创建项目，而非手动拼装；aspire 核心是 distributedapplication 宿主模型，需通过 aspire run 启动 apphost 项目，依赖声明须按顺序、禁用字符串引用，敏感配置走 appsettings.json 或环境变量，调试和仪表板（http://localhost:18888）不可少。
直接上结论：用 dotnet new aspire 创建项目，不是 dotnet new webapi 加手动拼装 —— 后者根本绕不开配置地狱，也得不到 Aspire 的运行时服务编排和仪表板。
创建 Aspire 项目必须用 CLI 模板，不能从零手搭
很多人卡在第一步：以为先建一个 WebAPI，再 NuGet 引入 Microsoft.Extensions.Hosting 就算“接入 Aspire”。错。Aspire 的核心是 DistributedApplication 这个宿主模型，它要求整个解决方案从生成起就包含 AppHost 项目，并由 aspire run 启动。
-
dotnet new aspire -n MyOrderApp是唯一推荐的起点；dotnet new aspire-starter也行，但 starter 模板含 Blazor 前端，若只做后端微服务，选基础aspire更干净 - 生成后必须保留
MyOrderApp.AppHost项目，它不是“可有可无的胶水”，而是整个分布式应用的控制平面 - 不要在
.csproj里手动加PackageReference来“模拟” Aspire 功能 —— 比如自己引用Microsoft.Extensions.Caching.StackExchangeRedis，这会导致builder.AddRedis("redis")失效，因为 Aspire 的资源注册机制不认纯客户端包
AppHost.cs 里声明资源顺序影响依赖注入可用性
常见错误：builder.AddProject<projects.orderservice_api>("orderservice").WithReference(redis)</projects.orderservice_api> 报错说 redis 未定义。这不是语法错，是变量声明顺序问题。
- 所有
builder.Add*调用必须按“被依赖方先声明”原则排列：先var redis = builder.AddRedis("redis")，再var orderService = builder.AddProject<...>("orderservice").WithReference(redis)</...> - 不能把
WithReference()写成字符串名，比如.WithReference("redis")—— 这会跳过类型安全检查，运行时报Resource not found - 数据库连接字符串等敏感值，不要写死在
AppHost.cs里；Aspire 默认从AppHost项目的appsettings.Development.json或环境变量读取，优先级为：环境变量 > appsettings.json > 默认值
本地调试时 aspire run 和 dotnet run 完全不是一回事
开发者常误以为在 OrderService.Api 项目目录下执行 dotnet run 就能连上 Redis 和 Postgres —— 实际上，此时服务启动时找不到 ConnectionStrings:redis，因为 dotnet run 不触发 Aspire 的资源解析逻辑。
- 必须在
AppHost项目根目录下执行aspire run（或dotnet run，前提是当前目录是AppHost且项目 SDK 是Microsoft.NET.Sdk.Worker） -
aspire run会自动拉起 Docker Desktop（如果启用容器化资源），并注入所有WithReference()声明的连接字符串、端口、健康检查路径到子服务的IConfiguration - 断点调试仍可在 VS 或 VS Code 中正常设置，但需确保调试器附加的是由
aspire run启动的进程，而不是手动dotnet run启动的孤立进程
别忽略 Aspire Dashboard 的实时诊断价值
很多人跑通服务就关掉浏览器，其实 http://localhost:18888（默认地址）的仪表板才是 Aspire 区别于传统开发的关键。
- 它不是“额外功能”，而是随
aspire run自动启动的内置服务，显示每个资源的健康状态、日志流、OpenTelemetry 指标（如 HTTP 请求延迟、失败率） - 如果某个服务显示
Unhealthy，先看仪表板里的Logs标签页，通常第一行就是System.InvalidOperationException: Unable to resolve service for type '...' while attempting to activate '...'—— 这说明WithReference()没生效或连接字符串为空 - 仪表板中看到的连接字符串（如
redis://localhost:6379）是 Aspire 在运行时动态生成的，不是你代码里硬写的；改配置要改AppHost的appsettings.json，不是下游服务的配置文件
最易被忽略的一点：Aspire 的资源抽象（AddRedis、AddPostgres）在本地开发时默认走 Docker 容器，但部署到 Azure 时会自动切换为托管服务（如 Azure Cache for Redis）。这种“同一份 C# 代码，不同环境行为不同”的能力，依赖的是 Aspire 的延迟解析机制 —— 如果你在 AppHost.cs 里提前调用 .ConnectionString 或 .GetConnectionString()，就破坏了这个机制，导致部署失败。
