Merge pull request #184417 from JialinXin/awps-chatapp-middleware

ttorble · web-flow · commit 24d171e37f1e · 2022-01-11T09:48:49.000Z
[WebPubSub] Update c# sample to use middleware.
diff --git a/articles/azure-web-pubsub/tutorial-build-chat.md b/articles/azure-web-pubsub/tutorial-build-chat.md
@@ -76,7 +76,7 @@ First let's create an empty ASP.NET Core app.
 
     ```bash
     dotnet new web
-    dotnet add package Azure.Messaging.WebPubSub
+    dotnet add package Microsoft.Azure.WebPubSub.AspNetCore --version 1.0.0-beta.3
     ```
 
 2.  Then add `app.UseStaticFiles();` before `app.UseRouting();` in `Startup.cs` to support static files. Remove the default `endpoints.MapGet` inside `app.UseEndpoints`.
@@ -90,7 +90,6 @@ First let's create an empty ASP.NET Core app.
         }
 
         app.UseStaticFiles();
-
         app.UseRouting();
 
         app.UseEndpoints(endpoints =>
@@ -114,25 +113,44 @@ You can test the server by running `dotnet run --urls http://localhost:8080` and
 
 You may remember in the [publish and subscribe message tutorial](./tutorial-pub-sub-messages.md) the subscriber uses an API in Web PubSub SDK to generate an access token from connection string and use it to connect to the service. This is usually not safe in a real world application as connection string has high privilege to do any operation to the service so you don't want to share it with any client. Let's change this access token generation process to a REST API at server side, so client can call this API to request an access token every time it needs to connect, without need to hold the connection string.
 
-1.  Install dependencies
-    Install dependencies and use [Secret Manager](/aspnet/core/security/app-secrets#secret-manager) tool for .NET Core to set the connection string. Run the below command, replacing `<connection_string>` with the one fetched in [previous step](#get-the-connectionstring-for-future-use)
+1.  Install dependencies.
 
     ```bash
     dotnet add package Microsoft.Extensions.Azure
     ```
 
-2. DI the service client inside `ConfigureServices` and don't forget to replace `<connection_string>` with the one of your services.
+2.  Add a `SampleChatHub` class to handle hub events. And DI the service middleware and service client inside `ConfigureServices()`. Don't forget to replace `<connection_string>` with the one of your services.
 
     ```csharp
     public void ConfigureServices(IServiceCollection services)
     {
-        services.AddAzureClients(builder =>
+        services.AddWebPubSub(o => o.ServiceEndpoint = new ServiceEndpoint("<connection_string>"))
+                .AddWebPubSubServiceClient<SampleChatHub>();
+    }
+
+    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+    {
+        if (env.IsDevelopment())
+        {
+            app.UseDeveloperExceptionPage();
+        }
+
+        app.UseStaticFiles();
+        app.UseRouting();
+
+        app.UseEndpoints(endpoints =>
         {
-            builder.AddWebPubSubServiceClient("<connection_string>", "chat");
         });
     }
+
+    private sealed class SampleChatHub : WebPubSubHub
+    {
+    }
     ```
-2.  Add a `/negotiate` API to the server inside `app.UseEndpoints` to generate the token
+
+    `AddWebPubSubServiceClient<THub>()` is used to inject the service client `WebPubSubServiceClient<THub>`, with which we can use in negotiation step to generate client connection token and in hub methods to invoke service REST APIs when hub events are triggered.
+
+3.  Add a `/negotiate` API to the server inside `app.UseEndpoints` to generate the token.
 
     ```csharp
     app.UseEndpoints(endpoints =>
@@ -146,7 +164,7 @@ You may remember in the [publish and subscribe message tutorial](./tutorial-pub-
                 await context.Response.WriteAsync("missing user id");
                 return;
             }
-            var serviceClient = context.RequestServices.GetRequiredService<Azure.Messaging.WebPubSub.WebPubSubServiceClient>();
+            var serviceClient = context.RequestServices.GetRequiredService<WebPubSubServiceClient<SampleChatHub>>();
             await context.Response.WriteAsync(serviceClient.GetClientAccessUri(userId: id).AbsoluteUri);
         });
     });
@@ -156,7 +174,7 @@ You may remember in the [publish and subscribe message tutorial](./tutorial-pub-
 
     You can test this API by running `dotnet run --urls http://localhost:8080` and accessing `http://localhost:8080/negotiate?id=<user-id>` and it will give you the full url of the Azure Web PubSub with an access token.
 
-3.  Then update `index.html` to include the following script to get the token from server and connect to service
+4.  Then update `index.html` to include the following script to get the token from server and connect to service.
  
     ```html
     <html>
@@ -176,8 +194,7 @@ You may remember in the [publish and subscribe message tutorial](./tutorial-pub-
     </html>
     ```
 
-    If you are using Chrome, you can test it by opening the home page, input your user name. press F12 to open the Developer Tools window, switch to **Console** table and you'll see `connected` being printed in browser console.
-
+    If you are using Chrome, you can test it by opening the home page, input your user name. Press F12 to open the Developer Tools window, switch to **Console** table and you'll see `connected` being printed in browser console.
 
 # [JavaScript](#tab/javascript)
 
@@ -285,7 +302,7 @@ You may remember in the [publish and subscribe message tutorial](./tutorial-pub-
     </html>
     ```
 
-    If you are using Chrome, you can test it by opening the home page, input your user name. press F12 to open the Developer Tools window, switch to **Console** table and you'll see `connected` being printed in browser console.
+    If you are using Chrome, you can test it by opening the home page, input your user name. Press F12 to open the Developer Tools window, switch to **Console** table and you'll see `connected` being printed in browser console.
 
 # [Java](#tab/java)
 
@@ -459,7 +476,7 @@ You may remember in the [publish and subscribe message tutorial](./tutorial-pub-
     </html>
     ```
 
-    If you are using Chrome, you can test it by opening the home page, input your user name. press F12 to open the Developer Tools window, switch to **Console** table and you'll see `connected` being printed in browser console.
+    If you are using Chrome, you can test it by opening the home page, input your user name. Press F12 to open the Developer Tools window, switch to **Console** table and you'll see `connected` being printed in browser console.
 
 ---
 
@@ -472,63 +489,35 @@ Events are delivered to server in the form of Webhook. Webhook is served and exp
 Azure Web PubSub follows [CloudEvents](./reference-cloud-events.md) to describe the event data. 
 
 # [C#](#tab/csharp)
-For now, you need to implement the event handler by your own in C#, the steps are straight forward following [the protocol spec](./reference-cloud-events.md) and illustrated below.
+Here we're using Web PubSub middleware SDK, there is already an implementation to parse and process CloudEvents schema, so we don't need to deal with these details. Instead, we can focus on the inner business logic in the hub methods. 
 
 1. Add event handlers inside `UseEndpoints`. Specify the endpoint path for the events, let's say `/eventhandler`. 
-
-2. First we'd like to handle the abuse protection OPTIONS requests, we check if the header contains `WebHook-Request-Origin` header, and we return the header `WebHook-Allowed-Origin`. For simplicity for demo purpose, we return `*` to allow all the origins.
     ```csharp
     app.UseEndpoints(endpoints =>
     {
-        // abuse protection
-        endpoints.Map("/eventhandler/{*path}", async context =>
-        {
-            if (context.Request.Method == "OPTIONS")
-            {
-                if (context.Request.Headers["WebHook-Request-Origin"].Count > 0)
-                {
-                    context.Response.Headers["WebHook-Allowed-Origin"] = "*";
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-            }
-        });
+        endpoints.MapWebPubSubHub<SampleChatHub>("/eventhandler/{*path}");
     });
     ```
 
-3. Then we'd like to check if the incoming requests are the events we expect. Let's say we now care about the system `connected` event, which should contain the header `ce-type` as `azure.webpubsub.sys.connected`. We add the logic after abuse protection:
+2. Go the `SampleChatHub` we created in previous step. Add a constructor to work with `WebPubSubServiceClient<SampleChatHub>` so we can use to invoke service. And override `OnConnectedAsync()` method to respond when `connected` event is triggered.
     ```csharp
-    app.UseEndpoints(endpoints =>
+    private sealed class SampleChatHub : WebPubSubHub
     {
-        // abuse protection
-        endpoints.Map("/eventhandler/{*path}", async context =>
+        private readonly WebPubSubServiceClient<SampleChatHub> _serviceClient;
+
+        public SampleChatHub(WebPubSubServiceClient<SampleChatHub> serviceClient)
         {
-            if (context.Request.Method == "OPTIONS")
-            {
-                if (context.Request.Headers["WebHook-Request-Origin"].Count > 0)
-                {
-                    context.Response.Headers["WebHook-Allowed-Origin"] = "*";
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-            }
-            else if (context.Request.Method == "POST")
-            {
-                // get the userId from header
-                var userId = context.Request.Headers["ce-userId"];
-                if (context.Request.Headers["ce-type"] == "azure.webpubsub.sys.connected")
-                {
-                    // the connected event
-                    Console.WriteLine($"{userId} connected");
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-            }
-        });
-    });
+            _serviceClient = serviceClient;
+        }
+
+        public override async Task OnConnectedAsync(ConnectedEventRequest request)
+        {
+            await _serviceClient.SendToAllAsync($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
+        }
+    }
     ```
 
-In the above code, we simply print a message to console when a client is connected. You can see we use `context.Request.Headers["ce-userId"]` so we can see the identity of the connected client.
+In the above code, we use the service client to broadcast a notification message to all of whom is joined.
 
 # [JavaScript](#tab/javascript)
 
@@ -629,50 +618,35 @@ Besides system events like `connected` or `disconnected`, client can also send m
 
 # [C#](#tab/csharp)
 
-The `ce-type` of `message` event is always `azure.webpubsub.user.message`, details see [Event message](./reference-cloud-events.md#message).
+Implement the `OnMessageReceivedAsync()` method in `SampleChatHub`.
 
-1. Handle message event
+1. Handle message event.
 
     ```csharp
-    app.UseEndpoints(endpoints =>
+    private sealed class SampleChatHub : WebPubSubHub
     {
-        // abuse protection
-        endpoints.Map("/eventhandler/{*path}", async context =>
+        private readonly WebPubSubServiceClient<SampleChatHub> _serviceClient;
+
+        public SampleChatHub(WebPubSubServiceClient<SampleChatHub> serviceClient)
         {
-            var serviceClient = context.RequestServices.GetRequiredService<Azure.Messaging.WebPubSub.WebPubSubServiceClient>();
-            if (context.Request.Method == "OPTIONS")
-            {
-                if (context.Request.Headers["WebHook-Request-Origin"].Count > 0)
-                {
-                    context.Response.Headers["WebHook-Allowed-Origin"] = "*";
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-            }
-            else if (context.Request.Method == "POST")
-            {
-                // get the userId from header
-                var userId = context.Request.Headers["ce-userId"];
-                if (context.Request.Headers["ce-type"] == "azure.webpubsub.sys.connected")
-                {
-                    // the connected event
-                    Console.WriteLine($"{userId} connected");
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-                else if (context.Request.Headers["ce-type"] == "azure.webpubsub.user.message")
-                {
-                    using var stream = new StreamReader(context.Request.Body);
-                    await serviceClient.SendToAllAsync($"[{userId}] {await stream.ReadToEndAsync()}");
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-            }
-        });
-    });
+            _serviceClient = serviceClient;
+        }
+
+        public override async Task OnConnectedAsync(ConnectedEventRequest request)
+        {
+            await _serviceClient.SendToAllAsync($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
+        }
+
+        public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
+        {
+            await _serviceClient.SendToAllAsync($"[{request.ConnectionContext.UserId}] {request.Data}");
+
+            return request.CreateResponse($"[SYSTEM] ack."));
+        }
+    }
     ```
 
-    This event handler uses `WebPubSubServiceClient.SendToAllAsync()` to broadcast the received message to all clients.
+    This event handler uses `WebPubSubServiceClient.SendToAllAsync()` to broadcast the received message to all clients. You can see in the end we returned `UserEventResponse`, which contains a message directly to the caller and make the WebHook request success. If you have extra logic to validate and would like to break this call, you can throw an exception here. The middleware will deliver the exception message to service and service will drop current client connection.
 
 2.  Update `index.html` to add the logic to send message from user to server and display received messages in the page.
 
@@ -713,41 +687,6 @@ The `ce-type` of `message` event is always `azure.webpubsub.user.message`, detai
 
     You can see in the above code we use `WebSocket.send()` to send message and `WebSocket.onmessage` to listen to message from service.
 
-3.  Finally update the `onConnected` handler to broadcast the connected event to all clients so they can see who joined the chat room.
-
-    ```csharp
-    app.UseEndpoints(endpoints =>
-    {
-        var serviceClient = context.RequestServices.GetRequiredService<Azure.Messaging.WebPubSub.WebPubSubServiceClient>();
-        // abuse protection
-        endpoints.Map("/eventhandler/{*path}", async context =>
-        {
-            if (context.Request.Method == "OPTIONS")
-            {
-                if (context.Request.Headers["WebHook-Request-Origin"].Count > 0)
-                {
-                    context.Response.Headers["WebHook-Allowed-Origin"] = "*";
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-            }
-            else if (context.Request.Method == "POST")
-            {
-                // get the userId from header
-                var userId = context.Request.Headers["ce-userId"];
-                if (context.Request.Headers["ce-type"] == "azure.webpubsub.sys.connected")
-                {
-                    // the connected event
-                    Console.WriteLine($"{userId} connected");
-                    await serviceClient.SendToAllAsync($"[SYSTEM] {userId} joined.");
-                    context.Response.StatusCode = 200;
-                    return;
-                }
-            }
-        });
-    });
-    ```
-
 Now run the server using `dotnet run --urls http://localhost:8080` and open multiple browser instances to access http://localhost:8080/index.html, then you can chat with each other.
 
 The complete code sample of this tutorial can be found [here][code-csharp].
