StreamSocket 類別

參考

定義

命名空間:: Windows.Networking.Sockets

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

支援在 UWP 應用程式中透過 TCP 或藍牙 RFCOMM 使用串流套接字的網路通訊。

public ref class StreamSocket sealed : IClosable

/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [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)]
class StreamSocket final : 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 StreamSocket final : IClosable

[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[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)]
public sealed class StreamSocket : System.IDisposable

[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 StreamSocket : System.IDisposable

function StreamSocket()

Public NotInheritable Class StreamSocket
Implements IDisposable

繼承: Object Platform::Object IInspectable StreamSocket

屬性: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

實作: IClosable IDisposable

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)
應用程式功能	bluetooth.rfcomm ID_CAP_NETWORKING [Windows Phone] internetClient privateNetworkClientServer

範例

使用此類別的範例應用程式包括藍牙 RFCOMM 聊天範例、DatagramSocket 範例 (Windows 10) 、套接字活動觸發程式串流套接字範例、StreamSocket 範例 (Windows 10) ，以及 Wi-Fi Direct 範例。

備註

StreamSocket 類別支援在 UWP 應用程式中透過 TCP 或藍牙 RFCOMM 使用串流套接字的網路通訊。

針對用戶端應用程式，使用 StreamSocket 最常見的作業順序如下：

建立 StreamSocket。
使用 Control 屬性取得 StreamSocketControl 物件，並在呼叫其中一個 ConnectAsync 方法之前，先在 StreamSocketControl 物件上設定任何屬性。
呼叫其中一個 ConnectAsync 方法，以建立與遠端端端點的連線。針對藍牙，遠端服務名稱是藍牙服務標識符。如果立即需要 TCP 的 SSL/TLS 連線或藍牙的加密層級，則可以使用某些 ConnectAsync 方法來指定。如果在傳送和接收 TCP 套接字的一些初始數據之後需要 SSL/TLS 連線，則稍後可以呼叫 UpgradeToSslAsync 方法來升級連線以使用 SSL。
取得 OutputStream 屬性，以將數據寫入遠端主機。
取得 InputStream 屬性，以從遠端主機讀取數據。
視需要讀取和寫入數據。
呼叫 Close 方法來中斷套接字的連線、中止任何擱置的作業，以及釋放與 StreamSocket 對象相關聯的所有 Unmanaged 資源。

注意

Close 方法是由以 JavaScript 撰寫的 UWP 應用程式使用。針對使用 C# .NET Framework 4.5 撰寫的應用程式，VB.NET，Close 方法會公開為 StreamSocket 上的方法。針對以 C++ 撰寫的應用程式，會在物件上使用 delete 關鍵詞時呼叫 Close 方法。

明確關閉 StreamSocket 物件 (呼叫 Close 方法) 可確保在套接字上沒有擱置的讀取或寫入作業時，正常中斷聯機。所有擱置的讀取都會自動中止，StreamSocket 會等候任何進行中的 I/O 完成，然後再卸除連線。如果在進行中的 I/O 完成之後，套接字上沒有未讀取的數據，則保證會正常中斷連線 (FIN) 。否則，會發生不正常中斷連線 (RST) 。

當作用中的 (仍然連線) StreamSocket 物件超出範圍時，中止 (非正常) 中斷連線可能會導致先前傳送的數據在遠端對等讀取之前遭到捨棄。強烈建議在 JavaScript 中關閉 (Close 方法、C# 中的方法和 VB.NET，或 C++ 中的 delete 運算子) 在 StreamSocket 物件上呼叫，再超出範圍。

每當取消讀取或寫入作業時，I/O 作業會以錯誤狀態完成，且相關聯的 StreamSocket 物件會立即卸除連線，這會導致 RST 中斷聯機 (RST) 如果有任何未讀取或未傳送的數據保留在套接字上。

如果發生異常終止 (應用程式當機) ，則一律會發生不正常連線 (RST) ;或網路堆疊 (偵測到異常連線失敗，例如 TCP 重新傳輸逾時) 。

StreamSocket 物件也會與 StreamSocketListener 物件搭配使用，以接聽伺服器應用程式或點對點應用程式中透過 TCP 或藍牙 RFCOMM 的連入連線。當 StreamSocketListener 物件收到 TCP 或藍牙 RFCOMM 連線要求時，StreamSocket 物件會由 ConnectionReceived 事件的 Socket 屬性傳回。如需詳細資訊，請參閱 StreamSocketListener。

Proxy 的支援

在UWP應用程式中，StreamSocket 類別支援在需要 Proxy才能完成連線時連線到遠端端點。此 Proxy 支援對應用程式而言是自動且透明的。 StreamSocket 可以透過驗證 Proxy 以及不需要驗證的其他 Proxy 建立連線。只有在 Internet Explorer 或 Windows.Web.Http 命名空間中使用 HttpClient 類別的應用程式先前已成功向 Proxy 進行驗證，且先前用於驗證的認證仍然有效時，驗證 Proxy 才能運作。如果 Internet Explorer 以外的網頁瀏覽器用來將驗證認證提供給 Proxy，驗證 Proxy 的支援將無法運作。如果 ConnectAsync 方法上指定了本機主機位址或特定網路適配器，則不支援透過 Proxy 進行連線。

在UWP應用程式中，StreamSocket物件上的 ConnectAsync 方法會嘗試在名稱解析前後探索 Proxy 和目前的 Proxy 組態，以協助加速連線建立。如果為端點指定埠，而不是服務名稱，則會在內部起始 Proxy 探索和名稱解析。如果 Proxy 探索在名稱解析之前完成，且 ProxyConfiguration 物件上的 CanConnectDirectly 屬性為 false，則會嘗試 Proxy 連線。名稱解析完成後，系統會使用解析的端點位址再次起始 Proxy 探索，以判斷目前的 Proxy 組態。如果 CanConnectDirectly 指出應用程式可以直接連線到遠端端點的名稱解析之後，則會直接嘗試套接字連線到端點。如果 CanConnectDirectly 在名稱解析之後為 false ，則會直接嘗試套接字連線到端點，並透過 Proxy 嘗試平行套接字連線。 StreamSocket 會使用第一個成功連線，並取消另一個連線。

在某些情況下，CanConnectDirectly 會傳回 false，但並不表示您無法直接存取資源。局域網路可以設定為同時支援 Proxy 和網路位址轉換， (NAT) 。用來將 Proxy 資訊提供給網頁瀏覽器或 HttpClient 的 WPAD 腳本會告訴 Windows 它應該使用 Proxy。這可能會導致遠端端端點不預期 Proxy 連線 (HTTP CONNECT 要求時發生問題，例如) 。應用程式可以在 NetworkInformation 物件上使用 GetProxyConfigurationAsync 方法，傳遞 uri 參數的遠端端點和埠，以擷取 Proxy 資訊，以協助判斷此條件是否可疑。當伺服器只能處理直接連線時，避免傳送 Proxy 連線要求的方法，就是使用 ConnectAsync (HostName、String、SocketProtectionLevel、NetworkAdapter) 方法，因為選取特定網路適配器時會停用 Proxy 相關邏輯。

在 Windows Phone 8.x 應用程式中，StreamSocket 不提供 Proxy 的自動支援，因為 Windows Phone 不支援 ProxyConfiguration 類別。

處理例外狀況

當您在 StreamSocket 類別上呼叫異步方法時，您必須撰寫程式代碼來處理例外狀況。例外狀況可能是因為參數驗證錯誤、名稱解析失敗和網路錯誤所造成。網路錯誤 (連線中斷、連線失敗和伺服器失敗的例外狀況，例如，隨時可能會發生) 。這些錯誤會造成擲出例外狀況。如果應用程式未處理，例外狀況可能會導致整個應用程式由運行時間終止。

Windows.Networking.Sockets 命名空間具有可簡化使用套接字時處理錯誤的功能。 SocketError 類別上的 GetStatus 方法可以將 HRESULT 從例外狀況轉換為 SocketErrorStatus 列舉值。這對於在您的應用程式中以不同的方式處理特定網路例外狀況時很有用。應用程式也可以使用來自參數驗證錯誤例外狀況的 HRESULT ，深入瞭解造成例外狀況之錯誤的詳細資訊。

如需可能例外狀況以及如何處理例外狀況的詳細資訊，請參閱處理網路應用程式中的例外狀況。

使用 StreamSocket 搭配鄰近性、Wi-Fi Direct 和藍牙

您的應用程式可以使用 StreamSocket 在接近範圍內裝置之間的網路連線。 Windows.Networking.Proximity 命名空間中的類別支援使用 StreamSocket 聯機到使用藍牙或 Wi-Fi Direct 的鄰近裝置的網路連線。 Windows.Networking.Proximity 命名空間中的 PeerFinder 和相關類別可讓您的應用程式探索鄰近裝置上的另一個應用程式實例。 PeerFinder.FindAllPeersAsync 方法會流覽在無線範圍內執行相同應用程式的對等計算機。 PeerFinder.ConnectAsync 方法會傳回連線的 StreamSocket，您的應用程式可用來與附近的對等應用程式傳輸網路數據。如需詳細資訊，請參閱支持鄰近性和點選、 Windows.Networking.Proximity、 PeerFinder 和近接範例。

您的應用程式也可以使用 StreamSocket 在 Windows.Devices.WiFiDirect 命名空間中使用類別 Wi-Fi Direct 的裝置之間的網路連線。 WiFiDirectDevice 類別可用來尋找具有 Wi-Fi Direct (WFD) 裝置的其他裝置。 WiFiDirectDevice.GetDeviceSelector 方法會取得附近 WFD 裝置的裝置標識符。取得鄰近 WFD 裝置的參考之後，您可以呼叫 WiFiDirectDevice.GetConnectionEndpointPairs 方法來取得 EndpointPair 物件。 StreamSocket 類別上的 ConnectAsync (EndpointPair) 或 ConnectAsync (EndpointPair、 SocketProtectionLevel) 方法可用來建立套接字聯機。如需詳細資訊，請參閱 Windows.Devices.WiFiDirect 和 WiFiDirectDevice。

藍牙使用藍牙服務標識碼作為 StreamSocket 連線的端點，而不是主機名或 IP 位址。若要搭配藍牙使用 StreamSocket，必須在應用程式指令清單中設定 bluetooth.rfcomm 裝置功能。如需詳細資訊，請參閱 Windows.Devices.Bluetooth.Rfcomm 命名空間、如何指定藍牙的裝置功能，以及藍牙 Rfcomm 聊天範例。

在 Windows Server 2012 上使用 StreamSocket

在 Windows Server 2012 和 Windows Server 2012 R2 上，除非啟用媒體基礎功能，否則實作 Windows.Networking.Sockets 命名空間中大部分類別的 Windows.Networking.dll 將無法載入。因此，如果停用 Media Foundation 功能，則 Windows.Networking.Sockets 命名空間中使用 StreamSocket 和相關套接字類別的應用程式將會失敗。 Windows Server 2012 或 Windows Server 2012 R2 安裝，並停用 Media Foundation 功能。

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

dism /online /enable-feature /featurename:ServerMediaFoundation 啟用 Media Foundation 功能之後，系統會提示使用者重新啟動。重新啟動計算機之後， Windows.Networking.Sockets 命名空間中的套接字和 WebSocket 類別會如預期般運作。

使用 StreamSocket 解析 DNS 服務記錄

應用程式可以與屬於 SRV 記錄的目標 DNS 位址通訊。例如，Contoso 網域中的可延伸傳訊和目前狀態通訊協定 (XMPP) 服務會對應至 _xmpp-client._tcp.contoso.com。這個服務名稱會對應至伺服器 DNS 名稱， xmpp-client01.contoso.com 例如。

若要連線到該服務伺服器的 DNS 位址，請在 StreamSocket 實例上使用下列方法呼叫：

using Windows.Networking.Sockets;

StreamSocket socket = new StreamSocket();
socket.ConnectAsync(new HostName("contoso.com"), "xmpp-client");

此通訊協定會推斷為 StreamSocket 實例的 TCP。方法會處理底線字元。

DNS 可以設定為具有SRV階層。 DNS SRV 資源記錄的格式可能如下： _xmpp-client._service01._tcp.contoso.com。在此範例中，請在 StreamSocket 實例上使用下列方法呼叫：

socket.ConnectAsync(new HostName("contoso.com"), "xmpp-client._service01");

這些代碼段會使用 ConnectAsync。 GetEndpointPairsAsync 方法支援與服務連線的類似用法。

版本歷程記錄

Windows 版本	SDK 版本	新增值
1607	14393	GetEndpointPairsAsync (HostName，String)
1607	14393	GetEndpointPairsAsync (HostName，String，HostNameSortOptions)

建構函式

StreamSocket()

建立新的 StreamSocket 物件。

屬性

Control	取得 StreamSocket 物件上的套接字控制項數據。
Information	取得 StreamSocket 物件的套接字資訊。
InputStream	取得從 StreamSocket 物件上的遠端目的地讀取的輸入數據流。
OutputStream	取得輸出數據流，以寫入 StreamSocket 物件上的遠端主機。

方法

CancelIOAsync()	取消 StreamSocket 物件的暫止讀取和寫入。
Close()	關閉 StreamSocket 物件。
ConnectAsync(EndpointPair)	在 StreamSocket 對象上啟動異步操作，以連線到指定為 EndpointPair 物件的遠端網路目的地。
ConnectAsync(EndpointPair, SocketProtectionLevel)	在 StreamSocket 對象上啟動異步操作，以連線到指定為 EndpointPair 物件和 SocketProtectionLevel 列舉的遠端網路目的地。這個方法無法從 JavaScript 呼叫。
ConnectAsync(HostName, String)	在 StreamSocket 物件上啟動異步操作，以連線到遠端主機名和遠端服務名稱所指定的遠端網路目的地。
ConnectAsync(HostName, String, SocketProtectionLevel)	在 StreamSocket 對象上啟動異步操作，以連線到遠端主機名、遠端服務名稱和 SocketProtectionLevel 所指定的遠端目的地。
ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)	在指定的局域網路卡上啟動 StreamSocket 物件的異步操作，以連線到遠端主機名、遠端服務名稱和 SocketProtectionLevel 所指定的遠端目的地。
Dispose()	執行與釋放 (Free)、釋放 (Release) 或重設 Unmanaged 資源相關聯之應用程式定義的工作。
EnableTransferOwnership(Guid)	當此 StreamSocket 的流量在應用程式未使用時送達時，讓套接字代理程式觸發應用程式的背景工作。
EnableTransferOwnership(Guid, SocketActivityConnectedStandbyAction)	啟用或停用當系統處於連線待命狀態時，當此 StreamSocket 的流量到達時，套接字代理程式觸發應用程式的背景工作的能力。
GetEndpointPairsAsync(HostName, String)	根據可用來將 TCP 封包傳送至遠端網路目的地的遠端主機名和遠端服務名稱，取得 EndpointPair 物件清單。
GetEndpointPairsAsync(HostName, String, HostNameSortOptions)	根據遠端主機名和遠端服務名稱和要使用的排序順序，取得 EndpointPair 物件清單。
TransferOwnership(String)	將 StreamSocket 的擁有權轉移至套接字代理服務，這會監視套接字活動，並在有任何活動時透過背景工作通知應用程式。
TransferOwnership(String, SocketActivityContext)	將 StreamSocket 的擁有權轉移至套接字代理服務，這會監視套接字活動，並在有任何活動時透過背景工作通知應用程式。指定套接字的新 SocketActivityContext 。
TransferOwnership(String, SocketActivityContext, TimeSpan)	將 StreamSocket 的擁有權轉移至套接字代理服務，這會監視套接字活動，並在有任何活動時透過背景工作通知應用程式。指定新的 SocketActivityContext 和套接字的保持運作時間。
UpgradeToSslAsync(SocketProtectionLevel, HostName)	啟動異步操作，以升級連接的套接字，以在 StreamSocket 物件上使用 SSL。

適用於

共用方式為