企业官网建设流程全解析

在 VS Code 中使用 Aspire 扩展创建第一个 Aspire 应用：AppHost、资源与依赖编排实战指南

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire

本指南以 Aspire 官方 VS Code 扩展的 "Create your first Aspire app" 入门文档为骨架，结合当前仓库中 VS Code 扩展源码、Aspire CLI 与项目模板实现，完整讲解如何从零创建第一个 Aspire 应用：选择 Starter 模板或空 AppHost、理解 AppHost 这一"应用地图"中资源（Resources）、连接（Connections）与启动顺序（Startup order）三大核心概念，并最终运行起来。读完本文，你将掌握通过 VS Code 命令面板创建 Aspire 项目的完整流程，并能读懂 AppHost 中的声明式编排代码。

从零开始：选择 Starter 还是空 AppHost

Aspire 扩展提供的入门体验非常直接：要么为你的技术栈选择一个 Starter 模板，要么从一个空的 AppHost 开始。无论走哪条路，入口都是同一个 VS Code 命令——aspire-vscode.new（对应命令面板中的 "Aspire: New Project"）。

在 walkthrough 文档中，这一入口被设计为一条可点击的命令链接：

Create a new Aspire project

从扩展源码可以看到，这个命令并不是一个孤立实现，而是与 CLI 的new子命令一一对应。extension/src/commands/new.ts中的newCommand会通过AspireTerminalProvider把命令转发到专用的 Aspire 终端中执行：

export async function newCommand(terminalProvider: AspireTerminalProvider, target: CliPathResolutionTarget, cliPath: string) { await terminalProvider.sendAspireCommandToAspireTerminal('new', true, undefined, { target, cliPath }); };

命令的注册位于 extension/src/activation/registerCliCommands.ts，扩展同时注册了aspire-vscode.new（新建）、aspire-vscode.init（将现有项目初始化为 Aspire 应用）、aspire-vscode.add（添加集成）等一组命令。其中createWithAspireCommand（见 extension/src/commands/createWithAspire.ts）会把"新建应用"与"加入现有工作区"两个流程用结果导向的语言封装成两个快速选择项，再分别委托给aspire-vscode.new与aspire-vscode.init，从而保证 CLI 调用、目标解析和遥测只由单一实现负责。

命令行等价操作

如果你更习惯命令行，扩展在背后调用的其实是 Aspire CLI 的new子命令。其参数定义位于 src/Aspire.Cli/Commands/NewCommand.cs，核心选项如下：

创建后的终端体验

从AspireTerminalProvider（extension/src/utils/AspireTerminalProvider.ts）的实现可以看出，扩展为 Aspire 命令维护了专用终端：Windows 上统一使用 PowerShell（优先pwsh.exe，回退powershell.exe），Unix 上使用 POSIX 引号规则安全拼接命令；如果终端支持 Shell Integration，则优先通过shellIntegration.executeCommand执行，否则回退到sendText。这意味着你始终能在 VS Code 集成终端中看到实际运行的 CLI 命令，方便排查问题。

理解 AppHost：你的应用地图

文档中对 AppHost 有一个非常形象的比喻：AppHost 是应用的地图。它用一段可编译、可版本化的代码描述整个分布式应用的拓扑，而不是依赖散落的 YAML 或文档。这张地图由三个基本要素构成：

• Resources（资源）：描述服务、容器、数据库和前端。资源是构成应用的最小编排单元。
• Connections（连接）：让依赖关系与配置显式化。资源之间的引用关系被明确写进代码，不再靠"约定"或"运气"。
• Startup order（启动顺序）：通过显式的等待关系（wait relationships）控制依赖资源何时启动，避免"前端先于 API 启动"这类竞态问题。

模板中的真实示例

以仓库中的 Starter 模板为例，src/Aspire.ProjectTemplates/templates/aspire-starter/Aspire-StarterApplication.1.AppHost/AppHost.cs 完整展示了这三大要素如何落地：

var builder = DistributedApplication.CreateBuilder(args); var cache = builder.AddRedis("cache"); // 资源：Redis 容器 var apiService = builder.AddProject<Projects.GeneratedClassNamePrefix_ApiService>("apiservice") // 资源：API 服务项目 .WithHttpHealthCheck("/health"); builder.AddProject<Projects.GeneratedClassNamePrefix_Web>("webfrontend") // 资源：Web 前端 .WithExternalHttpEndpoints() .WithHttpHealthCheck("/health") .WithReference(cache) // 连接：前端引用 Redis .WaitFor(cache) // 启动顺序：前端等待 Redis 就绪 .WithReference(apiService) // 连接：前端引用 API .WaitFor(apiService); // 启动顺序：前端等待 API 就绪 builder.Build().Run();

在这个不到 20 行的文件中，可以清晰看到：

• 资源声明：AddRedis添加一个 Redis 容器，AddProject引入 .NET 项目（API 与 Web 前端）。仓库的src/Aspire.Hosting下还有大量类似的资源扩展，例如AddPostgres、AddKafka、AddMongoDB等，覆盖数据库、消息队列、云服务等常见依赖。
• 显式连接：WithReference(cache)、WithReference(apiService)把依赖关系写进代码。连接信息（如连接字符串、服务端点）会被注入到目标资源的配置环境中，相关机制可进一步查看 src/Aspire.Hosting/ApplicationModel/ConnectionPropertyAnnotation.cs 与 src/Aspire.Hosting/ApplicationModel/ReferenceEnvironmentInjectionAnnotation.cs 等应用模型注解。
• 启动顺序控制：WaitFor(cache)、WaitFor(apiService)建立显式等待关系，前端只有在 Redis 与 API 就绪后才会启动。WaitFor的具体语义定义在 src/Aspire.Hosting/ResourceBuilderExtensions.cs 的资源构建扩展中。

为什么应用模型值得住在代码里

文档明确指出：Because the app model lives in code, it stays readable, type-safe, and versioned with the rest of your app（应用模型存在于代码中，因此与应用的其余部分一起保持可读、类型安全且可版本化）。这句话包含三层含义，也正是 Aspire 的核心设计哲学：

1. 可读（Readable）：分布式拓扑用声明式 API 表达，读 AppHost 代码即可了解整个系统的依赖关系，无需在多个配置文件之间跳转。
2. 类型安全（Type-safe）：资源、连接与等待关系都是强类型 API，编译期即可发现引用错误、拼写错误和无效配置，而不是等到运行时。
3. 可版本化（Versioned）：AppHost 与业务代码同处一个仓库、同一套 Git 历史，拓扑变更随代码评审一起被审查、被追溯，天然支持基础设施即代码的工程实践。

下一步：继续构建

创建完第一个应用后，扩展的后续 walkthrough 文档提供了继续深入的路径：

• 为应用添加所需依赖：从集成库引入数据库、消息、云服务等，对应 Add an integration 命令（底层为 CLI 的add子命令，见 extension/src/commands/add.ts）；
• 向生产环境迈进：通过 Aspire 视图执行部署、发布制品或流水线步骤；
• 深入阅读 Aspire 文档获取完整说明。

仓库的 extension/walkthrough 目录还提供了配套的入门材料，包括 installCli.md（安装 Aspire CLI）、runApp.md（运行应用）、dashboard.md（使用仪表盘）与 nextSteps.md（下一步构建），可与本文配合阅读。

小结

从 VS Code 中的一条命令出发，你已经走过了 Aspire 入门最关键的一步：创建项目、理解 AppHost 这张"应用地图"、掌握资源/连接/启动顺序三大概念，并看到了它们在真实模板代码中的形态。接下来要做的就是打开命令面板，运行Aspire: New Project，选择适合你技术栈的 Starter 模板（或空 AppHost），然后看着你的第一个分布式应用在代码中"长"出来。

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire