From 2eb599642bffb63a191b7ace1d09b8a3fd9ed81a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20P=C4=99czek?= Date: Sat, 30 Sep 2017 19:09:48 +0200 Subject: [PATCH] DocFx Project (#4) --- .../DocFx.AspNetCore.ServerSentEvents.csproj | 1 - DocFx.AspNetCore.ServerSentEvents/Program.cs | 2 +- .../articles/getting-started.md | 95 +++++++++++++++++++ DocFx.AspNetCore.ServerSentEvents/docfx.json | 3 +- DocFx.AspNetCore.ServerSentEvents/index.md | 11 ++- DocFx.AspNetCore.ServerSentEvents/toc.md | 2 + 6 files changed, 110 insertions(+), 4 deletions(-) create mode 100644 DocFx.AspNetCore.ServerSentEvents/articles/getting-started.md diff --git a/DocFx.AspNetCore.ServerSentEvents/DocFx.AspNetCore.ServerSentEvents.csproj b/DocFx.AspNetCore.ServerSentEvents/DocFx.AspNetCore.ServerSentEvents.csproj index 8c41d6c..4cd9dfc 100644 --- a/DocFx.AspNetCore.ServerSentEvents/DocFx.AspNetCore.ServerSentEvents.csproj +++ b/DocFx.AspNetCore.ServerSentEvents/DocFx.AspNetCore.ServerSentEvents.csproj @@ -6,7 +6,6 @@ - diff --git a/DocFx.AspNetCore.ServerSentEvents/Program.cs b/DocFx.AspNetCore.ServerSentEvents/Program.cs index 1fd501a..1032aef 100644 --- a/DocFx.AspNetCore.ServerSentEvents/Program.cs +++ b/DocFx.AspNetCore.ServerSentEvents/Program.cs @@ -5,6 +5,6 @@ namespace DocFx.AspNetCore.ServerSentEvents { public class Program { - public static void Main(string[] args) => WebHost.CreateDefaultBuilder(args).UseStartup().Build(); + public static void Main(string[] args) => WebHost.CreateDefaultBuilder(args).UseStartup().Build().Run(); } } diff --git a/DocFx.AspNetCore.ServerSentEvents/articles/getting-started.md b/DocFx.AspNetCore.ServerSentEvents/articles/getting-started.md new file mode 100644 index 0000000..fbffdc3 --- /dev/null +++ b/DocFx.AspNetCore.ServerSentEvents/articles/getting-started.md @@ -0,0 +1,95 @@ +# Getting Started + +## Configuration + +In order to add the Server-Sent Events (SSE) support to an application a required service and middleware must be registered. The library provides [extensions](../api/Lib.AspNetCore.ServerSentEvents.ServerSentEventsMiddlewareExtensions.html) which make it really simple. + +```cs +public class Startup +{ + public void ConfigureServices(IServiceCollection services) + { + ... + + services.AddServerSentEvents(); + + ... + } + + public void Configure(IApplicationBuilder app) + { + ... + + app.MapServerSentEvents("/default-sse-endpoint"); + + ... + } +} +``` + +The `AddServerSendEvents()` method registers default service which provides operations over Server-Sent Events protocol, while `MapServerSentEvents()` maps this service to a specific endpoint. The `MapServerSentEvents()` method can be called multiple times for different endpoints but all of them will be mapped to same service which will make them indistinguishable from application perspective. In order to create distinguishable endpoints a delivered version of [`Server​Sent​Events​Service`](../api/Lib.AspNetCore.ServerSentEvents.ServerSentEventsService.html) should be registered (it doesn't need to override any of the default service functionality). Below is an example of such configuration. + +```cs +internal interface INotificationsServerSentEventsService : IServerSentEventsService +{ } + +internal class NotificationsServerSentEventsService : ServerSentEventsService, INotificationsServerSentEventsService +{ } + +public class Startup +{ + public void ConfigureServices(IServiceCollection services) + { + ... + + services.AddServerSentEvents(); + services.AddServerSentEvents(); + + ... + } + + public void Configure(IApplicationBuilder app, IHostingEnvironment env, IServiceProvider serviceProvider) + { + ... + + app.MapServerSentEvents("/default-sse-endpoint"); + app.MapServerSentEvents("/notifications-sse-endpoint", serviceProvider.GetService()); + + ... + } +} +``` + +## Sending Messages + +In order to send a message to an endpoint the instance of the service registered for that endpoint should be obtained. The easiest way is to rely on dependency injection. + +```cs +public class NotificationsController : Controller +{ + private readonly INotificationsServerSentEventsService _serverSentEventsService; + + public NotificationsController(INotificationsServerSentEventsService serverSentEventsService) + { + _serverSentEventsService = serverSentEventsService; + } + + ... +} +``` + +### Sending to all clients + +Sending message to all clients is as simple as calling `IServerSentEventsService.SendEventAsync`. Under the hood the service will take care of distributing the message to all connected clients. + +### Sending to specific client + +The `IServerSentEventsService.GetClients()` method returns list of all currently connected clients. Every client (represented by [`IServerSentEventsClient`](../api/Lib.AspNetCore.ServerSentEvents.IServerSentEventsClient.html)) exposes `User` property and `SendEventAsync` method. The `User` property contains a `System.Security.Claims.ClaimsPrincipal` which can be used to filter a specific client. Additionally there is an `Id` property available which value can be stored and later passed to `IServerSentEventsService.GetClient()` in order to retrieve a specific client. + +## Handling Auto Reconnect + +Server-Sent Events provide auto reconnect and tracking of the last seen message functionality. If the connection is dropped, client will automatically reconnect to the server and optionally advertise the identifier of the last seen message. This allows for retransmission of lost messages. In order to use this mechanism the `OnReconnectAsync` method must be overridden when delivering from `Server​Sent​Events​Service`. When client reconnects the method will be called with `IServerSentEventsClient` representing the client and the identifier of last message which client has received. + +### Changing Reconnect Interval + +The interval after which client attempts to reconnect can be controlled by the application. In order to change the interval for specific endpoint it is enough to call `IServerSentEventsService.ChangeReconnectIntervalAsync`. \ No newline at end of file diff --git a/DocFx.AspNetCore.ServerSentEvents/docfx.json b/DocFx.AspNetCore.ServerSentEvents/docfx.json index b0cffb0..a16edc2 100644 --- a/DocFx.AspNetCore.ServerSentEvents/docfx.json +++ b/DocFx.AspNetCore.ServerSentEvents/docfx.json @@ -22,7 +22,8 @@ "files": [ "api/*.yml", "toc.md", - "index.md" + "index.md", + "articles/getting-started.md" ] } ], diff --git a/DocFx.AspNetCore.ServerSentEvents/index.md b/DocFx.AspNetCore.ServerSentEvents/index.md index 912600e..43b47e9 100644 --- a/DocFx.AspNetCore.ServerSentEvents/index.md +++ b/DocFx.AspNetCore.ServerSentEvents/index.md @@ -4,16 +4,25 @@ Lib.AspNetCore.ServerSentEvents is a library which provides Server-Sent Events ( ## Getting Started -Lib.AspNetCore.ServerSentEvents is available on [NuGet](https://www.nuget.org/packages/Lib.AspNetCore.ServerSentEvents/). +You can install [Lib.AspNetCore.ServerSentEvents](https://www.nuget.org/packages/Lib.AspNetCore.ServerSentEvents/) from NuGet. ``` PM> Install-Package Lib.AspNetCore.ServerSentEvents ``` +The configuration and basic usage patterns are described [here](articles/getting-started.md). + ## Demos The demo project is available on [GitHub](https://github.com/tpeczek/Demo.AspNetCore.ServerSentEvents). +## Additional Resources + +There are some blog posts available which describe implementation details and some interesting scenarios: + +- [Server-Sent Events (SSE) support for ASP.NET Core](https://www.tpeczek.com/2017/02/server-sent-events-sse-support-for.html) +- [Server-Sent Events (or WebSockets) broadcasting in load balancing scenario with Redis](https://www.tpeczek.com/2017/09/server-sent-events-or-websockets.html) + ## Donating Lib.AspNetCore.ServerSentEvents is a personal open source project. If Lib.AspNetCore.ServerSentEvents has been helpful to you, consider donating. Donating helps support Lib.AspNetCore.ServerSentEvents. diff --git a/DocFx.AspNetCore.ServerSentEvents/toc.md b/DocFx.AspNetCore.ServerSentEvents/toc.md index b66a53b..1a38084 100644 --- a/DocFx.AspNetCore.ServerSentEvents/toc.md +++ b/DocFx.AspNetCore.ServerSentEvents/toc.md @@ -1,3 +1,5 @@ # [Introduction](index.md) +# [Getting Started](articles/getting-started.md) + # [API Reference](api/Lib.AspNetCore.ServerSentEvents.html) \ No newline at end of file