Class WebSocketModule

A base class for modules that handle WebSocket connections.

Inheritance
Object
WebModuleBase
WebSocketModule
Implements
IDisposable
Inherited Members
Namespace: EmbedIO.WebSockets
Syntax
public abstract class WebSocketModule : WebModuleBase, IWebModuleImpl, IWebModule, IDisposable
Remarks

Each WebSocket server has a list of WebSocket subprotocols it can accept.

When a client initiates a WebSocket opening handshake:

  • if the list of accepted subprotocols is empty, the connection is accepted only if no SecWebSocketProtocol header is present in the request;
  • if the list of accepted subprotocols is not empty, the connection is accepted only if one or more SecWebSocketProtocol headers are present in the request and one of them specifies one of the subprotocols in the list. The first subprotocol specified by the client that is also present in the module's list is then specified in the handshake response.
If a connection is not accepted because of a subprotocol mismatch, a 400 Bad Request response is sent back to the client. The response contains one or more SecWebSocketProtocol headers that specify the list of accepted subprotocols (if any).

Constructors

WebSocketModule(String, Boolean)

Initializes a new instance of the WebSocketModule class.

Declaration
protected WebSocketModule(string path, bool enableConnectionWatchdog)
Parameters
Type Name Description
String path

The URL path of the WebSocket endpoint to serve.
Boolean enableConnectionWatchdog

If set to true, contexts representing closed connections will automatically be purged from ActiveContexts every 30 seconds..

Properties

ActiveContexts

Gets a list of IWebSocketContext interfaces representing the currently connected clients.

Declaration
protected IReadOnlyList<IWebSocketContext> ActiveContexts { get; }
Property Value
Type Description
IReadOnlyList<IWebSocketContext>

Encoding

Gets the Encoding used by the SendAsync(IWebSocketContext, String) method to send a string. The default is UTF8 per the WebSocket specification.

Declaration
protected Encoding Encoding { get; set; }
Property Value
Type Description
Encoding

IsFinalHandler

Gets a value indicating whether processing of a request should stop after a module has handled it.

Declaration
public override sealed bool IsFinalHandler { get; }
Property Value
Type Description
Boolean
Overrides
Remarks

If this property is true, a HTTP context's SetHandled() method will be automatically called immediately after after the returned by HandleRequestAsync(IHttpContext) is completed. This will prevent the context from being passed further along to other modules.

See Also

KeepAliveInterval

Gets or sets the keep-alive interval for the WebSocket connection. The default is 30 seconds.

Declaration
protected TimeSpan KeepAliveInterval { get; set; }
Property Value
Type Description
TimeSpan

MaxMessageSize

Gets or sets the maximum size of a received message. If a message exceeding the maximum size is received from a client, the connection is closed automatically.

The default value is 0, which disables message size checking.

Declaration
protected int MaxMessageSize { get; set; }
Property Value
Type Description
Int32

Methods

AddProtocol(String)

Adds a WebSocket subprotocol to the list of protocols supported by a WebSocketModule.

Declaration
protected void AddProtocol(string protocol)
Parameters
Type Name Description
String protocol

The protocol name to add to the list.
See Also

AddProtocols(IEnumerable<String>)

Adds one or more WebSocket subprotocols to the list of protocols supported by a WebSocketModule.

Declaration
protected void AddProtocols(IEnumerable<string> protocols)
Parameters
Type Name Description
IEnumerable<String> protocols

The protocol names to add to the list.
Remarks

This method enumerates protocols just once; hence, if an exception is thrown because one of the specified protocols is null or contains invalid characters, any preceding protocol is added to the list of supported protocols.

See Also

AddProtocols(String[])

Adds one or more WebSocket subprotocols to the list of protocols supported by a WebSocketModule.

Declaration
protected void AddProtocols(params string[] protocols)
Parameters
Type Name Description
String[] protocols

The protocol names to add to the list.
Remarks

This method performs validation checks on all specified protocols before adding them to the list of supported protocols; hence, if an exception is thrown because one of the specified protocols is null or contains invalid characters, none of the specified protocol names are added to the list.

See Also

BroadcastAsync(Byte[])

Broadcasts the specified payload to all connected WebSocket clients.

Declaration
protected Task BroadcastAsync(byte[] payload)
Parameters
Type Name Description
Byte[] payload

The payload.
Returns
Type Description
Task

A representing the ongoing operation.

BroadcastAsync(Byte[], Func<IWebSocketContext, Boolean>)

Broadcasts the specified payload to selected WebSocket clients.

Declaration
protected Task BroadcastAsync(byte[] payload, Func<IWebSocketContext, bool> selector)
Parameters
Type Name Description
Byte[] payload

The payload.
Func<IWebSocketContext, Boolean> selector

A callback function that must return true for each context to be included in the broadcast.
Returns
Type Description
Task

A representing the ongoing operation.

BroadcastAsync(String)

Broadcasts the specified payload to all connected WebSocket clients.

Declaration
protected Task BroadcastAsync(string payload)
Parameters
Type Name Description
String payload

The payload.
Returns
Type Description
Task

A representing the ongoing operation.

BroadcastAsync(String, Func<IWebSocketContext, Boolean>)

Broadcasts the specified payload to selected WebSocket clients.

Declaration
protected Task BroadcastAsync(string payload, Func<IWebSocketContext, bool> selector)
Parameters
Type Name Description
String payload

The payload.
Func<IWebSocketContext, Boolean> selector

A callback function that must return true for each context to be included in the broadcast.
Returns
Type Description
Task

A representing the ongoing operation.

CloseAsync(IWebSocketContext)

Closes the specified web socket, removes it and disposes it.

Declaration
protected Task CloseAsync(IWebSocketContext context)
Parameters
Type Name Description
IWebSocketContext context

The web socket.
Returns
Type Description
Task

A representing the ongoing operation.

Dispose()

Declaration
public void Dispose()

Dispose(Boolean)

Releases unmanaged and - optionally - managed resources.

Declaration
protected virtual void Dispose(bool disposing)
Parameters
Type Name Description
Boolean disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.

OnClientConnectedAsync(IWebSocketContext)

Called when this WebSocket server accepts a new client.

Declaration
protected virtual Task OnClientConnectedAsync(IWebSocketContext context)
Parameters
Type Name Description
IWebSocketContext context

The context.
Returns
Type Description
Task

A representing the ongoing operation.

OnClientDisconnectedAsync(IWebSocketContext)

Called when the server has removed a connected client for any reason.

Declaration
protected virtual Task OnClientDisconnectedAsync(IWebSocketContext context)
Parameters
Type Name Description
IWebSocketContext context

The context.
Returns
Type Description
Task

A representing the ongoing operation.

OnFrameReceivedAsync(IWebSocketContext, Byte[], IWebSocketReceiveResult)

Called when this WebSocket server receives a message frame regardless if the frame represents the EndOfMessage.

Declaration
protected virtual Task OnFrameReceivedAsync(IWebSocketContext context, byte[] buffer, IWebSocketReceiveResult result)
Parameters
Type Name Description
IWebSocketContext context

The context.
Byte[] buffer

The buffer.
IWebSocketReceiveResult result

The result.
Returns
Type Description
Task

A representing the ongoing operation.

OnMessageReceivedAsync(IWebSocketContext, Byte[], IWebSocketReceiveResult)

Called when this WebSocket server receives a full message (EndOfMessage) from a client.

Declaration
protected abstract Task OnMessageReceivedAsync(IWebSocketContext context, byte[] buffer, IWebSocketReceiveResult result)
Parameters
Type Name Description
IWebSocketContext context

The context.
Byte[] buffer

The buffer.
IWebSocketReceiveResult result

The result.
Returns
Type Description
Task

A representing the ongoing operation.

OnRequestAsync(IHttpContext)

Called to handle a request from a client.

Declaration
protected override sealed Task OnRequestAsync(IHttpContext context)
Parameters
Type Name Description
IHttpContext context

The context of the request being handled.
Returns
Type Description
Task

A representing the ongoing operation.
Overrides

OnStart(CancellationToken)

Called when a module is started, immediately before locking the module's configuration.

Declaration
protected override void OnStart(CancellationToken cancellationToken)
Parameters
Type Name Description
CancellationToken cancellationToken

A used to stop the web server.
Overrides

SendAsync(IWebSocketContext, Byte[])

Sends a binary payload.

Declaration
protected static Task SendAsync(IWebSocketContext context, byte[] payload)
Parameters
Type Name Description
IWebSocketContext context

The web socket.
Byte[] payload

The payload.
Returns
Type Description
Task

A representing the ongoing operation.

SendAsync(IWebSocketContext, String)

Sends a text payload.

Declaration
protected static Task SendAsync(IWebSocketContext context, string payload)
Parameters
Type Name Description
IWebSocketContext context

The web socket.
String payload

The payload.
Returns
Type Description
Task

A representing the ongoing operation.

Implements

IDisposable