WebSocket: Document how WebSocket enters Aborted, what states are allowed pre-conditions for calling CloseAsync and CloseOutputAsync, and which exception is thrown if state pre-condition is violated

[mattflaschen]

Describe the issue or suggestion

Document (on relevant methods, e.g. SendAsync, ReceiveAsync, etc.) how a WebSocket can enter a WebSocketState.Aborted state.

Relatedly (Aborted is not an allowed state for CloseAsync), document which WebSocketState values are allowed pre-conditions when calling CloseAsync and CloseOutputAsync,

As an example of the motivation for this request, I received an error:

The WebSocket is in an invalid state ('Aborted') for this operation. Valid states are: 'Open, CloseReceived, CloseSent'

when calling CloseAsync (I believe another WebSocket method was cancelled by a CancellationToken, which put it into Aborted state).

CloseAsync (via WebSocketStateHelper) throws a WebSocketException if the pre-condition state is invalid. This needs to be documented as a possible exception anywhere it can be thrown (e.g. CloseAsync, CloseOutputAsync, etc.). Only OperationCanceledException is currently listed.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/ncl

[mattflaschen]

For example, if the ReceiveAsync CancellationToken triggers, the entire WebSocket object enters Aborted state. This is not documented. Before learning that, I expected that only the current receive operation would be cancelled.