practical-aspnetcore 实战:在 Minimal API 中用 Results.ServerSentEvents 实现服务端推送(SSE)

原创2026-10-14 20:28:202,339 阅读
文章标签:示例工程

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 支持的设计意图。

登录后查看全文
practical-aspnetcore