资源模型

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

资源（Resource） 是 Aspire 建模的基本单位。一个服务、一个容器、一个数据库、一个缓存、一个云存储账户，都是资源。把它们和它们之间的依赖关系放在一起，就构成了应用模型。

资源的两个关键性质

• 资源默认是「惰性」的：它本质上是一个纯数据对象，用来描述能力、配置与关系。资源不负责自己的生命周期（启动、停止、健康检查），这些由编排器统一协调。
• 资源在应用图中拥有唯一名称：这个名称是所有引用、接线与可视化的基础。它同时也是环境变量名生成的输入，因此不要随意改名。

资源状态

资源在运行期间会经历一系列状态，Aspire 仪表板与 aspire describe 会显示它们：

状态	含义
Starting	正在启动。
Running	已启动。
Healthy	已通过健康检查。
Unhealthy	健康检查失败。
FailedToStart	启动失败。
Finished / Exited	已正常结束（常见于一次性任务）。

用 CLI 观察状态

aspire start        # 后台启动
aspire describe     # 查看资源表
aspire describe -f  # 持续流式输出状态变化

资源的类型

由 Aspire 核心提供

类别	API	说明
.NET 项目	AddProject<T>("name")	引用 .NET 项目，支持调试与热重载。
容器	AddContainer("name", "image")	直接使用镜像启动容器。
容器构建	AddDockerfile("name", "ctx", "file")	由 Dockerfile 构建并启动容器。
可执行文件	AddExecutable("name", "cmd", "args")	启动本机任意可执行程序。
参数	AddParameter("name")	外部参数/机密，见外部参数。
连接字符串	AddConnectionString("name")	直接提供外部服务的连接字符串。

由集成包提供

绝大多数资源来自集成包（Hosting integration）。例如：

类别	集成包示例
数据库	Aspire.Hosting.PostgreSQL、Aspire.Hosting.SqlServer、Aspire.Hosting.MySql、Aspire.Hosting.MongoDB、Aspire.Hosting.Oracle、Aspire.Hosting.Sqlite
缓存	Aspire.Hosting.Redis、Aspire.Hosting.Garnet、Aspire.Hosting.Valkey
消息	Aspire.Hosting.RabbitMQ、Aspire.Hosting.Kafka、Aspire.Hosting.NATS
云服务	Aspire.Hosting.Azure.*、Aspire.Hosting.AWS
可观测性	Aspire.Hosting.Seq、Grafana / Loki / Prometheus / Tempo 系列
框架	Aspire.Hosting.NodeJs、Aspire.Hosting.Python、Aspire.Hosting.Java、Aspire.Hosting.Go、Aspire.Hosting.Rust

完整清单可在集成画廊中检索（150+ 个集成）。

资源层级

许多资源是父子（包含）关系。数据库挂在数据库服务器下，缓存之外还可能有多个逻辑库：

var postgres = builder.AddPostgres("pg");
var appDb = postgres.AddDatabase("appdata");   // appDb 是 postgres 的子资源
var cache = builder.AddRedis("cache");

var api = builder.AddProject<Projects.Api>("api")
    .WithReference(appDb)
    .WithReference(cache);

在这个例子里：

• pg 是容器资源，appdata 是它之上的逻辑数据库资源。
• 引用子资源（appDb）时，Aspire 会注入指向该具体数据库的连接字符串，而不是服务器的连接字符串。
• 仪表板上，子资源会以嵌套形式展示在父资源下方。

也可以显式切换层级关系：

var api = builder.AddProject<Projects.Api>("api");
var worker = builder.AddProject<Projects.Worker>("worker");

worker.WithParentRelationship(api);   // worker 作为 api 的子资源展示

生命周期默认独立

层级关系默认只影响展示与命名，不会自动让子资源跟随父资源启动。如果要表达启动依赖，请显式使用 WaitFor。

资源生命周期

Aspire 在本地开发时管理资源的完整生命周期：

1. 发现（Discovery）：发现资源并分析依赖关系。
2. 启动（Startup）：按依赖顺序启动资源。
3. 健康监控（Health Monitoring）：持续监控资源的健康与就绪状态。
4. 关闭（Shutdown）：应用终止时优雅停止资源。

可以用生命周期钩子插入自定义逻辑：

var pg = builder.AddPostgres("pg");

pg.OnResourceReady(async (resource, evt, ct) =>
{
    // 资源就绪后执行：例如运行数据库迁移
    await RunMigrationsAsync(ct);
});

常用钩子：

钩子	触发时机
OnBeforeResourceStarted	资源启动前。
OnResourceReady	资源就绪（健康）后。
OnResourceStopped	资源停止后。
OnConnectionStringAvailable	连接字符串可用时。

还可以通过 aspire resource 对资源执行命令（重启、停止、启动等）：

aspire resource cache restart

资源命名约定

资源名需要满足：

• 在应用图中唯一。
• 由字母、数字与连字符组成时最安全（会参与环境变量名生成）。
• 使用连字符（my-cache）会在生成的物理环境变量名中转换为下划线（my_cache）；使用双下划线（my__db）会被折叠为单个下划线。

换言之，my-db 与 my_db 会映射到同一个物理变量名，同时使用会导致解析期冲突报错。详细规则见环境变量命名约定。

下一步

• 应用模型与架构
• 健康检查
• 集成简介