DocFx Project (#4)

DocFx.AspNetCore.ServerSentEvents/DocFx.AspNetCore.ServerSentEvents.csproj

@@ -6,7 +6,6 @@
     <None Remove="log.txt" />
   </ItemGroup>
   <ItemGroup>
-    <Folder Include="articles\" />
     <Folder Include="wwwroot\" />
   </ItemGroup>
   <ItemGroup>

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<Startup>().Build();
+        public static void Main(string[] args) => WebHost.CreateDefaultBuilder(args).UseStartup<Startup>().Build().Run();
     }
 }

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<INotificationsServerSentEventsService, NotificationsServerSentEventsService>();
+
+		...
+    }
+
+    public void Configure(IApplicationBuilder app, IHostingEnvironment env, IServiceProvider serviceProvider)
+    {
+        ...
+
+		app.MapServerSentEvents("/default-sse-endpoint");
+		app.MapServerSentEvents("/notifications-sse-endpoint", serviceProvider.GetService<NotificationsServerSentEventsService>());
+
+		...
+    }
+}
+```
+
+## 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`.

DocFx.AspNetCore.ServerSentEvents/docfx.json

@@ -22,7 +22,8 @@
         "files": [
           "api/*.yml",
           "toc.md",
-          "index.md"
+          "index.md",
+          "articles/getting-started.md"
         ]
       }
     ],

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.

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)