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)

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

public:
 static bool ConnectAsync(System::Net::Sockets::SocketType socketType, System::Net::Sockets::ProtocolType protocolType, System::Net::Sockets::SocketAsyncEventArgs ^ e);
public static bool ConnectAsync (System.Net.Sockets.SocketType socketType, System.Net.Sockets.ProtocolType protocolType, System.Net.Sockets.SocketAsyncEventArgs e);
static member ConnectAsync : System.Net.Sockets.SocketType * System.Net.Sockets.ProtocolType * System.Net.Sockets.SocketAsyncEventArgs -> bool
Public Shared Function ConnectAsync (socketType As SocketType, protocolType As ProtocolType, e As SocketAsyncEventArgs) As Boolean

参数

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 错误代码 文档,获取错误的详细说明。

适用于

ConnectAsync(IPAddress[], Int32, CancellationToken)

与远程主机建立连接。

public:
 System::Threading::Tasks::ValueTask ConnectAsync(cli::array <System::Net::IPAddress ^> ^ addresses, int port, System::Threading::CancellationToken cancellationToken);
public System.Threading.Tasks.ValueTask ConnectAsync (System.Net.IPAddress[] addresses, int port, System.Threading.CancellationToken cancellationToken);
member this.ConnectAsync : System.Net.IPAddress[] * int * System.Threading.CancellationToken -> System.Threading.Tasks.ValueTask
Public Function ConnectAsync (addresses As IPAddress(), port As Integer, cancellationToken As CancellationToken) As ValueTask

参数

addresses
IPAddress[]

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

port
Int32

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

cancellationToken
CancellationToken

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

返回

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

例外

addresses 参数不能为 NULL。

参数 addresses 不能为空数组。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

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

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

注解

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

适用于

ConnectAsync(String, Int32, CancellationToken)

与远程主机建立连接。

public:
 System::Threading::Tasks::ValueTask ConnectAsync(System::String ^ host, int port, System::Threading::CancellationToken cancellationToken);
public System.Threading.Tasks.ValueTask ConnectAsync (string host, int port, System.Threading.CancellationToken cancellationToken);
member this.ConnectAsync : string * int * System.Threading.CancellationToken -> System.Threading.Tasks.ValueTask
Public Function ConnectAsync (host As String, port As Integer, cancellationToken As CancellationToken) As ValueTask

参数

host
String

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

port
Int32

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

cancellationToken
CancellationToken

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

返回

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

例外

host 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

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

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

注解

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

适用于

ConnectAsync(IPAddress, Int32, CancellationToken)

与远程主机建立连接。

public:
 System::Threading::Tasks::ValueTask ConnectAsync(System::Net::IPAddress ^ address, int port, System::Threading::CancellationToken cancellationToken);
public System.Threading.Tasks.ValueTask ConnectAsync (System.Net.IPAddress address, int port, System.Threading.CancellationToken cancellationToken);
member this.ConnectAsync : System.Net.IPAddress * int * System.Threading.CancellationToken -> System.Threading.Tasks.ValueTask
Public Function ConnectAsync (address As IPAddress, port As Integer, cancellationToken As CancellationToken) As ValueTask

参数

address
IPAddress

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

port
Int32

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

cancellationToken
CancellationToken

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

返回

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

例外

address 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

尝试访问套接字时出错。

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

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

注解

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

适用于

ConnectAsync(String, Int32)

与远程主机建立连接。

public:
 System::Threading::Tasks::Task ^ ConnectAsync(System::String ^ host, int port);
public System.Threading.Tasks.Task ConnectAsync (string host, int port);
member this.ConnectAsync : string * int -> System.Threading.Tasks.Task
Public Function ConnectAsync (host As String, port As Integer) As Task

参数

host
String

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

port
Int32

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

返回

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

例外

host 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

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

注解

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

适用于

ConnectAsync(IPAddress[], Int32)

与远程主机建立连接。

public:
 System::Threading::Tasks::Task ^ ConnectAsync(cli::array <System::Net::IPAddress ^> ^ addresses, int port);
public System.Threading.Tasks.Task ConnectAsync (System.Net.IPAddress[] addresses, int port);
member this.ConnectAsync : System.Net.IPAddress[] * int -> System.Threading.Tasks.Task
Public Function ConnectAsync (addresses As IPAddress(), port As Integer) As Task

参数

addresses
IPAddress[]

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

port
Int32

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

返回

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

例外

addresses 参数不能为 NULL。

参数 addresses 不能为空数组。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

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

注解

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

适用于

ConnectAsync(IPAddress, Int32)

与远程主机建立连接。

public:
 System::Threading::Tasks::Task ^ ConnectAsync(System::Net::IPAddress ^ address, int port);
public System.Threading.Tasks.Task ConnectAsync (System.Net.IPAddress address, int port);
member this.ConnectAsync : System.Net.IPAddress * int -> System.Threading.Tasks.Task
Public Function ConnectAsync (address As IPAddress, port As Integer) As Task

参数

address
IPAddress

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

port
Int32

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

返回

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

例外

address 参数不能为 NULL。

port 小于 MinPort

- 或 -

port 大于 MaxPort

套接字不在 或 InterNetworkV6 系列中InterNetwork

尝试访问套接字时出错。

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

注解

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

适用于

ConnectAsync(EndPoint, CancellationToken)

与远程主机建立连接。

public:
 System::Threading::Tasks::ValueTask ConnectAsync(System::Net::EndPoint ^ remoteEP, System::Threading::CancellationToken cancellationToken);
public System.Threading.Tasks.ValueTask ConnectAsync (System.Net.EndPoint remoteEP, System.Threading.CancellationToken cancellationToken);
member this.ConnectAsync : System.Net.EndPoint * System.Threading.CancellationToken -> System.Threading.Tasks.ValueTask
Public Function ConnectAsync (remoteEP As EndPoint, cancellationToken As CancellationToken) As ValueTask

参数

remoteEP
EndPoint

要连接到的终结点。

cancellationToken
CancellationToken

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

返回

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

例外

remoteEP 参数不能为 NULL。

尝试访问套接字时出错。

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

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

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

注解

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

适用于

ConnectAsync(SocketAsyncEventArgs)

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

public:
 bool ConnectAsync(System::Net::Sockets::SocketAsyncEventArgs ^ e);
public bool ConnectAsync (System.Net.Sockets.SocketAsyncEventArgs e);
member this.ConnectAsync : System.Net.Sockets.SocketAsyncEventArgs -> bool
Public Function ConnectAsync (e As SocketAsyncEventArgs) As Boolean

参数

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 错误代码 文档,获取错误的详细说明。

另请参阅

适用于

ConnectAsync(EndPoint)

与远程主机建立连接。

public:
 System::Threading::Tasks::Task ^ ConnectAsync(System::Net::EndPoint ^ remoteEP);
public System.Threading.Tasks.Task ConnectAsync (System.Net.EndPoint remoteEP);
member this.ConnectAsync : System.Net.EndPoint -> System.Threading.Tasks.Task
Public Function ConnectAsync (remoteEP As EndPoint) As Task

参数

remoteEP
EndPoint

要连接到的终结点。

返回

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

例外

remoteEP 参数不能为 NULL。

尝试访问套接字时出错。

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

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

注解

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

适用于