The WebSocketClient Client

The framework includes the built-in WebSocketClient type, making it easy for users to establish a connection with a WebSocket server via the ws or wss protocol. To use the WebSocket functionality, you first need to create and initialize an instance of WebSocketClient. The following details all the functional configuration options available on a WebSocketClient instance:

Creating a WebSocketClient Client

The following are three ways to create a WebSocketClient instance. They are implemented through different constructor overloads, but essentially all of them ultimately call the constructor with the WebSocketClientOptions parameter to configure the connection:

1234567891011

// Use a URL string directly (supports ws:// and wss://)using var webSocketClient = new WebSocketClient("wss://localhost:7044/ws");// Use a Uri objectusing var webSocketClient = new WebSocketClient(new Uri("wss://localhost:7044/ws"));// Use a WebSocketClientOptions object for detailed configurationusing var webSocketClient = new WebSocketClient(new WebSocketClientOptions("wss://localhost:7044/ws"));// Configure the internal ClientWebSocketOptions instanceusing var webSocketClient = new WebSocketClient("wss://localhost:7044/ws", options => {});

The WebSocketClientOptions type contains a variety of configuration properties for customizing the detailed settings of the ClientWebSocket connection. WebSocketClientOptions includes the following properties:

Properties:
- ServerUri: The server address (Uri type).
- ReconnectInterval: The reconnect interval (in milliseconds); the default value is 2 seconds. (TimeSpan type).
- MaxReconnectRetries: The maximum number of reconnect attempts, defaulting to 10. (int type).
- Timeout: The timeout duration (TimeSpan type).
- ReceiveBufferSize: The size of the buffer for receiving new messages from the server (an int type in bytes).
- Configure: Configures the internal ClientWebSocketOptions instance (Action<ClientWebSocketOptions> type).

WebSocketClient Client Events

The WebSocketClient client provides a variety of events, allowing developers to insert custom logic at various stages of WebSocket communication. The following example shows how to subscribe to these events:

12345678910111213141516171819202122232425262728293031

using var webSocketClient = new WebSocketClient("wss://localhost:7044/ws");    // Supports ws:// and wss://// Event triggered when connection startswebSocketClient.Connecting += (s, e) => {};// Event triggered when the connection succeedswebSocketClient.Connected += (s, e) => { };// Event triggered when reconnecting startswebSocketClient.Reconnecting += (s, e) => { };// Event triggered when reconnecting succeedswebSocketClient.Reconnected += (s, e) => { };// Event triggered when closing startswebSocketClient.Closing += (s, e) => { };// Event triggered when the connection is closed successfullywebSocketClient.Closed += (s, e) => { };// Event triggered when message receiving startswebSocketClient.ReceivingStarted += (s, e) => { };// Event triggered when message receiving stopswebSocketClient.ReceivingStopped += (s, e) => { };// Event for receiving text messages; result is of type WebSocketTextReceiveResultwebSocketClient.TextReceived += (s, result) => { };// Event for receiving binary messages; result is of type WebSocketBinaryReceiveResultwebSocketClient.BinaryReceived += (s, result) => { };

The WebSocketTextReceiveResult type derives from WebSocketReceiveResult and includes the following properties:

Properties:
- Message: The text message (string type).
- For other properties, refer to WebSocketReceiveResult

The WebSocketBinaryReceiveResult type derives from WebSocketReceiveResult and includes the following properties:

Properties:
- Message: The binary message (byte[] type).
- For other properties, refer to WebSocketReceiveResult

WebSocketClient Client Methods

The WebSocketClient class encapsulates the key operations for interacting with a WebSocket server, specifically three methods: connecting, sending messages, and closing the connection.

12345678910111213141516

using var webSocketClient = new WebSocketClient("wss://localhost:7044/ws");    // Supports ws:// and wss://// Connect to the serverawait webSocketClient.ConnectAsync(cancellationToken);// Send a message to the serverawait webSocketClient.SendAsync(message, endOfMessage, cancellationToken);  // Send a string messageawait webSocketClient.SendAsync(byteArray, endOfMessage, cancellationToken);    // Send a binary messageawait webSocketClient.SendAsync(message, webSocketMessageType, endOfMessage, cancellationToken);    // Send a message of the specified type (text or binary)// Wait for messages (blocking)await webSocketClient.WaitAsync(cancellationToken);// Close the connectionawait webSocketClient.CloseAsync(cancellationToken);    // Close without additional informationawait webSocketClient.CloseAsync(closeStatus, closeDescription, cancellationToken); // Close providing close status and description