configuration doc #7031

rachelappel · 2018-06-13T20:50:07Z

fixes #6599
The PR at #6852 kept erroring when pushing despite fixing merge messages, so I moved it here rather than continue to fight with it for no reason.

Internal review

BrennanConroy

I couldn't find the internal review link :(

BrennanConroy · 2018-06-13T21:37:12Z

aspnetcore/signalr/configuration.md

+## JSON/MessagePack Serialization Options
+
+ASP.NET Core SignalR supports two protocols for encoding messages, JSON and MessagePack. Each protocol has configuration options that can be used to configure serialization.
+JSON Serialization Options


3 #'s are a H3 subheading (these under messagepack). Move to H2 (##)?

BrennanConroy · 2018-06-13T21:38:14Z

aspnetcore/signalr/configuration.md

+ASP.NET Core SignalR supports two protocols for encoding messages, JSON and MessagePack. Each protocol has configuration options that can be used to configure serialization.
+JSON Serialization Options
+
+JSON serialization can be configured on both the Server and .NET Client by providing a delegate to the AddJsonHubProtocol method. The options object received by that delegate has a PayloadSerializedSettings which is a JSON.NET JsonSerializerSettings object that can be used to configure serialization of arguments and return values


Missing some code markdown and fullstop.

JSON serialization can be configured on both the Server and .NET Client.

[import snippet]
In the preceding code,

BrennanConroy · 2018-06-13T21:39:32Z

aspnetcore/signalr/configuration.md

+
+JSON serialization can be configured on both the Server and .NET Client by providing a delegate to the AddJsonHubProtocol method. The options object received by that delegate has a PayloadSerializedSettings which is a JSON.NET JsonSerializerSettings object that can be used to configure serialization of arguments and return values
+
+On the server, add `AddJsonHubProtocol` to the `AddSignalR` call in `ConfigureServices`. Use PascalCase property names instead of the default camelCase names. See the [JSON.NET Documentation](https://www.newtonsoft.com/json/help/html/Introduction.htm) for more details.


"Use PascalCase property names instead of the default camelCase names."
This sounds like we're telling them to use Pascal always

BrennanConroy · 2018-06-13T21:41:26Z

aspnetcore/signalr/configuration.md

+            options.PayloadSerializerSettings.ContractResolver = 
+            new DefaultContractResolver();
+        });
+}


Extra "}"
Move whole code snippet one tab left

BrennanConroy · 2018-06-13T21:41:53Z

aspnetcore/signalr/configuration.md

+using Microsoft.Extensions.DependencyInjection;
+
+// When constructing your connection:
+var connection = new HubConnectionBuilder();


BrennanConroy · 2018-06-13T21:53:39Z

aspnetcore/signalr/configuration.md

+        options.AccessTokenProvider = async () => {
+            // Get access token and return it.
+        };
+    });


BrennanConroy · 2018-06-13T21:53:48Z

aspnetcore/signalr/configuration.md

+        options.Headers["Foo"] = "Bar";
+        options.Cookies.Add(new Cookie(...));
+        options.ClientCertificates.Add(...);
+    });


BrennanConroy · 2018-06-13T21:54:18Z

aspnetcore/signalr/configuration.md

+    .withUrl("url")
+    .build();
+
+// Sets the transport type. Transport types are defined in preceding table


Forgot the table?

BrennanConroy · 2018-06-13T21:55:05Z

aspnetcore/signalr/configuration.md

+    .build();
+```
+
+> ![NOTE]


BrennanConroy · 2018-06-13T21:56:09Z

aspnetcore/signalr/configuration.md

+| `transport`  | Specific transport the client should use, or an `ITransport` implementation for a custom transport. |
+| `accessTokenFactory`  | Called for each HTTP request to set the authorization header or for WebSockets to set the `access_token` query string value. |
+| `logMessageContent`  | Log the message content when sending and receiving. Disabled by default. |
+| `skipNegotiation`  | Only use this when `HttpTransportType.WebSockets` is specified. It skips the negotiation step when it not necessary. |


"It skips the negotiation step when it not necessary." =>
"It skips the negotiation step when it isn't necessary."

rachelappel · 2018-06-14T10:22:15Z

Closing/reopening to force a build to get review link

Rick-Anderson · 2018-06-14T16:15:52Z

@BrennanConroy Internal review is working.

Rick-Anderson · 2018-06-14T17:06:03Z

@rachelappel

Fix all API links
All APIs referenced need first occurrence to be a link to the API
Replace all copy/paste snippets with imported snippets

Rick-Anderson · 2018-06-14T16:22:55Z

aspnetcore/signalr/configuration.md

+
+## JSON/MessagePack Serialization Options
+
+ASP.NET Core SignalR supports two protocols for encoding messages, JSON and MessagePack. Each protocol has configuration options that can be used to configure serialization.


How about
Each protocol has serialization configuration options .

Linke MessagePack to https://msgpack.org/index.html or other appropriate

Rick-Anderson · 2018-06-14T16:23:43Z

aspnetcore/signalr/configuration.md

+
+# ASP.NET Core SignalR configuration
+
+## JSON/MessagePack Serialization Options


sentence case

Rick-Anderson · 2018-06-14T16:29:08Z

aspnetcore/signalr/configuration.md

+ASP.NET Core SignalR supports two protocols for encoding messages, JSON and MessagePack. Each protocol has configuration options that can be used to configure serialization.
+JSON Serialization Options
+
+JSON serialization can be configured on both the Server and .NET Client by providing a delegate to the AddJsonHubProtocol method. The options object received by that delegate has a PayloadSerializedSettings which is a JSON.NET JsonSerializerSettings object that can be used to configure serialization of arguments and return values


The options object received by that delegate has a PayloadSerializedSettings which is a JSON.NET JsonSer
too long, split up.

AddJsonHubProtocol
Code fence all code. Ditto for PayloadSerializedSettings and JsonSerializerSettings

Rick-Anderson · 2018-06-14T16:32:00Z

aspnetcore/signalr/configuration.md

+| Option | Description |
+| ------ | ----------- |
+| `HandshakeTimeout` | If the client doesn't send an initial handshake message within this time interval, the connection will be closed |
+| `KeepAliveInterval` | If the server hasn't sent a message within this interval, a ping message will is sent automatically to keep the connection open |


Rick-Anderson · 2018-06-14T16:33:18Z

aspnetcore/signalr/configuration.md

+| `HandshakeTimeout` | If the client doesn't send an initial handshake message within this time interval, the connection will be closed |
+| `KeepAliveInterval` | If the server hasn't sent a message within this interval, a ping message will is sent automatically to keep the connection open |
+| `SupportedProtocols` | Protocols supported by this hub. By default, all protocols registered on the server are allowed, but protocols can be removed from this list to disable specific protocols for individual hubs. |
+| `EnableDetailedErrors` | If true, sends detailed error messages to the client when exceptions occur. This may contain sensitive data and is `false` by default |


avoid this
The detailed error messages may ...

Rick-Anderson · 2018-06-14T17:00:46Z

aspnetcore/signalr/configuration.md

+
+### HttpConnectionDispatcherOptions
+
+Options related to the transport layer. Use these to restrict the transports that can be used by SignalR clients, as well as to configure advanced settings related to memory buffer management. These options are configured by passing a delegate to `MapHub<T>`.


Options related to the transport layer.

That doesn't make sense by itself. SHould it be

HttpConnectionDispatcherOptions - Options related to the transport layer.

Rick-Anderson · 2018-06-14T17:03:59Z

aspnetcore/signalr/configuration.md

+| Cookies | Cookies to be sent with each HTTP request. |
+| ClientCertificates | TLS client certificates to send when connecting over HTTP (not supported in Xamarin) |
+
+The following code samples demonstrate the C# setting connection options with the `HubConnectionBuilder`:


The following code sets connection options with ~~the~~ HubConnectionBuilder:

https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.signalr.client.hubconnectionbuilder?view=aspnetcore-2.1

Rick-Anderson · 2018-06-14T17:06:57Z

aspnetcore/signalr/configuration.md

+  }
+```
+
+### HttpConnectionDispatcherOptions


append Options related to the transport layer ???

Rick-Anderson · 2018-06-14T17:07:42Z

aspnetcore/signalr/configuration.md

+
+### HttpConnectionDispatcherOptions
+
+Options related to the transport layer. Use these to restrict the transports that can be used by SignalR clients, as well as to configure advanced settings related to memory buffer management. These options are configured by passing a delegate to `MapHub<T>`.


What is these?

Rick-Anderson · 2018-06-14T17:08:21Z

aspnetcore/signalr/configuration.md

+
+| Option | Description |
+| ------ | ----------- |
+| `ApplicationMaxBufferSize`  | The maximum number of bytes the connection (transport) can buffer when invoking methods from the client, before blocking and waiting for the application to consume enough bytes to allow writing again.  |


try to split up long sentence.

analogrelay

Some comments. Still working through it

analogrelay · 2018-06-18T16:56:57Z

aspnetcore/signalr/configuration.md

+
+[!code-csharp[Startup config](configuration/sample/config-startup.cs?range=1-5)]
+
+The preceding code adds add `AddJsonHubProtocol` to the [AddSignalR](/dotnet/api/microsoft.extensions.dependencyinjection.signalrdependencyinjectionextensions.addsignalr#Microsoft_Extensions_DependencyInjection_SignalRDependencyInjectionExtensions_AddSignalR_Microsoft_Extensions_DependencyInjection_IServiceCollection_) call in [ConfigureServices](/dotnet/api/microsoft.aspnetcore.hosting.istartup.configureservices#Microsoft_AspNetCore_Hosting_IStartup_ConfigureServices_Microsoft_Extensions_DependencyInjection_IServiceCollection_). Then the code provides a delegate to the `AddJsonHubProtocol` method. The `options` object received by that delegate has a `PayloadSerializedSettings`. The `PayloadSerializedSettings` is a JSON.NET [JsonSerializerSettings](/dotnet/api/microsoft.aspnetcore.mvc.formatters.jsonserializersettingsprovider object that can be used to configure serialization of arguments and return values. See the [JSON.NET Documentation](https://www.newtonsoft.com/json/help/html/Introduction.htm) for more details.


The wording here seems a bit awkward. What about moving it above the example:

JSON serialization can be configured on the server using the AddJsonProtocol extension method. The AddJsonProtocol method takes a delegate that receives an options object. The PayloadSerializerSettings property on that object is a JSON.NET JsonSerializerSettings object that can be used to configure serialization of arguments and return values. See the JSON.NET Documentation for more details.

As an example, you can configure the serializer to use PascalCase names instead of the default camelCase names using the following code:

[example]

In the .NET client, the same AddJsonHubProtocol extension method exists on HubConnectionBuilder. The Microsoft.Extensions.DependencyInjection namespace must be imported to resolve the extension method:

[example]

analogrelay · 2018-06-18T16:57:46Z

aspnetcore/signalr/configuration.md

+The preceding code adds add `AddJsonHubProtocol` to the [AddSignalR](/dotnet/api/microsoft.extensions.dependencyinjection.signalrdependencyinjectionextensions.addsignalr#Microsoft_Extensions_DependencyInjection_SignalRDependencyInjectionExtensions_AddSignalR_Microsoft_Extensions_DependencyInjection_IServiceCollection_) call in [ConfigureServices](/dotnet/api/microsoft.aspnetcore.hosting.istartup.configureservices#Microsoft_AspNetCore_Hosting_IStartup_ConfigureServices_Microsoft_Extensions_DependencyInjection_IServiceCollection_). Then the code provides a delegate to the `AddJsonHubProtocol` method. The `options` object received by that delegate has a `PayloadSerializedSettings`. The `PayloadSerializedSettings` is a JSON.NET [JsonSerializerSettings](/dotnet/api/microsoft.aspnetcore.mvc.formatters.jsonserializersettingsprovider object that can be used to configure serialization of arguments and return values. See the [JSON.NET Documentation](https://www.newtonsoft.com/json/help/html/Introduction.htm) for more details.
+
+> [!NOTE]
+> It's possible to use PascalCase property names instead of the default camelCase names.


This seems awkward. There are many different settings and while this is a common one, I don't think it should be called out as a NOTE. In my above comment, I suggested just working it in to the example description. I think that's a little cleaner.

analogrelay · 2018-06-18T16:58:57Z

aspnetcore/signalr/configuration.md

+
+### Configure [HubOptions](/dotnet/api/microsoft.aspnetcore.signalr.huboptions) for SignalR
+
+The following table describes the `HubOptions` options for configuring the hub:


for configuring ~~the~~ a hub

analogrelay · 2018-06-18T17:00:29Z

aspnetcore/signalr/configuration.md

+| `SupportedProtocols` | Protocols supported by this hub. By default, all protocols registered on the server are allowed, but protocols can be removed from this list to disable specific protocols for individual hubs. |
+| `EnableDetailedErrors` | If true, sends detailed error messages to the client when exceptions occur. The detailed error messages may contain sensitive data, and are `false` by default. |
+
+The `HubOptions` are configured in the `ConfigureServices` method of the `Startup` class, as shown in the following code sample:


Suggest:

Options can be configured for all hubs by providing an options delegate to the AddSignalR call in ConfigureServices

analogrelay · 2018-06-18T17:01:00Z

aspnetcore/signalr/configuration.md

+
+[!code-csharp[Startup](configuration/sample/config-startup.cs?range=7-14)]
+
+Strongly-typed [HubOptions<T>](/dotnet/api/microsoft.aspnetcore.signalr.huboptions-1) are as follows:


Suggest:

Options for a single hub override the global options provided in AddSignalR and can be configured using AddHubOptions<T>:

analogrelay · 2018-06-18T19:43:05Z

aspnetcore/signalr/configuration.md

+> [!NOTE]
+> It's not possible to configure JSON or MessagePack serialization in the JavaScript client at this time.
+
+### Configure [HubOptions](/dotnet/api/microsoft.aspnetcore.signalr.huboptions) for SignalR


We should make all these headers a little more consistent. How about we remove the type names from the headers, and leave those for the prose below.

Also, I think we can just merge this with the next section (HttpConnectionDispatcherOptions) as a "Configuring Server Options" section. The section below on the Client has multiple types and I think it works fine there.

analogrelay · 2018-06-18T19:45:02Z

aspnetcore/signalr/configuration.md

+
+ Items in the table marked with an asterisk (*) are specific to WebSockets.
+
+### HubConnectionBuilder


"Configuring Client Options"

This section looks really rough right now. I think we should split it into two, with one for .NET and one for JavaScript. There will be some duplication, but I think that's OK.

In each section, I think we should list the properties on the relevant object (JS: https://github.com/aspnet/SignalR/blob/dev/clients/ts/signalr/src/IHttpConnectionOptions.ts, C#: https://github.com/aspnet/SignalR/blob/dev/src/Microsoft.AspNetCore.Http.Connections.Client/HttpConnectionOptions.cs) with the descriptions we've got here. Code samples can come afterwards, illustrating some of the scenarios.

analogrelay · 2018-06-18T19:45:52Z

aspnetcore/signalr/configuration.md

+
+### HubConnectionBuilder
+
+The [HubConnectionBuilder](/dotnet/api/microsoft.aspnetcore.signalr.client.hubconnectionbuilder) API is available for both C# and TypeScript clients.


~~TypeScript~~ JavaScript

The client is written in TypeScript and includes a full set of "typings" files to make it easier to use from TypeScript, but that's just an implementation detail. The client works on any JavaScript environment and you can use plain JavaScript to interact with it, so it's a "JavaScript client"

analogrelay · 2018-06-19T21:59:52Z

aspnetcore/signalr/configuration.md

+| `WebSockets`*  |  Gets the WebSockets options object.  |
+| `CloseTimeout`*  | TimeSpan to set how long to wait for a clean WebSocket close when connection is being terminated.  |
+| `SubProtocolSelector`* | A delegate the hub calls and passes a list of `Sec-WebSocket-Protocol` values from the request header. A delegate returns the chosen `Sec-WebSocket-Protocol`. |
+| `AccessTokenProvider`* | A delegate that is called to get an access token. The token is applied as an HTTP Bearer Authentication header. |


First: AccessTokenProvider isn't a property on HttpConnectionDispatcherOptions. Just strike this row.

Also: It's not quite clear that CloseTimeout, and SubProtocolSelector are properties on the WebSocketOptions object, not HttpConnectionDispatcherOptions. Perhaps a separate table? Or write them as WebSockets.CloseTimeout?

analogrelay · 2018-06-19T22:38:20Z

aspnetcore/signalr/configuration.md

+
+ Items in the table marked with an asterisk (*) are specific to WebSockets.
+
+## Configure client options


I think the client options section needs a bit of a rework. The headers don't match with the tables and the code snippets are a bit rough. I'll sketch something up.

analogrelay · 2018-06-20T17:01:12Z

Replace all copy/paste snippets with imported snippets

@Rick-Anderson Can you clarify the expected pattern here? In most of the other docs it looks like inline snippets are used when the example is illustrative but not part of a fully-functional sample and imported snippets are used when the example is part of a fully-functional sample. There isn't a sample associated with this document so I'd expect to use mostly inline snippets in this document.

scottaddie · 2018-06-20T17:20:19Z

aspnetcore/signalr/configuration.md

+title: ASP.NET Core SignalR configuration
+author: rachelappel
+description: Configure ASP.NET Core SignalR Apps
+manager: wpickett


Remove the following metadata fields:

manager

ms.prod

ms.technology

ms.topic

These are defined in docfx.json now.

scottaddie · 2018-06-20T17:20:42Z

aspnetcore/signalr/configuration.md

+
+[!code-csharp[HubConnectionBuilder](configuration/sample/addhubjsonprotocol.cs)]
+
+### MessagePack Serialization Options


Serialization Options --> serialization options

analogrelay · 2018-06-20T17:56:56Z

I reworked the client options section, but I realized the original branch is in a fork so I can't easily just push some additional changes :). The easiest thing to do here may just be to open a new PR (again 😝) from my branch now.

rachelappel · 2018-06-20T19:52:35Z

@anurse Go for it, remember to tag us. :D I'll hold off on any changes on my side until you do that.

As discussed #7031 (comment) I made some changes and decided to just open a new PR to get things cleared up. [Internal Review URL](https://review.docs.microsoft.com/en-us/aspnet/core/signalr/configuration?view=aspnetcore-2.1&branch=pr-en-us-7199)

configuration doc

e8f9f24

rachelappel requested a review from BrennanConroy June 13, 2018 20:50

rachelappel assigned analogrelay Jun 13, 2018

rachelappel mentioned this pull request Jun 13, 2018

signalr/configuration draft #6852

Closed

BrennanConroy reviewed Jun 13, 2018

View reviewed changes

rachelappel closed this Jun 14, 2018

rachelappel reopened this Jun 14, 2018

Rick-Anderson requested changes Jun 14, 2018

View reviewed changes

rachelappel added 3 commits June 14, 2018 15:37

feedback changes

a42c847

feedback modifications

1ab67c7

feedback changes

6d6cce6

analogrelay reviewed Jun 18, 2018

View reviewed changes

rachelappel added 3 commits June 18, 2018 15:01

andrew feedback changes

1272b0f

andrew feedback

e846aaa

merge

79f0c5e

rachelappel force-pushed the rachelap/signalr-configuration branch from edbc7f1 to 79f0c5e Compare June 18, 2018 19:18

analogrelay reviewed Jun 18, 2018

View reviewed changes

rachelappel and others added 3 commits June 19, 2018 17:43

andrew feedback changes

5515142

tiny mod

48f25fc

Merge branch 'master' into rachelap/signalr-configuration

8c470a8

analogrelay reviewed Jun 20, 2018

View reviewed changes

scottaddie reviewed Jun 20, 2018

View reviewed changes

analogrelay closed this Jun 20, 2018

analogrelay mentioned this pull request Jun 20, 2018

Configuration: Pass #3 #7199

Merged


		JSON serialization can be configured on both the Server and .NET Client by providing a delegate to the AddJsonHubProtocol method. The options object received by that delegate has a PayloadSerializedSettings which is a JSON.NET JsonSerializerSettings object that can be used to configure serialization of arguments and return values

		On the server, add `AddJsonHubProtocol` to the `AddSignalR` call in `ConfigureServices`. Use PascalCase property names instead of the default camelCase names. See the [JSON.NET Documentation](https://www.newtonsoft.com/json/help/html/Introduction.htm) for more details.


		## JSON/MessagePack Serialization Options

		ASP.NET Core SignalR supports two protocols for encoding messages, JSON and MessagePack. Each protocol has configuration options that can be used to configure serialization.


		# ASP.NET Core SignalR configuration

		## JSON/MessagePack Serialization Options


		### HttpConnectionDispatcherOptions

		Options related to the transport layer. Use these to restrict the transports that can be used by SignalR clients, as well as to configure advanced settings related to memory buffer management. These options are configured by passing a delegate to `MapHub<T>`.


		[!code-csharp[Startup config](configuration/sample/config-startup.cs?range=1-5)]

		The preceding code adds add `AddJsonHubProtocol` to the [AddSignalR](/dotnet/api/microsoft.extensions.dependencyinjection.signalrdependencyinjectionextensions.addsignalr#Microsoft_Extensions_DependencyInjection_SignalRDependencyInjectionExtensions_AddSignalR_Microsoft_Extensions_DependencyInjection_IServiceCollection_) call in [ConfigureServices](/dotnet/api/microsoft.aspnetcore.hosting.istartup.configureservices#Microsoft_AspNetCore_Hosting_IStartup_ConfigureServices_Microsoft_Extensions_DependencyInjection_IServiceCollection_). Then the code provides a delegate to the `AddJsonHubProtocol` method. The `options` object received by that delegate has a `PayloadSerializedSettings`. The `PayloadSerializedSettings` is a JSON.NET [JsonSerializerSettings](/dotnet/api/microsoft.aspnetcore.mvc.formatters.jsonserializersettingsprovider object that can be used to configure serialization of arguments and return values. See the [JSON.NET Documentation](https://www.newtonsoft.com/json/help/html/Introduction.htm) for more details.


		### Configure [HubOptions](/dotnet/api/microsoft.aspnetcore.signalr.huboptions) for SignalR

		The following table describes the `HubOptions` options for configuring the hub:


		[!code-csharp[Startup](configuration/sample/config-startup.cs?range=7-14)]

		Strongly-typed [HubOptions<T>](/dotnet/api/microsoft.aspnetcore.signalr.huboptions-1) are as follows:


		Items in the table marked with an asterisk (*) are specific to WebSockets.

		### HubConnectionBuilder


		### HubConnectionBuilder

		The [HubConnectionBuilder](/dotnet/api/microsoft.aspnetcore.signalr.client.hubconnectionbuilder) API is available for both C# and TypeScript clients.


		Items in the table marked with an asterisk (*) are specific to WebSockets.

		## Configure client options


		[!code-csharp[HubConnectionBuilder](configuration/sample/addhubjsonprotocol.cs)]

		### MessagePack Serialization Options

configuration doc #7031

configuration doc #7031

Conversation

rachelappel commented Jun 13, 2018 • edited Loading

BrennanConroy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rachelappel commented Jun 14, 2018

Rick-Anderson commented Jun 14, 2018

Rick-Anderson commented Jun 14, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HttpConnectionDispatcherOptions - Options related to the transport layer.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

analogrelay left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

analogrelay commented Jun 20, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

analogrelay commented Jun 20, 2018

rachelappel commented Jun 20, 2018

rachelappel commented Jun 13, 2018 •

edited

Loading