Socket.ConnectAsync 方法

定义

开始一个对远程主机连接的异步请求。

重载

ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs)

开始一个对远程主机连接的异步请求。

ConnectAsync(IPAddress[], Int32, CancellationToken)

与远程主机建立连接。

ConnectAsync(String, Int32, CancellationToken)

与远程主机建立连接。

ConnectAsync(IPAddress, Int32, CancellationToken)

与远程主机建立连接。

ConnectAsync(String, Int32)

与远程主机建立连接。

ConnectAsync(IPAddress[], Int32)

与远程主机建立连接。

ConnectAsync(IPAddress, Int32)

与远程主机建立连接。

ConnectAsync(EndPoint, CancellationToken)

与远程主机建立连接。

ConnectAsync(SocketAsyncEventArgs)

开始一个对远程主机连接的异步请求。

ConnectAsync(EndPoint)

与远程主机建立连接。

ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs)

Source:
Socket.cs
Source:
Socket.cs
Source:
Socket.cs

开始一个对远程主机连接的异步请求。

public static bool ConnectAsync (System.Net.Sockets.SocketType socketType, System.Net.Sockets.ProtocolType protocolType, System.Net.Sockets.SocketAsyncEventArgs e);

参数

socketType
SocketType

SocketType 值之一。

protocolType
ProtocolType

ProtocolType 值之一。

e
SocketAsyncEventArgs

要用于此异步套接字操作的 SocketAsyncEventArgs 对象。

返回

如果 I/O 操作挂起,则为 true。 操作完成时,将引发 e 参数的 Completed 事件。

如果 I/O 操作同步完成,则为 false。 在这种情况下,将不会引发 e 参数的 Completed 事件,并且可能在方法调用返回后立即检查作为参数传递的 e 对象以检索操作的结果。

例外

自变量无效。 如果指定了多个缓冲区,即 BufferList 属性不为 null,将会发生此异常。

e 参数不能为 null,并且 RemoteEndPoint 不能为空。

Socket 正在侦听或已经在使用 e 参数中指定的 SocketAsyncEventArgs 对象执行套接字操作。

尝试访问套接字时出错。

本地终结点和 RemoteEndPoint 不是同一个地址系列。

调用堆栈中的较高调用方无权执行所请求的操作。

注解

如果使用面向连接的协议,则 M:System.Net.Sockets.Socket.ConnectAsync (System.Net.Sockets.SocketType,System.Net.Sockets.ProtocolType,System.Net.Sockets.SocketAsyncEventArgs) 方法启动与远程主机连接的异步请求。 如果使用无连接协议, ConnectAsync 将建立由 socketTypeprotocolType 参数指定的默认远程主机。

若要收到完成通知,必须创建实现 EventHandler<SocketAsyncEventArgs> 委托的回调方法,并将回调附加到 SocketAsyncEventArgs.Completed 事件。

调用方必须将 属性设置为SocketAsyncEventArgs.RemoteEndPointIPEndPoint要连接到的远程主机的 。

调用方可以在调用ConnectAsync方法之前将 SocketAsyncEventArgs.UserToken 属性设置为所需的任何用户状态对象,以便可在回调方法中检索信息。 如果回调需要比单个对象更多的信息,则可以创建一个小类来保存其他所需的状态信息作为成员。

如果使用 UDP 等无连接协议,则不必在发送和接收数据之前调用 ConnectAsync 。 可以使用 SendToAsyncReceiveFromAsync 与远程主机通信。 如果确实调用 ConnectAsync,则将放弃从指定默认值以外的地址到达的任何数据报。 如果要更改默认远程主机,请使用所需的终结点再次调用 ConnectAsync 方法。

如果要将默认远程主机设置为广播地址,必须首先调用 SetSocketOption 并将 Broadcast 设置为 true。 如果未完成此操作,该方法 ConnectAsync 将引发 SocketException

对象需要 System.Net.Sockets.SocketAsyncEventArgs 以下属性和事件:

(可选)可以提供缓冲区,该方法成功后 ConnectAsync 将在套接字上以原子方式发送。 在这种情况下,需要将 SocketAsyncEventArgs.Buffer 属性设置为包含要发送的数据的缓冲区, SocketAsyncEventArgs.Count 而 属性需要设置为要从缓冲区发送的数据的字节数。 建立连接后,发送此数据缓冲区。

如果使用面向连接的协议,并且未在调用 ConnectAsync之前调用 Bind ,则基础服务提供商将分配最合适的本地网络地址和端口号。

如果使用无连接协议,则在你调用 SendAsyncReceiveAsync 方法之前,服务提供商不会分配本地网络 IP 地址和端口号。

ConnectAsync如果 和 SocketAsyncEventArgs.RemoteEndPointSocket地址系列不在同一地址系列,则引发 NotSupportedException 方法。

备注

如果在调用此方法时收到 SocketException ,请使用 SocketException.ErrorCode 属性获取特定的错误代码。 获取此代码后,请参阅 Windows 套接字版本 2 API 错误代码 文档,获取错误的详细说明。

适用于

.NET 9 和其他版本
产品 版本
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

ConnectAsync(IPAddress[], Int32, CancellationToken)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.ValueTask ConnectAsync (System.Net.IPAddress[] addresses, int port, System.Threading.CancellationToken cancellationToken);

参数

addresses
IPAddress[]

将用于尝试连接到远程主机的远程主机的 IPAddresses 列表。

port
Int32

要连接到的远程主机上的端口。

cancellationToken
CancellationToken

可用于取消异步操作的取消标记。

返回

建立连接时完成的异步任务。

例外

addresses 参数不能为 NULL。

参数 addresses 不能为空数组。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

调用堆栈中的较高调用方无权执行所请求的操作。

取消令牌已取消。 此异常存储在返回的任务中。

注解

此方法将存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(IPAddress[], Int32)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9

ConnectAsync(String, Int32, CancellationToken)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.ValueTask ConnectAsync (string host, int port, System.Threading.CancellationToken cancellationToken);

参数

host
String

要连接到的远程主机的主机名。

port
Int32

要连接到的远程主机上的端口。

cancellationToken
CancellationToken

可用于取消异步操作的取消标记。

返回

建立连接时完成的异步任务。

例外

host 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

调用堆栈中的较高调用方无权执行所请求的操作。

取消令牌已取消。 此异常存储在返回的任务中。

注解

此方法将存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(String, Int32)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9

ConnectAsync(IPAddress, Int32, CancellationToken)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.ValueTask ConnectAsync (System.Net.IPAddress address, int port, System.Threading.CancellationToken cancellationToken);

参数

address
IPAddress

要连接到的远程主机的 IP 地址。

port
Int32

要连接到的远程主机上的端口。

cancellationToken
CancellationToken

可用于取消异步操作的取消标记。

返回

建立连接时完成的异步任务。

例外

address 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

尝试访问套接字时出错。

调用堆栈中的较高调用方无权执行所请求的操作。

取消令牌已取消。 此异常存储在返回的任务中。

注解

此方法存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(IPAddress, Int32)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9

ConnectAsync(String, Int32)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.Task ConnectAsync (string host, int port);

参数

host
String

要连接到的远程主机的主机名。

port
Int32

要连接到的远程主机上的端口。

返回

建立连接时完成的异步任务。

例外

host 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

调用堆栈中的较高调用方无权执行所请求的操作。

注解

此方法存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(String, Int32)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9

ConnectAsync(IPAddress[], Int32)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.Task ConnectAsync (System.Net.IPAddress[] addresses, int port);

参数

addresses
IPAddress[]

将用于尝试连接到远程主机的远程主机的 IPAddresses 列表。

port
Int32

要连接到的远程主机上的端口。

返回

建立连接时完成的异步任务。

例外

addresses 参数不能为 NULL。

参数 addresses 不能为空数组。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

调用堆栈中的较高调用方无权执行所请求的操作。

注解

此方法存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(IPAddress[], Int32)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9

ConnectAsync(IPAddress, Int32)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.Task ConnectAsync (System.Net.IPAddress address, int port);

参数

address
IPAddress

要连接到的远程主机的 IP 地址。

port
Int32

要连接到的远程主机上的端口。

返回

建立连接时完成的异步任务。

例外

address 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

调用堆栈中的较高调用方无权执行所请求的操作。

注解

此方法存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(IPAddress, Int32)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9

ConnectAsync(EndPoint, CancellationToken)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.ValueTask ConnectAsync (System.Net.EndPoint remoteEP, System.Threading.CancellationToken cancellationToken);

参数

remoteEP
EndPoint

要连接到的终结点。

cancellationToken
CancellationToken

可用于取消异步操作的取消标记。

返回

建立连接时完成的异步任务。

例外

remoteEP 参数不能为 NULL。

尝试访问套接字时出错。

本地终结点和 remoteEP 参数不是同一个地址系列。

调用堆栈中的较高调用方无权执行所请求的操作。

取消令牌已取消。 此异常存储在返回的任务中。

注解

此方法存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(EndPoint)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9

ConnectAsync(SocketAsyncEventArgs)

Source:
Socket.cs
Source:
Socket.cs
Source:
Socket.cs

开始一个对远程主机连接的异步请求。

public bool ConnectAsync (System.Net.Sockets.SocketAsyncEventArgs e);

参数

e
SocketAsyncEventArgs

要用于此异步套接字操作的 SocketAsyncEventArgs 对象。

返回

如果 I/O 操作挂起,则为 true。 操作完成时,将引发 e 参数的 Completed 事件。

如果 I/O 操作同步完成,则为 false。 在这种情况下,将不会引发 e 参数的 Completed 事件,并且可能在方法调用返回后立即检查作为参数传递的 e 对象以检索操作的结果。

例外

自变量无效。 如果指定了多个缓冲区,即 BufferList 属性不为 null,将会发生此异常。

e 参数不能为 null,并且 RemoteEndPoint 不能为空。

Socket 正在侦听或已经在使用 e 参数中指定的 SocketAsyncEventArgs 对象执行套接字操作。

尝试访问套接字时出错。

本地终结点和 RemoteEndPoint 不是同一个地址系列。

调用堆栈中的较高调用方无权执行所请求的操作。

注解

如果使用面向连接的协议,则 ConnectAsync 方法会启动与远程主机建立连接的异步请求。 如果使用无连接协议, ConnectAsync 则建立默认远程主机。

若要收到完成通知,必须创建实现 EventHandler<SocketAsyncEventArgs> 委托的回调方法,并将回调附加到 SocketAsyncEventArgs.Completed 事件。

调用方必须将 属性设置为SocketAsyncEventArgs.RemoteEndPointIPEndPoint要连接到的远程主机的 。

调用方可以在调用ConnectAsync方法之前将 SocketAsyncEventArgs.UserToken 属性设置为所需的任何用户状态对象,以便可在回调方法中检索信息。 如果回调需要比单个对象更多的信息,则可以创建一个小类来保存其他所需的状态信息作为成员。

如果使用 UDP 等无连接协议,则不必在发送和接收数据之前调用 ConnectAsync 。 可以使用 SendToAsyncReceiveFromAsync 与远程主机通信。 如果确实调用 ConnectAsync,则将放弃从指定默认值以外的地址到达的任何数据报。 如果要更改默认远程主机,请使用所需的终结点再次调用 ConnectAsync 方法。

如果要将默认远程主机设置为广播地址,必须首先调用 SetSocketOption 并将 Broadcast 设置为 true。 如果未完成此操作,该方法 ConnectAsync 将引发 SocketException

对象需要 System.Net.Sockets.SocketAsyncEventArgs 以下属性和事件:

(可选)可以提供缓冲区,该方法成功后 ConnectAsync 将在套接字上以原子方式发送。 在这种情况下,需要将 SocketAsyncEventArgs.Buffer 属性设置为包含要发送的数据的缓冲区, SocketAsyncEventArgs.Count 而 属性需要设置为要从缓冲区发送的数据的字节数。 建立连接后,发送此数据缓冲区。

如果使用面向连接的协议,并且未在调用 ConnectAsync之前调用 Bind ,则基础服务提供商将分配最合适的本地网络地址和端口号。

如果使用无连接协议,则在你调用 SendAsyncReceiveAsync 方法之前,服务提供商不会分配本地网络 IP 地址和端口号。

ConnectAsync如果 和 SocketAsyncEventArgs.RemoteEndPointSocket地址系列不在同一地址系列,则引发 NotSupportedException 方法。

备注

如果在调用此方法时收到 SocketException ,请使用 SocketException.ErrorCode 属性获取特定的错误代码。 获取此代码后,请参阅 Windows 套接字版本 2 API 错误代码 文档,获取错误的详细说明。

另请参阅

适用于

.NET 9 和其他版本
产品 版本
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.3, 1.4, 1.6, 2.0, 2.1
UWP 10.0

ConnectAsync(EndPoint)

Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs
Source:
Socket.Tasks.cs

与远程主机建立连接。

public System.Threading.Tasks.Task ConnectAsync (System.Net.EndPoint remoteEP);

参数

remoteEP
EndPoint

要连接到的终结点。

返回

建立连接时完成的异步任务。

例外

remoteEP 参数不能为 NULL。

尝试访问套接字时出错。

本地终结点和 remoteEP 参数不是同一个地址系列。

调用堆栈中的较高调用方无权执行所请求的操作。

注解

此方法将存储在任务中,它返回该方法的同步对应项可能引发的所有非使用异常。 如果异常存储在返回的任务中,则在等待任务时将引发该异常。 使用异常(如 ArgumentException)仍会同步引发。 有关存储的异常,请参阅 引发的 Connect(EndPoint)异常。

适用于

.NET 9 和其他版本
产品 版本
.NET 6, 7, 8, 9