MessageWebSocket Class

Definition

Namespace:

Windows.Networking.Sockets

Supports network communication that allows reading and writing whole messages using a WebSocket.

public ref class MessageWebSocket sealed : IClosable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class MessageWebSocket final : IClosable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class MessageWebSocket : System.IDisposable

function MessageWebSocket()

Public NotInheritable Class MessageWebSocket
Implements IDisposable

Inheritance

Object Platform::Object IInspectable MessageWebSocket

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements

IClosable IDisposable IWebSocket

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)
App capabilities	internetClient privateNetworkClientServer

Remarks

The MessageWebSocket class provides a message-based abstraction of the WebSocket protocol. When using MessageWebSocket, the entire WebSocket message is read or written in a single operation. In contrast, the StreamWebSocket allows sections of a message to be read with each read operation, rather than requiring the entire message to be read in a single operation.

For UTF-8 messages, MessageWebSocket must be used. StreamWebSocket only supports binary messages.

Handling exceptions

You must write code to handle exceptions when you call asynchronous methods on the MessageWebSocket class. Exceptions can result from parameter validation errors, name resolutions failures, and network errors. Exceptions from network errors (loss of connectivity, connection failures, and HTTP server failures, for example) can happen at any time. These errors result in exceptions being thrown. If not handled by your app, an exception can cause your entire app to be terminated by the runtime.

The Windows.Networking.Sockets namespace has a convenient helper method and enumeration for handling errors when using WebSockets. This can be useful for handling specific network exceptions differently in your app. An app can also use the HRESULT from the exception on parameter validation errors to learn more detailed information on the error that caused the exception.

For more information on possible exceptions and how to handle exceptions, see Handling exceptions in network apps.

Using MessageWebSocket on Windows Server 2012

On Windows Server 2012 and Windows Server 2012 R2, the Windows.Networking.dll that implements most of the classes in the Windows.Networking.Sockets namespace will fail to load unless the Media Foundation feature is enabled. As a result, apps that use MessageWebSocket and related WebSocket classes in the Windows.Networking.Sockets namespace will fail if the Media Foundation feature is disabled. Windows Server 2012 or Windows Server 2012 R2 installs with the Media Foundation feature disabled.

The Media Foundation feature can be enabled on Windows Server 2012 or Windows Server 2012 R2 using Server Manager or by entering the following text in a command prompt or a script:

dism /online /enable-feature /featurename:ServerMediaFoundation After the Media Foundation feature is enabled, the user is prompted to restart. Once the computer is restarted, classes for sockets and WebSockets in the Windows.Networking.Sockets namespace will work as expected.

Version history

Windows version	SDK version	Value added
1607	14393	ServerCustomValidationRequested
1803	17134	SendFinalFrameAsync
1803	17134	SendNonfinalFrameAsync

Constructors

MessageWebSocket()

Creates a new MessageWebSocket object.

Properties

Control	Gets socket control data on a MessageWebSocket object.
Information	Gets socket information on a MessageWebSocket object.
OutputStream	Gets the output stream to write to the remote network destination on a MessageWebSocket object.

Methods

Close()	Closes the MessageWebSocket object and sends an empty close frame to the server.
Close(UInt16, String)	Closes the MessageWebSocket object and indicates a reason for the closure.
ConnectAsync(Uri)	Starts an asynchronous operation to connect to a remote network destination on a MessageWebSocket object.
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
SendFinalFrameAsync(IBuffer)	Asynchronously (with progress) writes a frame of data in a sequential stream, with the semantics that this is the last frame in a WebSocket message (the FIN bit on this frame is set to 1). This method and SendNonfinalFrameAsync allow you to send individual WebSocket frames.
SendNonfinalFrameAsync(IBuffer)	Asynchronously (with progress) writes a frame of data in a sequential stream, with the semantics that more frames will follow for the same WebSocket message (the FIN bit on this frame is set to 0). This method and SendFinalFrameAsync allow you to send individual WebSocket frames.
SetRequestHeader(String, String)	Adds an HTTP request header to the HTTP request message used in the WebSocket protocol handshake by the MessageWebSocket object.

Events

Closed	Occurs when a close frame is received on the MessageWebSocket object as part of the close handshake.
MessageReceived	An event that indicates that a message was received on the MessageWebSocket object.
ServerCustomValidationRequested	Occurs when a new MessageWebSocket connection to a secured server URI (wss: protocol) is being validated. Handle this event if you want to implement custom server validation for the connection.

See also

• MessageWebSocketControl
• MessageWebSocketInformation
• StreamWebSocket
• WebSockets
• Handling exceptions in network apps
• WebSocket sample