aspnet-sse

ASP.NET Core Server-Sent Events (SSE) Skill

SSE is the right choice for server-to-client real-time push when bi-directional communication isn't needed — notifications, live updates, AI streaming. Unlike WebSockets, SSE runs over plain HTTP/1.1, is trivially proxied, and gets free reconnect logic in browsers.

ASP.NET Core 10 adds native first-class support via TypedResults.ServerSentEvents and System.Net.ServerSentEvents.SseItem<T>, eliminating the need for manual text/event-stream formatting.

Quick reference

Architecture overview

Mutation → Event stored → Projection updated → INotificationService.NotifyAsync()
                                                    ↓ (fan-out)
                                        Channel per subscriber → SseItem<T>
                                                    ↓
                                        TypedResults.ServerSentEvents(stream)
                                                    ↓
                                        Browser EventSource / SseParser

For multi-instance deployments, NotifyAsync publishes to Redis pub/sub instead of writing to local channels directly. Each instance subscribes to Redis and fans out to its own local Channel subscribers. See redis-scaling.md.

Core types

The three overloads of TypedResults.ServerSentEvents

// 1. Strings — sent as raw text (no JSON wrapping)
TypedResults.ServerSentEvents(IAsyncEnumerable<string> values, string? eventType = null)

// 2. Objects — serialized as JSON
TypedResults.ServerSentEvents<T>(IAsyncEnumerable<T> values, string? eventType = null)

// 3. SseItem<T> — full control over event type, id, and data per item
TypedResults.ServerSentEvents<T>(IAsyncEnumerable<SseItem<T>> values)

Use overload 3 (SseItem<T>) when each event has a different type (e.g., BookCreated, AuthorUpdated). The event type becomes the event: field in the SSE wire format and maps directly to EventSource.addEventListener('BookCreated', ...) in JavaScript.

Pattern: polymorphic domain events

When you have multiple event types sharing a base interface, use [JsonPolymorphic] on the interface and [JsonDerivedType] for each concrete type. This lets you serialize/deserialize through IDomainEventNotification without losing type information:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "NotificationType")]
[JsonDerivedType(typeof(BookCreatedNotification), "BookCreated")]
[JsonDerivedType(typeof(BookUpdatedNotification), "BookUpdated")]
public interface IDomainEventNotification
{
    Guid EventId { get; }
    Guid EntityId { get; }
    string EventType { get; }
    DateTimeOffset Timestamp { get; }
}

Each notification record is past-tense, carries EventId for causation tracking, and has a stable EventType string that matches the SSE event name.

Common mistakes

• No initial event → browser hangs: Browsers buffer text/event-stream responses until they see data. Emit a ping/Connected event immediately when a client subscribes to flush headers. See server-endpoint.md.
• Shared mutable state without CancellationToken: Always thread CancellationToken through Channel.Writer.WriteAsync and use [EnumeratorCancellation] on the subscribe method. Otherwise clients that disconnect silently leak channel entries forever.
• Single INotificationService instance in multi-replica deployments: Local channels don't cross process boundaries. Add Redis pub/sub or a message broker. See redis-scaling.md.
• Missing ProjectionCommitListener registration: If SSE notifications don't fire after a mutation, check that the new projection type is handled in AfterCommitAsync. The listener must be registered as both IDocumentSessionListener and IChangeListener in Marten configuration.
• Results vs TypedResults: Prefer TypedResults.ServerSentEvents — it returns the concrete ServerSentEventsResult<T> which integrates with OpenAPI metadata automatically. Results.ServerSentEvents returns IResult and loses that.