practical-aspnetcore 实战:在 Minimal API 中用 Results.ServerSentEvents 实现服务端推送(SSE)
practical-aspnetcore 实战:在 Minimal API 中用 Results.ServerSentEvents 实现服务端推送(SSE)
导读
本文以 practical-aspnetcore 仓库中的 sse-2 示例 为核心,讲解如何利用 ASP.NET Core 10 在 Minimal API 中内置的 Results.ServerSentEvents 返回 Server-Sent Events(服务端事件流,SSE)。你将掌握 SSE 协议的基本工作方式、IAsyncEnumerable<string> 与取消令牌的配合用法、Accept: text/event-stream 头校验策略,以及浏览器端 EventSource 的完整接入方案,并进一步了解带事件类型(eventType)和混合事件(SseItem<T>)的进阶用法。
SSE 是什么,为什么 Minimal API 要内置支持
Server-Sent Events 是一种基于 HTTP 的单向服务端推送技术:客户端发起一个普通 HTTP 请求后,连接保持打开,服务端可以持续向客户端推送文本事件流。它天然复用 HTTP/HTTPS 基础设施,不需要像 WebSocket 那样进行协议升级(upgrade),也没有专门的服务端状态管理负担,非常适合实时通知、计数器、日志流、AI 回复流等“服务端主动、客户端被动接收”的场景。
在 ASP.NET Core 10 之前,要在应用里返回 SSE 流通常需要手工设置响应头(Content-Type: text/event-stream)、逐行构造 data: 字段、手动调用 Response.Body.FlushAsync 并自行管理客户端断连。practical-aspnetcore 仓库的 sse-2 示例正是为了演示这一体验的简化:只需要一行 Results.ServerSentEvents(...),框架就替你完成协议格式化、刷新与取消处理。
仓库根目录的 projects/sse/README.md 将该能力总结为以下几点关键特性:
- 通过
Results.ServerSentEvents()内置 SSE 支持; - 借助
IAsyncEnumerable<string>实现类型安全的流式返回; - 自动管理响应 flush;
- 正确处理取消令牌(cancellation token);
- 无需手工实现 SSE 协议细节。
最小可运行示例:返回一个持续递增的事件流
sse-2 的 Program.cs 是完整的可运行实现,核心代码如下:
using System.Runtime.CompilerServices;
var builder = WebApplication.CreateBuilder();
var app = builder.Build();
app.MapGet("/sse", (HttpContext context, CancellationToken cancellationToken) =>
{
async IAsyncEnumerable<string> CounterAsync([EnumeratorCancellation] CancellationToken cancellationToken)
{
int count = 0;
while (true && !cancellationToken.IsCancellationRequested)
{
yield return $"hello world {++count}";
await Task.Delay(3000, cancellationToken);
}
}
if (context.Request.Headers["Accept"] == "text/event-stream")
{
return Results.ServerSentEvents(CounterAsync(cancellationToken), "greeting");
}
else
{
return Results.BadRequest("Unsupported Accept header. Use 'text/event-stream'.");
}
});
app.Run();
逐段拆解
1. 局部异步迭代器 CounterAsync
async IAsyncEnumerable<string> CounterAsync([EnumeratorCancellation] CancellationToken cancellationToken)
{
int count = 0;
while (true && !cancellationToken.IsCancellationRequested)
{
yield return $"hello world {++count}";
await Task.Delay(3000, cancellationToken);
}
}
这是整个 SSE 数据源的核心。它是一个异步迭代器,每 3 秒 yield 一条字符串消息。注意两个细节:
[EnumeratorCancellation]特性让调用方传入的CancellationToken能够随枚举器传递,从而在客户端断开时及时终止循环。该特性位于System.Runtime.CompilerServices命名空间,因此文件顶部有using System.Runtime.CompilerServices;。- 循环条件同时检查
cancellationToken.IsCancellationRequested,Task.Delay(3000, cancellationToken)也接收同一令牌,实现“协作式取消”:客户端断开连接后,迭代器会在下一次迭代或下一次延时中被干净地终止,而不是无限空转。
2. Accept 头校验:SSE 前置条件
if (context.Request.Headers["Accept"] == "text/event-stream")
{
return Results.ServerSentEvents(CounterAsync(cancellationToken), "greeting");
}
else
{
return Results.BadRequest("Unsupported Accept header. Use 'text/event-stream'.");
}
这里对请求的 Accept 头做严格匹配:只有声明 text/event-stream 的请求(浏览器 EventSource 会自动携带该头)才被允许进入 SSE 通道;其余请求直接返回 400 Bad Request,避免普通浏览器请求误入无限推送流。仓库中的同类示例(如 projects/sse/Program.cs)采用了完全一致的校验逻辑,可视为该系列示例的既定模式。在 sse-3 变体中则使用了强类型的 context.Request.Headers.Accept 写法,效果等价。
3. 返回 SSE 结果
Results.ServerSentEvents(CounterAsync(cancellationToken), "greeting") 的第二个参数是 eventType,值为 "greeting"。它会作为 SSE 事件的 event: 字段写入响应,客户端需要注册 addEventListener('greeting', ...) 才能收到这类事件(详见下文客户端部分)。
项目配置
sse-2.csproj 的目标框架为 net10.0,启用 ImplicitUsings,并引用 Microsoft.AspNetCore.OpenApi(10.0.11)与 NSwag.AspNetCore(14.7.1)。整个 net10 目录下的示例统一要求 .NET SDK 10.0.100(见 projects/net10/global.json),因此运行前请先确认本机 SDK 版本满足该要求。
浏览器端接入:EventSource 消费事件流
SSE 的服务端实现只是故事的一半。sse-2 的根路径 / 返回一个内嵌 JavaScript 的 HTML 页面,演示了最小客户端接入方式:
<script>
console.log('Connecting to SSE...');
var source = new EventSource('/sse');
source.onopen = function(event) {
console.log('Connection opened:', event);
};
source.onmessage = function(e) {
var item = document.createElement('li');
item.textContent = e.data;
list.appendChild(item);
};
source.onerror = function(event){
console.log(event);
};
</script>
要点如下:
new EventSource('/sse')发起请求时会自动携带Accept: text/event-stream头,与服务端的校验逻辑天然匹配;onmessage处理器在收到默认事件(无event:字段)时触发,e.data即服务端yield出来的字符串;onopen/onerror分别对应连接建立与异常(如断线)回调。SSE 规范规定浏览器在连接意外中断后会自动重连,onerror正是观察这一过程的地方;- 需要说明的是,示例中服务端使用了
"greeting"事件类型,而 sse-2 页面只监听了onmessage;这一“错位”在 sse-3 中被修正——客户端改用source.addEventListener('greeting', ...)精确监听。如果你的页面直接基于 sse-2 复制,记得补充对应的事件监听,这是最容易踩的坑。
进阶一:显式事件类型(sse-3)
sse-3 示例 与 sse-2 逻辑几乎一致,但更清晰地展示了事件类型的作用。其服务端调用:
return Results.ServerSentEvents(GreetingsAsync(cancellationToken), eventType: "greeting");
客户端则通过命名监听器区分不同的事件类别:
source.addEventListener('greeting', function(e){
var item = document.createElement('li');
item.textContent = e.data;
const greetings = document.getElementById("greetings");
greetings.appendChild(item);
});
这相当于给事件流加了“频道”维度:同类事件(如心跳、系统公告、业务消息)可以各自命名,客户端按需订阅,而不是把所有消息都塞进 onmessage。eventType 在协议层面体现为每帧的 event: 字段,浏览器据此决定分发给哪个监听器。
进阶二:混合事件与 SseItem(sse-4)
真实场景下,一个 SSE 端点往往需要同时推送多种类型的事件。 sse-4 示例 展示了用 SseItem<T> 构造混合事件流的方式:
using System.Net.ServerSentEvents;
using System.Runtime.CompilerServices;
async IAsyncEnumerable<SseItem<string>> GetEventsAsync([EnumeratorCancellation] CancellationToken cancellationToken)
{
int count = 0;
while (true && !cancellationToken.IsCancellationRequested)
{
yield return new SseItem<string>($"hello world {++count}", "greeting");
yield return new SseItem<string>($"{DateTime.UtcNow}");
await Task.Delay(3000, cancellationToken);
}
}
这里有两个值得注意的变化:
- 引入
System.Net.ServerSentEvents命名空间下的SseItem<T>类型。new SseItem<string>(数据, "greeting")显式指定事件类型,而第二个yield(只有一个参数)则是无事件类型的默认消息; - 返回类型从
IAsyncEnumerable<string>升级为IAsyncEnumerable<SseItem<string>>,Results.ServerSentEvents(GetEventsAsync(cancellationToken))无需再单独传eventType——每个事件的类型已经内嵌在SseItem中。
客户端的监听代码也相应分化为 onmessage(默认消息)与 addEventListener('greeting', ...)(命名事件)两条通道,分别渲染到页面上两列列表。
从源码结构看,SseItem<T> 正是框架提供的“数据 + 事件元数据”载体。仓库中 projects/net11/TODO.md 的规划笔记进一步印证了它的扩展方向:在 .NET 11 的 OpenAPI 3.2 文档中,SseItem<T> 生成的 SSE 响应会带有描述每个事件载荷的 itemSchema;同时该笔记提醒了一个关键陷阱——如果直接把 IAsyncEnumerable<SseItem<T>> 作为返回值而不经过 Results.ServerSentEvents / TypedResults.ServerSentEvents 包装,框架会把它当作普通 JSON 序列化输出,而不是 SSE 流。这一点对任何想要“既推流又出 OpenAPI 文档”的读者都非常重要。
如何运行与验证
在 practical-aspnetcore 仓库中,projects/net10/sse-2 是独立可运行的 Web 项目。运行方式与仓库其他示例一致:
cd projects/net10/sse-2
dotnet run
或使用 projects/sse/README.md 推荐的开发模式:
dotnet watch run
启动后打开浏览器访问 http://localhost:5000/(具体端口以应用输出为准),可以看到页面上的列表每 3 秒追加一条 hello world N 消息,同时浏览器控制台会打印连接建立(onopen)与推流过程日志。若直接访问 /sse 而非通过页面(即请求头不含 text/event-stream),则会收到 400 响应,这正是示例中 Accept 头校验在起作用。
小结
practical-aspnetcore 的 sse-2 及其姊妹示例共同构成了一个完整的 Minimal API SSE 学习序列:
| 示例 | 核心能力 | 关键 API |
|---|---|---|
| sse-2 | 基础 SSE 推送 + Accept 头校验 | Results.ServerSentEvents(IAsyncEnumerable<string>, eventType) |
| sse-3 | 显式事件类型、客户端命名监听 | eventType: 参数 + addEventListener |
| sse-4 | 混合事件流 | SseItem<string> + IAsyncEnumerable<SseItem<T>> |
从实现原理看,Results.ServerSentEvents 替你完成了三件过去必须手工做的事情:按 SSE 规范格式化 data: / event: 帧、在每次产出后自动刷新响应流、把客户端的断连转化为 CancellationToken 取消信号。开发者只需要关心“生产什么数据、多久产一条”,协议细节完全交给框架——这正是 ASP.NET Core 10 内置 SSE 支持的设计意图。