Aspire 应用改造评估清单aspireify Eval Rubric 深度解析与实战指南【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读本文围绕playground/aspireify-eval/EVAL-RUBRIC.md展开系统讲解 Aspire 仓库中用于评估aspireify技能AI Agent 自动将普通应用改造/迁移为 Aspire 应用的完整评分准则。文章覆盖两套典型评估应用——传统 .NET LOB 应用C# AppHost 全工程模式与多语言微服务应用TypeScript AppHost 单文件模式逐条拆解基础设施、AppHost 接线、依赖排序、ServiceDefaults、密钥迁移、可观测性与清理等评估维度并结合仓库源码与真实应用代码帮助开发者理解一次合格的 Aspirification应具备的全部技术要素。一、评估背景什么是 aspireify Evalaspireify-eval是 Aspire 仓库中用于评估aspireify技能的 Playground 应用集合。这些应用刻意保持未接入 Aspire的原始状态pre-aspirification其目标不是直接展示 Aspire 用法而是作为测试基准在应用目录中运行aspire init让 Agent 执行aspireify技能完成全自动改造再依据评估准则Rubric逐项打分验证 Agent 的改造质量。整个评估流程定义在 playground/aspireify-eval/README.md 中cd进入任一应用目录dotnet-traditional/或polyglot/运行aspire init让 Agent 执行aspireify技能依据 EVAL-RUBRIC.md 中的准则打分。一个关键设计约束是Rubric 文件不能放入评估应用目录内因为它包含了预期结果expected outcomesAgent 在评估过程中不应读取到它否则评估结果将失去意义。同理两个应用的 README 只描述改造前的手工运行方式绝不描述改造后的预期状态。Rubric 的评分模型为逐项 pass/fail每一条准则要么通过、要么不通过一次好的改造a good aspirification应当命中大多数条目。二、评估对象 1dotnet-traditional传统 .NET LOB 应用该应用目录为 playground/aspireify-eval/dotnet-traditional是一个带 Vue 前端的传统 .NET 业务系统BoardApp其架构见 dotnet-traditional/README.md如下frontend/ → Vue 3 Vite (port 5173)将 /api/* 代理到 BoardApi src/BoardApi/ → ASP.NET minimal API (port 5220)EF Core PostgresRedis 缓存 src/AdminDashboard/→ Blazor Server (port 5230)与 BoardApi 共享数据库 src/MigrationRunner/→ Worker 服务执行 EF Core 迁移后退出 src/BoardData/ → 类库共享 EF Core DbContext 与模型 BoardApp.slnx → 解决方案文件 .env → 全部配置数据库连接、Redis、API Key、密钥改造前所有配置都集中在根目录.env中包括DATABASE_URL、REDIS_URL、EXTERNAL_API_KEY、ADMIN_SECRET、FEATURE_ENABLE_NOTIFICATIONS五个变量。BoardApi通过Environment.GetEnvironmentVariable(DATABASE_URL)读取连接串见 BoardApi/Program.csAdminDashboard和MigrationRunner也采用同样的模式。改造前需要 4 个终端窗口 2 个基础设施服务Postgres、Redis 的 docker run才能手工跑起来——这正是 Aspire 要消除的痛点。2.1 基础设施必选aspire start能成功启动应用Postgres 作为 Aspire 托管容器运行Redis 作为 Aspire 托管容器运行所有服务出现在 Aspire Dashboard 中这一组准则验证改造后的应用能否一键启动不再手工docker runPostgres/Redis而是由 AppHost 以资源形式托管启动后所有服务Postgres、Redis、BoardApi、AdminDashboard、MigrationRunner、Frontend都应出现在 Dashboard 的资源列表中。2.2 AppHost 接线必选由于仓库中存在.slnx解决方案文件Agent 应识别为全工程模式full project mode创建*.AppHost/目录及其.csproj工程。随后对每个服务进行资源建模BoardApi→AddProject并引用 Postgres 数据库与 RedisAdminDashboard→AddProject引用 Postgres 数据库MigrationRunner→AddProject引用 Postgres 数据库Frontend→AddViteApp、AddNpmApp或类似 API 建模并引用 BoardApiBoardData 不做建模——它是类库而非可运行服务。这一条体现了 Aspire 资源建模的一个关键判断原则类库class library不是可运行资源不应被建模为项目。从仓库源码看AddProject会创建带启动能力的工作负载对应src/Aspire.Hosting/下对 project 资源的处理逻辑而类库不满足该前提。2.3 依赖排序必选依赖顺序是保证分布式应用正确启动的核心MigrationRunner 等待 PostgresWaitForBoardApi 等待 Postgres 与 RedisWaitForBoardApi 等待 MigrationRunner 完成WaitForCompletionAdminDashboard 等待 PostgresWaitForFrontend 等待 BoardApiWaitFor这里的两个 API 语义不同WaitFor表示等待资源就绪如容器健康检查通过WaitForCompletion表示等待资源运行完成并退出——这正是为 MigrationRunner 这类执行迁移后退出的一次性任务设计的。其底层实现位于 src/Aspire.Hosting/ApplicationModel/WaitAnnotation.csWait 注解的数据模型与 src/Aspire.Hosting/ResourceBuilderExtensions.csWaitFor/WaitForCompletion扩展方法。从源码结构看等待策略通过注解附加到资源上由编排层在启动时统一解析。MigrationRunner的实际行为印证了这一设计它运行await db.Database.EnsureCreatedAsync()并播种初始数据后打印 Migrations complete. 随即退出见 MigrationRunner/Program.cs因此后续服务必须等待它完成而非就绪。2.4 ServiceDefaults必选通过dotnet new aspire-servicedefaults创建 ServiceDefaults 工程ServiceDefaults 加入解决方案BoardApi、AdminDashboard、MigrationRunner 三个 .NET 服务引用 ServiceDefaults每个 .NET 服务的 Program.cs 中加入builder.AddServiceDefaults()在适用处加入app.MapDefaultEndpoints()ServiceDefaults 是 Aspire 为 .NET 服务提供的一站式默认配置工程模板集中封装了 OpenTelemetry、健康检查、服务发现等横切能力。Rubric 要求改造后三个 .NET 服务都通过项目引用接入它并在Program.cs中调用AddServiceDefaults()MapDefaultEndpoints()仅在适用场景使用——例如 BoardApi 这类暴露 HTTP 端点的服务。2.5 密钥与配置迁移必选这是从环境变量堆叠迈向Aspire 托管配置的关键DATABASE_URL被替换——Postgres 连接由 Aspire 通过WithReference管理REDIS_URL被替换——Redis 连接由 Aspire 通过WithReference管理EXTERNAL_API_KEY迁移为AddParameter(external-api-key, secret: true)ADMIN_SECRET迁移为AddParameter(admin-secret, secret: true)FEATURE_ENABLE_NOTIFICATIONS通过WithEnvironment或参数方式处理通过 Aspire 运行时不再需要.env文件其中AddParameter(..., secret: true)是 Aspire 管理密钥的标准方式参数资源在仪表盘中以密码框呈现、可挂接到用户机密user secrets或部署时的环境注入。其实现位于 src/Aspire.Hosting/ParameterResourceBuilderExtensions.cs。而WithReference则自动为引用方注入连接字符串或端点信息——例如 Postgres 资源被WithReference后BoardApi通过约定的配置键如ConnectionStrings:db读取连接串替代原来的DATABASE_URL环境变量。Rubric 还专门留有一条 nice-to-have改造过程中应向用户解释权衡例如把DATABASE_URL重命名为ConnectionStrings:db的含义体现可解释的自动化。2.6 开发体验优化可选加分项Postgres 容器使用持久化生命周期persistent lifetimeRedis 容器使用持久化生命周期为 Postgres 配置数据卷data volumesFrontend 配置WithExternalHttpEndpoints()向用户询问过权衡取舍如DATABASE_URL → ConnectionStrings:db重命名持久化生命周期保证aspire stop或aspire run重启后容器与数据卷不被销毁对数据库类资源尤为重要数据卷确保 Postgres 数据在容器重建后依然存在。WithExternalHttpEndpoints()让前端在开发环境外如容器/远程场景暴露可访问的 HTTP 端点。这些都属于提升体验的加分项不影响能跑通的底线。2.7 可观测性为 Vue 前端接入 OpenTelemetry或注明静态前端不适用.NET 服务通过 ServiceDefaults 自动获得 OTel对于 Vue 前端Agent 需要判断是否适合接入 OpenTelemetry纯静态前端可能不适用应如实注明而 .NET 服务则借助 ServiceDefaults 中的 OTel 配置自动获得追踪与指标无需逐个手工配置。2.8 清理Init 技能在完成后自移除self-removed确认常青Evergreenaspire技能仍然存在这组准则关注 Agent 技能的自我管理初始化完成后应移除一次性技能同时确认长期可用的aspire技能未被误删保证后续会话仍具备持续改造能力。三、评估对象 2polyglot多语言微服务应用第二个评估应用位于 playground/aspireify-eval/polyglot是一个 Python Go C# React 的多语言微服务应用CityServices其架构见 polyglot/README.md如下api-weather/ → Python FastAPI (port 8001)带 Redis 缓存的天气数据 api-geo/ → Go stdlib HTTP (port 8002)带外部 API Key 的地理编码桩服务 api-events/ → C# minimal API (port 8003)城市事件端点 frontend/ → React Vite (port 5173)直接调用三个后端 API .env → 全部配置Redis URL、API Keys没有解决方案文件、没有 AppHost——四个服务通过硬编码 URL 互相通信。React 前端在App.tsx中硬编码了http://localhost:8001/8002/8003见 polyglot/frontend/src/App.tsxapi-geo通过PORT环境变量决定监听端口见 polyglot/api-geo/main.goapi-weather则自行解析REDIS_URL拆分 host:port见 polyglot/api-weather/main.py。3.1 基础设施必选aspire start能成功启动应用Redis 作为 Aspire 托管容器运行所有服务出现在 Aspire Dashboard 中与 dotnet-traditional 相比该应用只有一个基础设施依赖Redis但同样要求托管化 Dashboard 可见。3.2 AppHost 接线必选由于没有.slnAgent 应采用单文件模式single-file mode使用单文件apphost.ts无.sln→ 不进入 project 模式在仓库根目录创建aspire.config.jsonapi-weather 建模AddPythonApp或类似引用 Redisapi-geo 建模可能为AddDockerfile或自定义HTTP 端点使用env: PORTapi-events 建模对 .csproj 使用AddProject含 HTTP 端点Frontend 建模AddViteApp或AddNpmApp引用全部后端服务Redis 使用addRedis类型化集成而非裸容器单文件模式与全工程模式的取舍由是否存在解决方案文件决定有.slnx走 C# AppHost 工程没有则走 TypeScriptapphost.ts单文件模式。aspire.config.json是 TypeScript AppHost 在仓库根目录的标识与配置入口。同时注意addRedis是类型化集成typed integration——它会自动提供约定的连接字符串与健康检查而不是简单地addContainer(redis)。3.3 依赖排序必选后端服务等待 RediswaitForFrontend 等待后端服务waitFor在 TypeScript AppHost 中使用小写驼峰 APIwaitFor、withReference与 C# AppHost 的WaitFor/WithReference对应。3.4 密钥与配置迁移必选REDIS_URL被替换——Redis 由 Aspire 通过withReference管理GEOCODING_API_KEY迁移为密钥参数WEATHER_API_KEY迁移为密钥参数OPENAI_API_KEY迁移为密钥参数通过 Aspire 运行时不再需要.env文件该应用的.env包含四个变量见 polyglot README 配置表其中三个外部 API Key 全部迁移为密钥参数。OPENAI_API_KEY被注释为保留给未来 advisor 功能说明即使当前未使用也应提前迁移为参数资源避免后续硬编码。3.5 服务间通信必选Frontend 获得后端 URL 注入而非硬编码 localhostGo 服务通过withHttpEndpoint({ env: PORT })注入 PORTPython 服务通过 Aspire 获得 Redis 连接而非硬编码 host:port向用户询问过权衡如前端 URL 注入方式这是多语言应用改造的独特难点withHttpEndpoint({ env: PORT })让 AppHost 为 api-geo 动态分配端口并通过PORT环境变量注入——Go 服务只需保持os.Getenv(PORT)的读取逻辑即可前端则通过注入的VITE_*环境变量或代理获得后端真实地址替换App.tsx中的硬编码 localhost。Python 的main.py中redis.Redis(hostredis_host, portint(redis_port))的分段解析逻辑也应由 Aspire 注入的REDIS_URL驱动而不是写死。3.6 开发体验优化可选加分项Redis 容器使用持久化生命周期为 Redis 配置数据卷Frontend 配置withExternalHttpEndpoints()建议或配置*.dev.localhost域*.dev.localhost域是 Aspire 的开发体验特性为前端提供稳定的本地域名如frontend.dev.localhost避免每次端口变化导致前端配置失效。3.7 可观测性建议为 Python 服务接入 OpenTelemetryfastapi OTLP exporter建议为 Go 服务接入 OpenTelemetryOTLP exporter修改服务代码接入 OTel 前先征求用户同意C# 服务获得 OTel 考量单工程场景可能不需要完整 ServiceDefaults多语言场景下 OTel 需要逐个语言适配PythonFastAPI OTLP、GoOTLP exporter、C#单工程场景可能只需最小配置而非整套 ServiceDefaults。同时 Rubric 特别强调在修改服务代码接入 OTel 之前必须征得用户同意——可观测性改造会侵入业务代码属于高影响变更应保持询问优先的 Agent 行为准则。3.8 包与配置准备必选根目录package.json为 apphost 配置type: module、start 脚本tsconfig.json为 apphost 编译配置aspire restore成功运行npm install成功运行TypeScript AppHost 的运行依赖 Node 工具链package.json需声明 ESMtype: module并提供启动脚本tsconfig.json负责 apphost.ts 的编译随后aspire restore恢复托管依赖、npm install安装前端依赖全部成功后才能aspire start。3.9 清理Init 技能在完成后自移除确认常青aspire技能仍然存在与 dotnet-traditional 应用相同作为评估收尾必须检查 Agent 技能生命周期管理是否干净。四、两大评估场景的技术要点对照评估维度dotnet-traditionalC# AppHost 全工程模式polyglotTypeScript AppHost 单文件模式判定依据存在.slnx→ 创建*.AppHost/工程无.sln→ 单文件apphost.tsaspire.config.json基础设施Postgres Redis 容器托管Redis 容器托管资源建模AddProject、AddViteApp/AddNpmAppAddPythonApp、AddDockerfile/自定义、AddProject、addRedis依赖排序WaitForWaitForCompletion迁移完成后才能启动下游waitFor配置迁移WithReference注入连接串AddParameter(secret: true)迁移密钥withReference三个 API Key 迁移为密钥参数服务通信前端代理 WithExternalHttpEndpointswithHttpEndpoint({ env: PORT })、前端 URL 注入可观测性.NET 服务经 ServiceDefaults 自动获得 OTel按语言分别建议 OTLP 接入改码前先征得同意工具链dotnet new aspire-servicedefaultspackage.jsontype: moduletsconfig.jsonaspire restorenpm install五、如何将 Rubric 落地为可验证的评估Rubric 中的每条 pass/fail 都可以对应到具体应用代码的检查点这里以两个应用的真实文件为例说明验证方式dotnet-traditional 应用BoardApi依赖 Postgres、Redis 与EXTERNAL_API_KEY对应源码中 BoardApi/Program.cs 的环境变量读取段——改造后这些读取点应被ConnectionStrings/注入配置替代MigrationRunner的迁移后退出语义对应 MigrationRunner/Program.cs 的Console.WriteLine(Migrations complete.)这决定了必须使用WaitForCompletion而非WaitForAdminDashboard与BoardApi共享BoardDbContext见 BoardData/Models.cs但 BoardData 本身只是类库不应建模为资源。polyglot 应用api-geo读取PORT与GEOCODING_API_KEY见 api-geo/main.go对应withHttpEndpoint({ env: PORT })与密钥参数api-weather解析REDIS_URL见 api-weather/main.py改造后该值应来自 Aspire 注入前端硬编码后端地址见 polyglot/frontend/src/App.tsx改造后应改为注入式获取。运行验证时aspire start成功后依次检查应用 README 中列出的验证端点如 BoardApi 的/api/health、/api/items、/api/cached-countCityServices 的/weather/seattle、/geocode/seattle、/events确认功能等价于改造前的手工运行方式随后在 Dashboard 中确认全部资源可见、依赖顺序正确、密钥参数以敏感字段形式呈现。六、总结EVAL-RUBRIC 的价值在于把一次合格的 Aspirification拆解成了可量化、可自动判定的检查项。它从基础设施托管化、资源建模完整性、依赖排序正确性、密钥与配置迁移、可观测性接入、开发体验优化、技能清理七个层面为aspireify这类 AI 改造技能定义了明确的验收标准同时也是一份面向人工改造者的极佳自查清单任何把传统 .NET 或多语言应用迁移到 Aspire 的工程都可以拿这份 Rubric 逐条核对确保改造结果既能跑must-have又好用nice-to-have且不丢失安全与可观测性底线。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
