MessageWebSocket 类

定义

命名空间:

Windows.Networking.Sockets

支持使用 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

继承

Object Platform::Object IInspectable MessageWebSocket

属性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

实现

IClosable IDisposable IWebSocket

Windows 要求

要求	说明
设备系列	Windows 10 (在 10.0.10240.0 中引入)
API contract	Windows.Foundation.UniversalApiContract (在 v1.0 中引入)
应用功能	internetClient privateNetworkClientServer

注解

MessageWebSocket 类提供基于消息的 WebSocket 协议抽象。 使用 MessageWebSocket 时，整个 WebSocket 消息在单个操作中读取或写入。 相比之下， StreamWebSocket 允许使用每个读取操作读取消息部分，而无需在单个操作中读取整个消息。

对于 UTF-8 消息，必须使用 MessageWebSocket。 StreamWebSocket 仅支持二进制消息。

处理异常

在 MessageWebSocket 类上调用异步方法时，必须编写代码来处理异常。 异常可能是由参数验证错误、名称解析失败和网络错误导致的。 网络错误（例如连接丢失、连接失败和 HTTP 服务器故障）可能会随时发生异常。 这些错误会导致引发异常。 如果应用未处理，异常可能会导致整个应用被运行时终止。

Windows。Networking.Sockets 命名空间具有一种方便的帮助程序方法和枚举，用于处理使用 WebSocket 时的错误。 这可用于在应用中以不同的方式处理特定网络异常。 应用还可以使用来自参数验证错误的异常中的 HRESULT 来了解有关导致异常的错误的更多详细信息。

有关可能的异常以及如何处理异常的详细信息，请参阅 在网络应用中处理异常。

在 Windows Server 2012 上使用 MessageWebSocket

在 Windows Server 2012 和 Windows Server 2012 R2 上，实现Windows中大多数类的 Windows.Networking.dll。除非启用了 Media Foundation 功能，否则 Networking.Sockets 命名空间将无法加载。 因此，使用 MessageWebSocket 和相关 WebSocket 类的应用在Windows。如果禁用媒体基础功能，Networking.Sockets 命名空间将失败。 禁用媒体基础功能Windows Server 2012或Windows Server 2012 R2 安装。

可以使用服务器管理器或在命令提示符或脚本中输入以下文本，在 Windows Server 2012 或 Windows Server 2012 R2 上启用媒体基础功能：

dism /online /enable-feature /featurename:ServerMediaFoundation 启用媒体基础功能后，系统会提示用户重启。 重启计算机后，Windows中套接字和 WebSocket 的类。Networking.Sockets 命名空间将按预期工作。

版本历史记录

Windows 版本	SDK 版本	附加值
1607	14393	ServerCustomValidationRequested
1803	17134	SendFinalFrameAsync
1803	17134	SendNonfinalFrameAsync

构造函数

名称	说明
MessageWebSocket()	创建新的 MessageWebSocket 对象。

属性

名称	说明
Control	获取 MessageWebSocket 对象上的套接字控件数据。
Information	获取 MessageWebSocket 对象的套接字信息。
OutputStream	获取要写入 MessageWebSocket 对象上的远程网络目标的输出流。

方法

名称	说明
Close()	关闭 MessageWebSocket 对象，并向服务器发送一个空的关闭帧。
Close(UInt16, String)	关闭 MessageWebSocket 对象，并指示关闭的原因。
ConnectAsync(Uri)	启动异步操作以连接到 MessageWebSocket 对象上的远程网络目标。
Dispose()	执行与释放、释放或重置非托管资源关联的应用程序定义任务。
SendFinalFrameAsync(IBuffer)	异步（具有进度）在顺序流中写入数据帧，其语义是 WebSocket 消息中的最后一帧（此帧上的 FIN 位设置为 1）。 此方法和 SendNonfinalFrameAsync 允许发送单个 WebSocket 帧。
SendNonfinalFrameAsync(IBuffer)	异步（随着进度）在顺序流中写入一帧数据，该帧将遵循更多帧的语义，用于相同的 WebSocket 消息（此帧上的 FIN 位设置为 0）。 此方法和 SendFinalFrameAsync 允许发送单个 WebSocket 帧。
SetRequestHeader(String, String)	将 HTTP 请求标头添加到 MessageWebSocket 对象在 WebSocket 协议握手中使用的 HTTP 请求消息。

事件

名称	说明
Closed	当 在 MessageWebSocket 对象上收到关闭帧作为关闭握手的一部分时发生。
MessageReceived	指示在 MessageWebSocket 对象上收到消息的事件。
ServerCustomValidationRequested	在验证到安全服务器 URI（wss： 协议）的新 MessageWebSocket 连接时发生。 如果要为连接实现自定义服务器验证，请处理此事件。

另请参阅

• MessageWebSocketControl
• MessageWebSocketInformation
• StreamWebSocket
• WebSockets
• 处理网络应用中的异常
• WebSocket 示例