Windows.Networking.Sockets 命名空间

重要

一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

编辑

提供套接字和 WebSocket 类，用于网络通信和类，用于在后台为打包Windows应用（包括 UWP 和 Windows 应用 SDK （WinUI 3）桌面应用接收的实时网络通知）。

类

名称	说明
ControlChannelTrigger	允许在后台接收建立 TCP 连接的对象的实时通知，并希望收到传入流量的通知。在使用 ControlChannelTrigger 之前，先调用 “BackgroundExecutionManager.RequestAccessAsync”。
DatagramSocket	支持使用 UDP 数据报套接字进行网络通信。有关代码示例，请参阅套接字。
DatagramSocketControl	在 DatagramSocket 对象上提供套接字控制数据。
DatagramSocketInformation	提供有关 DatagramSocket 对象的套接字信息。
DatagramSocketMessageReceivedEventArgs	为 DatagramSocket 上的 MessageReceived 事件提供数据。
MessageWebSocket	支持使用 WebSocket 读取和写入整个消息的网络通信。
MessageWebSocketControl	在 MessageWebSocket 上提供套接字控制数据。
MessageWebSocketInformation	提供有关 MessageWebSocket 的套接字信息。
MessageWebSocketMessageReceivedEventArgs	为 MessageWebSocket 上收到的消息事件提供数据。
ServerMessageWebSocket	支持使用 Web 服务器拥有的 WebSocket 对象读取和写入整个消息的网络通信。无法注册任意 WebSocket 连接;相反，ServerMessageWebSocket 的实例是由系统代码（例如Windows设备门户（WDP）创建的。
ServerMessageWebSocketControl	在 ServerMessageWebSocket 上提供套接字控制数据。
ServerMessageWebSocketInformation	提供有关 ServerMessageWebSocket 的套接字信息。
ServerStreamWebSocket	支持网络通信，允许使用 Web 服务器拥有的 WebSocket 对象读取和写入流。无法注册任意 WebSocket 连接;而是由系统代码（如 Windows 设备门户（WDP）创建 ServerStreamWebSocket 实例。
ServerStreamWebSocketInformation	提供有关 ServerStreamWebSocket 对象的套接字信息。
SocketActivityContext	在应用与套接字代理服务之间传输套接字所有权时，与套接字关联的上下文。
SocketActivityInformation	提供有关套接字代理中传输的套接字的信息。
SocketActivityTriggerDetails	由后台代理基础结构实例化的对象，由应用用来检索 SocketActivityTrigger 发生时的详细信息。
SocketError	为 DatagramSocket、StreamSocket 或 StreamSocketListener 上的操作提供套接字错误状态。
StreamSocket	支持在 UWP 应用中通过 TCP 或蓝牙 RFCOMM 使用流套接字进行网络通信。
StreamSocketControl	在 StreamSocket 对象上提供套接字控制数据。
StreamSocketInformation	提供有关 StreamSocket 对象的套接字信息。
StreamSocketListener	支持使用 TCP 流套接字或蓝牙 RFCOMM 侦听传入网络连接。
StreamSocketListenerConnectionReceivedEventArgs	为 StreamSocketListener 对象上的 ConnectionReceived 事件提供数据。
StreamSocketListenerControl	在 StreamSocketListener 对象上提供套接字控制数据。
StreamSocketListenerInformation	提供有关 StreamSocketListener 对象的套接字信息。
StreamWebSocket	支持使用 WebSocket 读取和写入流的网络通信。
StreamWebSocketControl	在 StreamWebSocket 对象上提供套接字控制数据。
StreamWebSocketInformation	提供有关 StreamWebSocket 对象的套接字信息。
WebSocketClosedEventArgs	为 MessageWebSocket、StreamWebSocket 或 IWebSocket 对象上的已关闭事件提供数据。
WebSocketError	在 MessageWebSocket 或 StreamWebSocket 对象上提供套接字错误状态。
WebSocketKeepAlive	提供在连接的 WebSocket 上发送 WebSocket 协议保持活动状态的功能。
WebSocketServerCustomValidationRequestedEventArgs	为 WebSocket 上的 ServerCustomValidationRequested 事件提供数据。在建立与 WebSocket 的新安全连接时，会发生此事件，并让代码有机会在建立连接之前对服务器证书执行自定义验证。

结构

名称	说明
BandwidthStatistics	表示使用 StreamSocket、 StreamWebSocket 或 MessageWebSocket 对象进行网络数据传输的带宽信息。
RoundTripTimeStatistics	表示 StreamSocket 对象的往返时间信息。

接口

名称	说明
IControlChannelTriggerEventDetails	由后台代理基础结构实例化的对象，用于区分控制通道触发器。
IControlChannelTriggerResetEventDetails	由 ControlChannelReset 事件的后台代理基础结构实例化的对象，指示 ControlChannelTrigger 已重置。
IWebSocket	提供对允许使用 WebSocket 进行读取和写入的网络通信的访问。
IWebSocketControl	在 IWebSocket 对象上提供套接字控制数据。
IWebSocketControl2	在 IWebSocket 对象上提供套接字控制数据。此接口使用附加属性扩展 IWebSocketControl 接口。
IWebSocketInformation	提供有关 IWebSocket 对象的套接字信息。
IWebSocketInformation2	提供有关 IWebSocket 对象的套接字信息。此接口使用其他属性扩展 IWebSocketInformation 。

枚举

名称	说明
ControlChannelTriggerResetReason	重置 ControlChannelTrigger 的原因。
ControlChannelTriggerResourceType	控制通道触发器使用的资源类型。
ControlChannelTriggerStatus	指定系统是否能够完成 ControlChannelTrigger 对象的配置，以供Windows中的类元素使用。Networking.Sockets 和相关命名空间。
MessageWebSocketReceiveMode	描述客户端将接受的消息类型。
SocketActivityConnectedStandbyAction	指示当系统进入连接状态时，使用套接字代理服务的应用是否可以接收数据包。
SocketActivityKind	描述要传输到套接字代理或从套接字代理传输的套接字对象类型。
SocketActivityTriggerReason	SocketActivityTrigger 发生的原因。
SocketErrorStatus	指定套接字操作的状态值。
SocketMessageType	指定 MessageWebSocket 对象的消息类型。
SocketProtectionLevel	指定要在 StreamSocket 对象上使用的加密级别。
SocketQualityOfService	指定 DatagramSocket 或 StreamSocket 对象的服务质量。
SocketSslErrorSeverity	SSL 连接上发生的错误类别。

注解

注释

应用框架兼容性：Windows。Networking.Sockets API 可用于Windows 应用 SDK（WinUI 3）桌面应用和 Win32 桌面应用，而不仅仅是 UWP 应用。打包的桌面应用使用与 UWP 应用相同的网络功能声明。未打包的桌面应用具有不受限制的网络访问，无需声明功能。有关指南，请参阅在桌面应用中调用Windows 运行时 API。

Windows。Networking.Sockets 命名空间为使用套接字和 WebSocket 的网络提供类和接口。下面是主类。

DatagramSocket。用于网络通信的 UDP 数据报套接字。
StreamSocket。用于通过 TCP 或通过使用 RFCOMM 的蓝牙连接进行传入或传出网络通信的流套接字。
StreamSocketListener。一个流套接字侦听器，用于侦听使用 RFCOMM 的传入 TCP 网络连接或传入蓝牙连接。
MessageWebSocket。一个基于消息的 WebSocket，用于读取和写入用于网络通信的整个消息。请参阅 WebSocket。
StreamWebSocket。一个基于流的 WebSocket，用于读取和写入网络通信的流。请参阅 WebSocket。

这些主类在Windows中还具有许多相关信息和控件类。Networking.Sockets 命名空间。

处理异常

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

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

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

将 StreamSocket 与邻近感应、Wi-Fi Direct 和蓝牙配合使用

你的应用可以使用 StreamSocket 在接近范围内的设备之间建立网络连接。 Windows中的类。Networking.Proximity 命名空间支持使用 StreamSocket 与使用蓝牙或 Wi-Fi Direct 的邻近设备建立网络连接。 Windows中的 PeerFinder 和相关类。Networking.Proximity 命名空间允许应用在附近的设备上发现应用的另一个实例。 PeerFinder.FindAllPeersAsync 方法可浏览在无线范围内运行同一应用的对等计算机。 PeerFinder.ConnectAsync 方法返回一个连接的 StreamSocket，应用可用于将网络数据与附近的对等应用传输。有关详细信息，请参阅支持邻近感应和点击，Windows。Networking.Proximity、PeerFinder 和邻近感应示例。

你的应用还可以将 StreamSocket 用于 Wi-Fi Direct 与Windows中的类的设备之间的网络连接。Devices.WiFiDirect 命名空间。 WiFiDirectDevice 类可用于查找具有 Wi-Fi Direct（WFD）功能设备的其他设备。 WiFiDirectDevice.GetDeviceSelector 方法获取附近 WFD 设备的设备标识符。对附近的 WFD 设备的引用后，可以调用 WiFiDirectDevice.GetConnectionEndpointPairs 方法以获取 EndpointPair 对象。然后，可以使用 StreamSocket 类上的 ConnectAsync（EndpointPair、SocketProtectionLevel）或 ConnectAsync（EndpointPair、SocketProtectionLevel）方法建立套接字连接。有关详细信息，请参阅Windows。Devices.WiFiDirect 和 WiFiDirectDevice。

蓝牙使用蓝牙服务 ID 作为 StreamSocket 连接的终结点，而不是主机名或 IP 地址。若要将 StreamSocket 与蓝牙配合使用，必须在应用清单中设置 bluetooth.rfcomm 设备功能。有关详细信息，请参阅Windows。Devices.Bluetooth.Rfcomm 命名空间、如何为蓝牙指定设备功能以及蓝牙 Rfcomm Chat 示例。

将 DatagramSocket 与 Wi-Fi Direct 配合使用

你的应用可以使用 DatagramSocket 在使用 Windows 中的类 Wi-Fi Direct 的设备之间进行网络数据传输。Devices.WiFiDirect 命名空间。 WiFiDirectDevice 类可用于查找具有 Wi-Fi Direct（WFD）功能设备的其他设备。 WiFiDirectDevice.GetDeviceSelector 方法获取附近 WFD 设备的设备标识符。对附近的 WFD 设备的引用后，可以调用 WiFiDirectDevice.GetConnectionEndpointPairs 方法以获取 EndpointPair 对象。 DatagramSocket 类上的方法可用于向 EndpointPair 对象发送和接收数据。有关详细信息，请参阅Windows。Devices.WiFiDirect 和 WiFiDirectDevice。

使用网络触发器

Windows。Networking.Sockets 命名空间提供两种类型的触发器，应用可用于后台网络：ControlChannelTrigger 和 SocketActivityTrigger。

控制通道触发器

ControlChannelTrigger 允许应用在后台时接收网络数据包和网络保留。这使你的应用能够在Windows中为 StreamSocket 提供实时状态和网络通知。Networking.Sockets 命名空间和相关命名空间中的其他网络类。

长时间运行的网络应用（例如电子邮件应用）使用网络触发器，以最大程度地减少网络和系统资源使用情况。网络触发器允许应用在一段时间内下降到低功率模式，使网络连接保持不变，但处于低功率状态。可以设置一个保持间隔，让系统知道应用何时应唤醒。还可以设置一个触发器，以便在为应用接收数据包时收到通知。在移动设备上使用长时间运行的网络应用时，这些通知功能可以帮助延长电池使用时间。

有关详细信息，请参阅 ControlChannelTrigger 类和如何设置后台连接选项。

套接字活动触发器

SocketActivityTrigger 允许应用在未处于活动状态（即使它被暂停或终止）时接收网络数据包，即使它当前未加载到内存中。它特别适用于提供网络服务的应用，其中应用将通过 DNS-SD 注册为服务提供商，然后变为非活动状态。当客户端连接到服务时， SocketActivityTrigger 会通知应用，以便该服务可以激活并提供请求的服务。 SocketActivityTrigger 也可以在其他情况下使用。每当你想要能够激活应用以响应收到的网络流量时使用它。

如果应用使用套接字活动触发器，则必须在应用清单中指定 pushNotifications 功能。

选择网络触发器

在某些情况下，任一类型的触发器都适用。选择要在应用中使用的触发器类型时，请考虑以下建议。

如果使用 IXMLHTTPRequest2、 System.Net.Http.HttpClient 或 System.Net.Http.HttpClientHandler，则必须使用 ControlChannelTrigger。
如果使用启用了推送的 StreamSocket，首选 SocketActivityTrigger。它允许系统在未主动使用连接时释放内存并降低电源要求。
如果要在应用未主动为网络请求提供服务时尽量减少应用的内存占用量，首选 SocketActivityTrigger。
如果希望应用能够在系统处于连接待机模式时接收数据，请使用 SocketActivityTrigger。

在 Windows Server 2012 上使用套接字和 WebSocket

在 Windows Server 2012 和 Windows Server 2012 R2 上，实现Windows中大多数类的 Windows.Networking.dll。除非启用了 Media Foundation 功能，否则 Networking.Sockets 命名空间将无法加载。因此，使用Windows中的套接字或 WebSocket 类的应用。如果禁用媒体基础功能，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 命名空间将按预期工作。

将套接字和 WebSocket 与网络隔离配合使用

Windows中的网络隔离使你可以完全控制打包应用（包括 UWP 和打包Windows 应用 SDK（WinUI 3）桌面应用）的安全配置文件。

通过网络隔离，可以通过选择相应的功能来定义每个应用所需的网络访问。没有适当功能集的应用被阻止使用特定的网络类型（Internet 或家庭/工作网络）和特定的网络请求（出站客户端发起的请求，或入站未经请求的请求和出站客户端发起的请求）。强制实施网络隔离的功能可确保即使应用遭到入侵，应用也只能使用应用（例如网络类型和网络请求）作为功能授予的功能。这大大减少了对其他应用和操作系统的潜在影响。

Windows主动强制实施网络隔离。对方法的调用或对Windows中属性的任何访问。如果未启用适当的网络功能，则 Networking.Sockets 命名空间（或需要网络访问的相关命名空间）可能会失败。

生成应用时，应用的网络功能在应用清单中配置。开发应用时，通常使用Visual Studio添加网络功能。还可以使用文本编辑器在应用清单文件中手动设置它们。未打包的桌面应用不受网络隔离的约束，也不需要声明网络功能。

有关网络隔离的更多详细信息，请参阅如何配置网络隔离功能。

另请参阅

反馈

此页面是否有帮助？