Dotnet-api-docs: WebSocket platform support

[breyed]

The ClientWebSocket Class docs for ASP.NET Core 2.1 say, "the only public implementations of client and server WebSockets are supported on Windows 8 and Windows Server 2012."

However, WebSockets support in ASP.NET Core says that WebSockets are supported on "any OS that supports ASP.NET Core."

These contradictory statements of support need to be reconciled.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 47bc11d0-a599-ca40-82cd-953e2cf7160e
• Version Independent ID: 98845ff1-bd60-0192-5708-ff346da6b62c
• Content: ClientWebSocket Class (System.Net.WebSockets)
• Content Source: xml/System.Net.WebSockets/ClientWebSocket.xml
• Product: dotnet-api
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[BillWagner]

@davidsh Can you provide the right resolution to this issue?

[BillWagner]

Thanks for pointing this out @breyed We're looking into the correct fix.

[davidsh]

cc: @Tratcher
Can you clarify ASP.NET Core support of WebSockets regarding Windows OS version?

.NET Framework and .NET Core only supports websockets from Windows 8 and beyond. That is due to websockets using a native Windows component, WEBSOCKET.DLL, that is only present in Windows 8+.

[Tratcher]

Keep reading in that linked doc:

"If the app runs on Windows with IIS:

• Windows 8 / Windows Server 2012 or later
• IIS 8 / IIS 8 Express
• WebSockets must be enabled in IIS (See the IIS/IIS Express support section.)

If the app runs on HTTP.sys:

• Windows 8 / Windows Server 2012 or later"

[breyed]

I'm surprised that the HTTP server binding affects ClientWebSocket.

Looking at client and server together, as I understand the WebSockets support doc, these are examples of the minimum Windows version required:

• WebSocket client: Win7
• WebSocket server via Kestrel: Win7
• WebSocket server via IIS: Win8
• WebSocket server via HTTP.sys: Win8

If that's right, it looks like just the class doc(s) need to be updated. If not, it looks like WebSockets support doc needs to be updated, too.

[Tratcher]

I'm surprised that the HTTP server binding affects ClientWebSocket.

What do you mean by that? The client and server are implemented independently but often use common dependencies from the OS. Newer implementations like Kestrel or SocketsHttpHandler have opted to use new dependencies that are not tied to the OS version.

[breyed]

I didn't realize that the client side technology stack was tied to the server side selection, or that server side selection could cause a not supported exception.

c# var kestrelClient = new ClientWebSocket(); WebHost.CreateDefaultBuilder(args).UseHttpSys(); var httpSysClient = new ClientWebSocket();

In the above code example, on Windows 7, the first attempt to create a WebSocket client succeeds, but the second fails (if I understand you correctly). Since the OS-independent code is available, I'm surprised that WebSocketClient doesn't fall back on it.

[davidfowl]

I didn't realize that the client side technology stack was tied to the server side selection, or that server side selection could cause a not supported exception.

It isn't.

In the above code example, on Windows 7, the first attempt to create a WebSocket client succeeds, but the second fails (if I understand you correctly). Since the OS-independent code is available, I'm surprised that WebSocketClient doesn't fall back on it.

That doesn't make any sense.

[breyed]

It's not clear how to reconcile the comments from @Tratcher and @davidfowl. On the one had, WebSocket client and server "use common dependencies from the OS" and "If the app runs on HTTP.sys", then Win 8 is required. On the other, the client and server side aren't tied to each other and the selection of a HTTP binding via UseHttpSys doesn't affect the ability to use ClientWebSocket.

The docs should provide enough background to make answers to these questions apparent: What determines whether ClientWebSocket will run on Windows 7? How does HTTP server binding (Kestrel, IIS, etc.) affect ClientWebSocket support, if at all? Can you use ClientWebSocket on Windows 7 if you're running on .NET Framework 4.6.1 (which supports .NET Standard 2.0)? What about on .NET Framework 4.6 (which doesn't) via the System.Net.WebSockets.Client NuGet package?

[davidfowl]

It's not clear how to reconcile the comments from @Tratcher and @davidfowl. On the one had, WebSocket client and server "use common dependencies from the OS" and "If the app runs on HTTP.sys", then Win 8 is required. On the other, the client and server side aren't tied to each other and the selection of a HTTP binding via UseHttpSys doesn't affect the ability to use ClientWebSocket.

Which part of that is confusing? If you're using the HTTP.sys server then the windows version dictates if WebSockets are available.

This is the same with IIS. When hosting using IIS, the version of windows dictates the whether websockets are supported.

In both of the above cases, Windows >= 8.1 is required (or server 2012) to get WebSockets on the server side.

Running directly against Kestrel doesn't have the same restriction and WebSockets works pretty much anywhere that .NET works.

That's the server, which doesn't affect the client.

ClientWebSocket on the other hand is has varying implementations depending on what version of .NET (Core, Framework, Xamarin) and operation system you're running on. As a result, there is a complicated matrix for determining if the API will just work.

The docs should provide enough background to make answers to these questions apparent: What determines whether ClientWebSocket will run on Windows 7? How does HTTP server binding (Kestrel, IIS, etc.) affect ClientWebSocket support, if at all? Can you use ClientWebSocket on Windows 7 if you're running on .NET Framework 4.6.1 (which supports .NET Standard 2.0)? What about on .NET Framework 4.6 (which doesn't) via the System.Net.WebSockets.Client NuGet package?

Agreed.

What determines whether ClientWebSocket will run on Windows 7?

On .NET Framework, the windows version determines this. You need to be on at least windows >= 8.1 or Server 2012 to make ClientWebSocket work on .NET Framework.

How does HTTP server binding (Kestrel, IIS, etc.) affect ClientWebSocket support, if at all?

It doesn't.

Can you use ClientWebSocket on Windows 7 if you're running on .NET Framework 4.6.1 (which supports .NET Standard 2.0)?

No. It will explode.

What about on .NET Framework 4.6 (which doesn't) via the System.Net.WebSockets.Client NuGet package?

AFAIK, no it will not work. This still uses the underlying implementation shipped on .NET Framework which relies on Windows components.

On .NET Core < 2.1, a similar restriction exists on Windows. ClientWebSocket relies on Windows >= 8.1 or Server 2012. On linux, it works anywhere .NET Core works.

On .NET Core >= 2.1, ClientWebSocket works on Windows 7 (this was fixed, see https://github.com/dotnet/corefx/issues/9503).

On UWP - ClientWebSocket uses the underlying OS support (I'm not sure what the deal is here).

Hopefully we can write this in the docs in a meaningful way.

[TechnikEmpire]

Thanks @davidfowl , I found your last comment here after crying real tears because the documentation led me to believe that managed websockets in .net core 3 were not supported on Windows 7.