Class ClientConnection

Namespace

IceRpc

Assembly

IceRpc.dll

Represents a client connection used to send requests to a server and receive the corresponding responses.

public sealed class ClientConnection : IInvoker, IAsyncDisposable

Inheritance

object

ClientConnection

Implements

IInvoker

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

InvokerExtensions.InvokeBidiStreamingAsync<TInput, TOutput>(IInvoker, ServiceAddress, string, IAsyncEnumerable<TInput>, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

InvokerExtensions.InvokeClientStreamingAsync<TInput, TOutput>(IInvoker, ServiceAddress, string, IAsyncEnumerable<TInput>, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

InvokerExtensions.InvokeServerStreamingAsync<TOutput>(IInvoker, ServiceAddress, string, IMessage, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

InvokerExtensions.InvokeUnaryAsync<TOutput>(IInvoker, ServiceAddress, string, IMessage, MessageParser<TOutput>, ProtobufEncodeOptions?, IFeatureCollection?, bool, CancellationToken)

Remarks

This client connection can also dispatch requests ("callbacks") received from the server. The client connection's underlying connection is recreated and reconnected automatically when it's closed by any event other than a call to ShutdownAsync(CancellationToken) or DisposeAsync().

Constructors

ClientConnection(ClientConnectionOptions, IDuplexClientTransport?, IMultiplexedClientTransport?, ILogger?)

Constructs a client connection.

public ClientConnection(ClientConnectionOptions options, IDuplexClientTransport? duplexClientTransport = null, IMultiplexedClientTransport? multiplexedClientTransport = null, ILogger? logger = null)

Parameters

options ClientConnectionOptions

The client connection options.

duplexClientTransport IDuplexClientTransport

The duplex client transport. null is equivalent to Default.

multiplexedClientTransport IMultiplexedClientTransport

The multiplexed client transport. null is equivalent to Default.

logger ILogger

The logger. null is equivalent to Instance.

ClientConnection(ServerAddress, SslClientAuthenticationOptions?, IDuplexClientTransport?, IMultiplexedClientTransport?, ILogger?)

Constructs a client connection with the specified server address and client authentication options. All other properties use the ClientConnectionOptions defaults.

public ClientConnection(ServerAddress serverAddress, SslClientAuthenticationOptions? clientAuthenticationOptions = null, IDuplexClientTransport? duplexClientTransport = null, IMultiplexedClientTransport? multiplexedClientTransport = null, ILogger? logger = null)

Parameters

serverAddress ServerAddress

The connection's server address.

clientAuthenticationOptions SslClientAuthenticationOptions

The SSL client authentication options. When not null, ConnectAsync(CancellationToken) will either establish a secure connection or fail.

duplexClientTransport IDuplexClientTransport

The duplex client transport. null is equivalent to Default.

multiplexedClientTransport IMultiplexedClientTransport

The multiplexed client transport. null is equivalent to Default.

logger ILogger

The logger. null is equivalent to Instance.

ClientConnection(Uri, SslClientAuthenticationOptions?, IDuplexClientTransport?, IMultiplexedClientTransport?, ILogger?)

Constructs a client connection with the specified server address URI and client authentication options. All other properties use the ClientConnectionOptions defaults.

public ClientConnection(Uri serverAddressUri, SslClientAuthenticationOptions? clientAuthenticationOptions = null, IDuplexClientTransport? duplexClientTransport = null, IMultiplexedClientTransport? multiplexedClientTransport = null, ILogger? logger = null)

Parameters

serverAddressUri Uri

The connection's server address URI.

clientAuthenticationOptions SslClientAuthenticationOptions

The SSL client authentication options. When not null, ConnectAsync(CancellationToken) will either establish a secure connection or fail.

duplexClientTransport IDuplexClientTransport

The duplex client transport. null is equivalent to Default.

multiplexedClientTransport IMultiplexedClientTransport

The multiplexed client transport. null is equivalent to Default.

logger ILogger

The logger. null is equivalent to Instance.

Methods

ConnectAsync(CancellationToken)

Establishes the connection.

public Task<TransportConnectionInformation> ConnectAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token that receives the cancellation requests.

Returns

Task<TransportConnectionInformation>

A task that provides the TransportConnectionInformation of the transport connection, once this connection is established. This task can also complete with one of the following exceptions:

• AuthenticationException if authentication failed.
• IceRpcException if the connection establishment failed.
• OperationCanceledException if cancellation was requested through the cancellation token.
• TimeoutException if this connection attempt or a previous attempt exceeded ConnectTimeout.

Remarks

This method can be called multiple times and concurrently. If the connection is not established, it will be connected or reconnected.

Exceptions

InvalidOperationException

Thrown if this client connection is shut down or shutting down.

ObjectDisposedException

Thrown if this client connection is disposed.

DisposeAsync()

Releases all resources allocated by the connection. The connection disposes all the underlying connections it created.

public ValueTask DisposeAsync()

Returns

ValueTask

A value task that completes when the disposal of all the underlying connections has completed.

Remarks

The disposal of an underlying connection aborts invocations, cancels dispatches and disposes the underlying transport connection without waiting for the peer. To wait for invocations and dispatches to complete, call ShutdownAsync(CancellationToken) first. If the configured dispatcher does not complete promptly when its cancellation token is canceled, the disposal can hang.

InvokeAsync(OutgoingRequest, CancellationToken)

Sends an outgoing request and returns the corresponding incoming response.

public Task<IncomingResponse> InvokeAsync(OutgoingRequest request, CancellationToken cancellationToken = default)

Parameters

request OutgoingRequest

The outgoing request being sent.

cancellationToken CancellationToken

A cancellation token that receives the cancellation requests.

Returns

Task<IncomingResponse>

The corresponding IncomingResponse.

Remarks

If the connection is not established, it will be connected or reconnected.

Exceptions

InvalidOperationException

Thrown if none of the request's server addresses matches this connection's server address.

IceRpcException

Thrown with error InvocationRefused if this client connection is shutdown.

ObjectDisposedException

Thrown if this client connection is disposed.

ShutdownAsync(CancellationToken)

Gracefully shuts down the connection. The shutdown waits for pending invocations and dispatches to complete.

public Task ShutdownAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token that receives the cancellation requests.

Returns

Task

A task that completes once the shutdown is complete. This task can also complete with one of the following exceptions:

• IceRpcException if the connection shutdown failed.
• OperationCanceledException if cancellation was requested through the cancellation token.
• TimeoutException if this shutdown attempt or a previous attempt exceeded ShutdownTimeout.

Exceptions

InvalidOperationException

Thrown if this connection is already shut down or shutting down.

ObjectDisposedException

Thrown if this connection is disposed.