模板与项目结构

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

快速开始 中我们用模板生成了一个 Aspire 解决方案。这一节来拆解模板到底生成了什么，以及每个项目的职责。

模板分类

Aspire 模板分为两类：

• 解决方案模板（Solution templates）：创建一个包含多个项目的完整 Aspire 解决方案。
• 项目模板（Project templates）：创建单个项目，用于添加到已有的 Aspire 解决方案中。

常见的解决方案模板：

模板名	说明
aspire-empty	最小模板，只包含 AppHost 与 ServiceDefaults。
aspire-starter	C# AppHost + ASP.NET Core Minimal API + Blazor 前端，最常用的入门模板。
aspire-ts-starter	TypeScript AppHost + Express API + React 前端。
aspire-ts-cs-starter	ASP.NET Core API + React 前端。
aspire-py-starter	FastAPI + React 前端。

使用 aspire new <模板名> 创建：

C# AppHost + Blazor

aspire new aspire-starter -n AspireApp -o AspireApp

最小模板

aspire new aspire-empty -n AspireApp -o AspireApp

只看所有模板

aspire new --help

关于 -n 与 -o

-n（--name）指定解决方案名称，-o（--output）指定输出目录。如果不传 -o，CLI 会用模板名作为目录名；如果该目录已存在且非空，会自动追加数字后缀，例如 aspire-starter-2。

生成的项目结构

使用 aspire-starter 模板后，目录大致如下：

AspireApp/
├── AspireApp.sln
├── AspireApp.AppHost/               # 编排项目（您要重点关注的地方）
│   ├── AppHost.cs
│   ├── appsettings.json
│   ├── appsettings.Development.json
│   └── AspireApp.AppHost.csproj
├── AspireApp.ApiService/            # ASP.NET Core Minimal API
│   ├── Program.cs
│   └── AspireApp.ApiService.csproj
├── AspireApp.Web/                   # Blazor 前端
│   ├── Program.cs
│   └── AspireApp.Web.csproj
└── AspireApp.ServiceDefaults/       # 共享服务配置
    ├── Extensions.cs
    └── AspireApp.ServiceDefaults.csproj

AppHost：编排入口

AppHost 是整个应用的「架构说明书」。它本身不承载业务逻辑，只负责声明有哪些资源、它们之间是什么关系：

var builder = DistributedApplication.CreateBuilder(args);

var apiService = builder
    .AddProject<Projects.AspireApp_ApiService>("apiservice")
    .WithHttpHealthCheck("/health");

builder
    .AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

关键点：

• AddProject<Projects.XxxService> 注册一个 .NET 项目资源。泛型参数来自源码生成器，保证编译期就能发现拼写错误。
• WithReference(apiService) 把 API 的地址以环境变量注入前端，同时启用服务发现。
• WaitFor(apiService) 让前端等待 API 通过健康检查后再启动，避免启动竞态。
• WithHttpHealthCheck("/health") 为资源添加 HTTP 健康检查。
• WithExternalHttpEndpoints() 表示该资源需要暴露给浏览器访问。

ServiceDefaults：共享的服务配置

ServiceDefaults 是一个被各服务引用的共享项目，通过扩展方法统一切入常见能力：

public static class Extensions
{
    public static IHostApplicationBuilder AddServiceDefaults(this IHostApplicationBuilder builder)
    {
        builder.ConfigureOpenTelemetry();
        builder.AddDefaultHealthChecks();
        builder.Services.AddServiceDiscovery();
        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            http.AddStandardResilienceHandler();
            http.AddServiceDiscovery();
        });
        return builder;
    }
}

它统一处理了四件事：

能力	说明
遥测	配置 OpenTelemetry 的日志、指标、追踪导出，见 遥测。
健康检查	默认暴露 /health 与 /alive 端点。
服务发现	让 HttpClient 能解析 https+http://apiservice 这样的逻辑地址。
HTTP 弹性	为标准 HttpClient 添加重试、熔断、超时策略。

ApiService 与 Web：普通业务项目

这两个项目就是普通的 ASP.NET Core 项目，唯一「特别」的地方是在 Program.cs 顶部调用了一次 AddServiceDefaults()：

var builder = WebApplication.CreateBuilder(args);

builder.AddServiceDefaults();

var app = builder.Build();

app.MapDefaultEndpoints();
app.MapGet("/weatherforecast", () => Results.Ok(WeatherForecast.Generate()));
app.Run();

这意味着您现有的 ASP.NET Core 项目不需要为了使用 Aspire 而重写，加上一行 AddServiceDefaults() 即可获得服务发现、弹性与遥测能力。

运行

cd ./AspireApp
aspire run

输出大致如下：

🔍 Finding apphosts...
AspireApp.AppHost/AspireApp.AppHost.csproj
🗄 Created settings file at 'aspire.config.json'.

 AppHost: AspireApp.AppHost/AspireApp.AppHost.csproj

 Dashboard: https://localhost:17068/login?t=ea559845d54cea66b837dc0ff33c3bd3
 Logs: %USERPROFILE%/.aspire/cli/logs/apphost-13024-2025-10-31-19-40-58.log

 Press CTRL+C to stop the apphost and exit.

打开 Dashboard 后面的地址（注意带登录令牌的完整链接）即可看到资源列表、日志与追踪。按 Ctrl+C 停止应用。

调试断点怎么打？

aspire run 启动的是 AppHost 进程，它会再启动各个资源进程。在 Visual Studio 中直接 F5 运行 AppHost 项目，就可以对解决方案中任意服务下断点、单步调试——这正是 Aspire 相比「开五个终端」的最大差别。

下一步

• 了解 AppHost 应用主机 的完整能力。
• 了解 资源模型。
• 为应用添加第一个 集成。