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 需求

規格需求	Description
裝置系列	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 命名空間提供方便的輔助方法與列舉方式，用於處理使用 WebSockets 時的錯誤。 這對於在應用程式中處理特定網路例外的方式很有幫助。 應用程式也可以利用例外中對參數驗證錯誤的 HRESULT 來學習導致異常的更詳細資訊。

欲了解更多可能例外及如何處理例外的資訊，請參閱 「網路應用程式中的例外處理」。

在 Windows Server 2012 上使用 MessageWebSocket

在 Windows Server 2012 和 Windows Server 2012 R2，這是實作大部分 Windows 類別的 Windows.Networking.dll。Networking.Sockets 命名空間若未啟用 Media Foundation 功能，將無法載入。 因此，使用MessageWebSocket及相關WebSocket類別的應用程式在Windows中，如果關閉 Media Foundation 功能，Networking.Sockets 命名空間將會失敗。 Windows Server 2012 或 Windows Server 2012 R2 安裝時，關閉了媒體基礎功能。

媒體基礎功能可在 Windows Server 2012 或 Windows Server 2012 R2 上啟用，使用 伺服器管理員，或透過命令提示字元或腳本輸入以下文字：

dism /online /enable-feature /featurename:ServerMediaFoundation 啟用 Media Foundation 功能後，使用者會被提示重新啟動。 電腦重新啟動後，Windows 中會建立 sockets 和 WebSockets 的類別。Networking.sockets 命名空間會如預期運作。

版本歷程記錄

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

建構函式

名稱	Description
MessageWebSocket()	建立一個新的 MessageWebSocket 物件。

屬性

名稱	Description
Control	取得 MessageWebSocket 物件上的套接字控制資料。
Information	取得 MessageWebSocket 物件的套接字資訊。
OutputStream	取得輸出串流，寫入遠端網路目的地的 MessageWebSocket 物件。

方法

名稱	Description
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)	在 MessageWebSocket 物件所使用的 HTTP請求訊息中，為WebSocket協定握手時新增HTTP請求標頭。

事件

名稱	Description
Closed	當 MessageWebSocket 物件作為密切握手的一部分接收到接近的框架時，會發生這種情況。
MessageReceived	一個表示 MessageWebSocket 物件已收到訊息的事件。
ServerCustomValidationRequested	當一個新的 MessageWebSocket 連線到安全伺服器 URI（wss： 協定）正在驗證時發生。 如果你想為連線實作自訂伺服器驗證，就處理這個事件。

另請參閱

• MessageWebSocketControl
• MessageWebSocketInformation
• StreamWebSocket
• WebSockets
• 處理網路應用程式中的例外
• WebSocket 範例