Socket.ConnectAsync 方法

定義

命名空間:

System.Net.Sockets

組件:

System.Net.Sockets.dll

開始與遠端主機連接的非同步要求。

多載

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)

來源:

Socket.cs

開始與遠端主機連接的非同步要求。

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 物件，用於這個非同步通訊端作業。

傳回

Boolean

若 I/O 作業暫止，則為 true。 作業完成時會引發與 e 參數有關的 Completed 事件。

若 I/O 作業同步完成，則為 false。 在這個情況下，就不會引發與 e 參數有關的 Completed 事件，而在方法呼叫傳回後會立即檢查做為參數傳遞的 e 物件，以擷取作業的結果。

例外狀況

ArgumentException

引數無效。 如果指定多個緩衝區而 BufferList 屬性不是 null，就會發生這個例外狀況。

ArgumentNullException

e 參數不可為 null，而且 RemoteEndPoint 也不可為 null。

InvalidOperationException

Socket 正在接聽，或是通訊端作業正在進行並且使用 e 參數所指定的 SocketAsyncEventArgs 物件。

SocketException

嘗試存取通訊端時發生錯誤。

NotSupportedException

本機端點和 RemoteEndPoint 不是相同的位址系列。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

備註

如果您使用連線導向通訊協定，M：System.Net.Sockets.Socket.ConnectAsync (System.Net.Sockets.SocketType，System.Net.Sockets.ProtocolType，System.Net.Sockets.SocketAsyncEventArgs) 方法會啟動遠端主機連線的非同步要求。 如果您使用無連線通訊協定， ConnectAsync 請建立 和 protocolType 參數所 socketType 指定的預設遠端主機。

若要收到完成通知，您必須建立回呼方法，以實作 EventHandler < SocketAsyncEventArgs > 委派，並將回呼附加至 SocketAsyncEventArgs.Completed 事件。

呼叫端必須將 屬性設定 SocketAsyncEventArgs.RemoteEndPoint 為 IPEndPoint 遠端主機的 ，才能連線。

呼叫端可以在呼叫 ConnectAsync 方法之前，將 屬性設定 SocketAsyncEventArgs.UserToken 為任何所需的使用者狀態物件，以便在回呼方法中擷取資訊。 如果回呼需要比單一物件更多的資訊，則可以建立小型類別，以將其他必要狀態資訊保存為成員。

如果您使用 UDP 之類的無連線通訊協定，則不需要在傳送和接收資料之前呼叫 ConnectAsync 。 您可以使用 SendToAsync 和 ReceiveFromAsync 與遠端主機通訊。 如果您呼叫 ConnectAsync ，則會捨棄從指定預設值以外的位址抵達的任何資料包。 如果您想要變更預設遠端主機，請使用所需的端點再次呼叫 ConnectAsync 方法。

如果您想要將預設遠端主機設定為廣播位址，您必須先呼叫 SetSocketOption ，並將 Broadcast 設定為 true 。 如果未這麼做，方法 ConnectAsync 會擲回 SocketException 。

需要物件上的 System.Net.Sockets.SocketAsyncEventArgs 下列屬性和事件：

• SocketAsyncEventArgs.Completed

• SocketAsyncEventArgs.RemoteEndPoint

您可以選擇性地提供緩衝區，這會在方法成功之後 ConnectAsync ，以不可部分完成的方式在通訊端上傳送。 在此情況下， SocketAsyncEventArgs.Buffer 屬性必須設定為包含要傳送之資料的緩衝區，而且 SocketAsyncEventArgs.Count 屬性必須設定為要從緩衝區傳送的資料位元組數目。 建立連線之後，就會傳送此資料緩衝區。

如果您使用連線導向通訊協定，而且在呼叫 之前未呼叫 BindConnectAsync ，基礎服務提供者會指派最適當的區域網路位址和埠號碼。

如果您使用無連線通訊協定，在呼叫 SendAsync 或 ReceiveAsync 方法之前，服務提供者不會指派區域網路 IP 位址和埠號碼。

如果 的 Socket 位址系列和 不是相同的位址系列， SocketAsyncEventArgs.RemoteEndPoint 方法 ConnectAsync 會 NotSupportedException 擲回 。

注意

如果您在呼叫此方法時收到 SocketException ，請使用 SocketException.ErrorCode 屬性來取得特定的錯誤碼。 取得此程式碼之後，請參閱 Windows Sockets 第 2 版 API 錯誤碼 檔，以取得錯誤的詳細描述。

ConnectAsync(IPAddress[], Int32, CancellationToken)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

可用來取消非同步作業的解除標記。

傳回

ValueTask

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

addresses 參數不可以是 Null。

ArgumentException

參數 addresses 不可以是空陣列。

ArgumentOutOfRangeException

port 小於 MinPort。

-或-

port 大於 MaxPort。

InvalidOperationException

正在 Socket 接聽。

NotSupportedException

通訊端不在 或 InterNetworkV6 系列中 InterNetwork 。

SocketException

嘗試存取通訊端時發生錯誤。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

OperationCanceledException

解除標記已取消。 此例外狀況會儲存在傳回的工作中。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用例外狀況，例如 ArgumentException 仍會同步擲回。 如需預存例外狀況，請參閱 擲回的 Connect(IPAddress[], Int32) 例外狀況。

ConnectAsync(String, Int32, CancellationToken)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

可用來取消非同步作業的解除標記。

傳回

ValueTask

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

host 參數不可以是 Null。

ArgumentOutOfRangeException

port 小於 MinPort。

-或-

port 大於 MaxPort。

InvalidOperationException

正在 Socket 接聽。

NotSupportedException

通訊端不在 或 InterNetworkV6 系列中 InterNetwork 。

SocketException

嘗試存取通訊端時發生錯誤。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

OperationCanceledException

解除標記已取消。 此例外狀況會儲存在傳回的工作中。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用例外狀況，例如 ArgumentException 仍會同步擲回。 如需預存例外狀況，請參閱 擲回的 Connect(String, Int32) 例外狀況。

ConnectAsync(IPAddress, Int32, CancellationToken)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

要連線之遠端主機的 IPAddress。

port

Int32

要連線之遠端主機上的埠。

cancellationToken

CancellationToken

可用來取消非同步作業的解除標記。

傳回

ValueTask

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

address 參數不可以是 Null。

ArgumentOutOfRangeException

port 小於 MinPort。

-或-

port 大於 MaxPort。

InvalidOperationException

Socket正在接聽。

SocketException

嘗試存取通訊端時發生錯誤。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

OperationCanceledException

取消權杖已取消。 此例外狀況會儲存在傳回的工作中。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用狀況例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用狀況例外狀況，例如 ArgumentException ，仍會同步擲回。 如需預存的例外狀況，請參閱 所 Connect(IPAddress, Int32) 擲回的例外狀況。

ConnectAsync(String, Int32)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

要連線之遠端主機上的埠。

傳回

Task

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

host 參數不可以是 Null。

ArgumentOutOfRangeException

port 小於 MinPort。

-或-

port 大於 MaxPort。

InvalidOperationException

Socket正在接聽。

NotSupportedException

通訊端不在 或 InterNetworkV6 系列中 InterNetwork 。

SocketException

嘗試存取通訊端時發生錯誤。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用狀況例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用狀況例外狀況，例如 ArgumentException ，仍會同步擲回。 如需預存的例外狀況，請參閱 所 Connect(String, Int32) 擲回的例外狀況。

ConnectAsync(IPAddress[], Int32)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

要連線之遠端主機上的埠。

傳回

Task

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

addresses 參數不可以是 Null。

ArgumentException

參數 addresses 不能是空陣列。

ArgumentOutOfRangeException

port 小於 MinPort。

-或-

port 大於 MaxPort。

InvalidOperationException

Socket正在接聽。

NotSupportedException

通訊端不在 或 InterNetworkV6 系列中 InterNetwork 。

SocketException

嘗試存取通訊端時發生錯誤。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用狀況例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用狀況例外狀況，例如 ArgumentException ，仍會同步擲回。 如需預存的例外狀況，請參閱 所 Connect(IPAddress[], Int32) 擲回的例外狀況。

ConnectAsync(IPAddress, Int32)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

要連線之遠端主機的 IPAddress。

port

Int32

要連線之遠端主機上的埠。

傳回

Task

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

address 參數不可以是 Null。

ArgumentOutOfRangeException

port 小於 MinPort。

-或-

port 大於 MaxPort。

InvalidOperationException

Socket正在接聽。

NotSupportedException

通訊端不在 或 InterNetworkV6 系列中 InterNetwork 。

SocketException

嘗試存取通訊端時發生錯誤。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用狀況例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用狀況例外狀況，例如 ArgumentException ，仍會同步擲回。 如需預存的例外狀況，請參閱 所 Connect(IPAddress, Int32) 擲回的例外狀況。

ConnectAsync(EndPoint, CancellationToken)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

可用來取消非同步作業的解除標記。

傳回

ValueTask

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

remoteEP 參數不可以是 Null。

InvalidOperationException

Socket正在接聽。

SocketException

嘗試存取通訊端時發生錯誤。

NotSupportedException

本機端點和 remoteEP 參數不是相同的位址系列。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

OperationCanceledException

取消權杖已取消。 此例外狀況會儲存在傳回的工作中。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用狀況例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用狀況例外狀況，例如 ArgumentException ，仍會同步擲回。 如需預存的例外狀況，請參閱 所 Connect(EndPoint) 擲回的例外狀況。

ConnectAsync(SocketAsyncEventArgs)

來源:

Socket.cs

開始與遠端主機連接的非同步要求。

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 物件，用於這個非同步通訊端作業。

傳回

Boolean

若 I/O 作業暫止，則為 true。 作業完成時會引發與 e 參數有關的 Completed 事件。

若 I/O 作業同步完成，則為 false。 在這個情況下，就不會引發與 e 參數有關的 Completed 事件，而在方法呼叫傳回後會立即檢查做為參數傳遞的 e 物件，以擷取作業的結果。

例外狀況

ArgumentException

引數無效。 如果指定多個緩衝區而 BufferList 屬性不是 null，就會發生這個例外狀況。

ArgumentNullException

e 參數不可為 null，而且 RemoteEndPoint 也不可為 null。

InvalidOperationException

Socket 正在接聽，或是通訊端作業正在進行並且使用 e 參數所指定的 SocketAsyncEventArgs 物件。

SocketException

嘗試存取通訊端時發生錯誤。

NotSupportedException

本機端點和 RemoteEndPoint 不是相同的位址系列。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

備註

如果您使用連接導向通訊協定，此方法 ConnectAsync 會啟動遠端主機連線的非同步要求。 如果您使用無連線通訊協定， ConnectAsync 請建立預設遠端主機。

若要收到完成通知，您必須建立回呼方法，以實作 EventHandler < SocketAsyncEventArgs > 委派，並將回呼附加至 SocketAsyncEventArgs.Completed 事件。

呼叫端必須將 屬性設定 SocketAsyncEventArgs.RemoteEndPoint 為 IPEndPoint 遠端主機的 ，才能連線。

呼叫端可以在呼叫 ConnectAsync 方法之前，將 屬性設定 SocketAsyncEventArgs.UserToken 為任何所需的使用者狀態物件，以便在回呼方法中擷取資訊。 如果回呼需要比單一物件更多的資訊，則可以建立小型類別，以將其他必要狀態資訊保留為成員。

如果您使用 UDP 之類的無連線通訊協定，則不需要在傳送和接收資料之前呼叫 ConnectAsync 。 您可以使用 SendToAsync 和 ReceiveFromAsync 與遠端主機通訊。 如果您呼叫 ConnectAsync ，則會捨棄從指定預設值以外的位址抵達的任何資料包。 如果您想要變更預設遠端主機，請使用所需的端點再次呼叫 ConnectAsync 方法。

如果您想要將預設遠端主機設定為廣播位址，您必須先呼叫 SetSocketOption ，並將 [廣播] 設定為 true 。 如果未這麼做， ConnectAsync 方法會擲回 SocketException 。

需要物件上的 System.Net.Sockets.SocketAsyncEventArgs 下列屬性和事件：

• SocketAsyncEventArgs.Completed

• SocketAsyncEventArgs.RemoteEndPoint

您可以選擇性地提供緩衝區，這會在方法成功之後 ConnectAsync ，以不可部分完成的方式在通訊端上傳送。 在此情況下， SocketAsyncEventArgs.Buffer 屬性必須設定為包含要傳送之資料的緩衝區，而且 SocketAsyncEventArgs.Count 屬性必須設定為要從緩衝區傳送的資料位元組數目。 建立連線之後，就會傳送此資料緩衝區。

如果您使用連線導向通訊協定，且未在呼叫 之前呼叫 BindConnectAsync ，則基礎服務提供者會指派最適當的區域網路位址和埠號碼。

如果您使用無連線通訊協定，在呼叫 SendAsync 或 ReceiveAsync 方法之前，服務提供者不會指派區域網路 IP 位址和埠號碼。

ConnectAsync如果 和 SocketAsyncEventArgs.RemoteEndPoint 的 Socket 位址系列不相同，方法會擲回 NotSupportedException 。

注意

如果您在呼叫此方法時收到 SocketException ，請使用 SocketException.ErrorCode 屬性來取得特定的錯誤碼。 取得此程式碼之後，請參閱 Windows Sockets 第 2 版 API 錯誤碼 檔，以取得錯誤的詳細描述。

另請參閱

• SocketAsyncEventArgs
• Buffer
• Completed
• Count
• RemoteEndPoint
• UserToken

ConnectAsync(EndPoint)

來源:

Socket.Tasks.cs

建立與遠端主機的連線。

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

要連線的端點。

傳回

Task

建立連接時完成的非同步工作。

例外狀況

ArgumentNullException

remoteEP 參數不可以是 Null。

InvalidOperationException

Socket正在接聽。

SocketException

嘗試存取通訊端時發生錯誤。

NotSupportedException

本機端點和 remoteEP 參數不是相同的位址系列。

ObjectDisposedException

Socket 已關閉。

SecurityException

在呼叫堆疊中位置較高的呼叫端對於要求的作業沒有權限。

備註

這個方法會儲存在工作中，它會傳回方法同步對應專案可以擲回的所有非使用狀況例外狀況。 如果例外狀況儲存在傳回的工作中，則會在等候工作時擲回該例外狀況。 使用狀況例外狀況，例如 ArgumentException ，仍會同步擲回。 如需預存的例外狀況，請參閱 所 Connect(EndPoint) 擲回的例外狀況。