Class ClientHelper

Namespace

Acuit.Pinpoint.Services.Client

Assembly

Acuit.Pinpoint.Services.Client.dll

Helpers for working with Acuit Pinpoint service clients.

public static class ClientHelper

Inheritance

object

ClientHelper

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

IsExpectedCommunicationException(Exception)

Determines whether an exception is an "expected" possible exception from the client, which includes faults returned from Acuit Pinpoint along with errors connecting to or communicating with the service.

public static bool IsExpectedCommunicationException(Exception exception)

Parameters

exception Exception

The exception.

Returns

bool

true if the exception is an "expected" possible exception from the client.

Examples

var options = new PinpointServiceClientOptions { PinpointHostName = "your-host-name" };
try
{
    ClientHelper.Use(() => new PinpointServiceClient(Options.Create(options)), client =>
    {
        // Call Pinpoint services...
    });
}
catch (Exception ex) when (ClientHelper.IsExpectedCommunicationException(ex))
{
    // Handle comm errors, etc., here
}

Remarks

A typical use for this is to examine a caught exception, and if it is not an expected communication exception, rethrow it as an unexpected unhandled application exception, which would be logged and stop the application to prevent further uncontrolled behavior.

A catch predicate expression can be used to do this, like this:

UseAsync<TClient>(Func<TClient>, Func<TClient, Task>)

A helper to perform work with an Acuit Pinpoint service client, properly closing the client and handling errors properly.

public static Task UseAsync<TClient>(Func<TClient> clientFactory, Func<TClient, Task> worker) where TClient : IPinpointClient

Parameters

clientFactory Func<TClient>

A factory that will create the Acuit Pinpoint service client client to use.

worker Func<TClient, Task>

The delegate that performs the asynchronous work, which will be provided the Acuit Pinpoint service client as its only parameter and should return a task object representing the asynchronous operation.

Returns

Task

The task object representing the asynchronous operation.

Type Parameters

TClient

The client type, which must implement IPinpointClient.

Remarks

Note that PinpointServiceClient and PinpointFileServiceClient have their own similar static helper methods that can simplify usage when using those concrete types.

The Acuit Pinpoint service clients provided by this package are WCF clients. Users of WCF clients should not use the "using" pattern to automatically dispose of them, as Dispose() calls Close(), which can throw an exception. See Use Close and Abort to release WCF client resources | Microsoft Docs for information on why this usage pattern is recommended.

Note: When targeting .NET 8 or later, using this method is unnecessary, as the client's IAsyncDisposable.DisposeAsync implementation provides the equivalent functionality in a more natural way using await using.

Exceptions

ArgumentNullException

clientFactory is null.

ArgumentNullException

worker is null.

CommunicationException

A communication error occurred. This includes faults.

TimeoutException

A communication timeout error occurred.

UseAsync<TClient, TResult>(Func<TClient>, Func<TClient, Task<TResult>>)

A helper to perform work with an Acuit Pinpoint service client, properly closing the client and handling errors properly.

public static Task<TResult> UseAsync<TClient, TResult>(Func<TClient> clientFactory, Func<TClient, Task<TResult>> worker) where TClient : IPinpointClient

Parameters

clientFactory Func<TClient>

A factory that will create the Acuit Pinpoint service client client to use.

worker Func<TClient, Task<TResult>>

The delegate that performs the asynchronous work, which will be provided the Acuit Pinpoint service client as its only parameter and should return a task object representing the asynchronous operation, producing as its result a value of type TResult.

Returns

Task<TResult>

The task object representing the asynchronous operation.

Type Parameters

TClient

The client type, which must implement IPinpointClient.

TResult

The return value type.

Remarks

Once the operation completes, the Result property on the returned task object contains the value produced by worker.

Note that PinpointServiceClient and PinpointFileServiceClient have their own similar static helper methods that can simplify usage when using those concrete types.

The Acuit Pinpoint service clients provided by this package are WCF clients. Users of WCF clients should not use the "using" pattern to automatically dispose of them, as Dispose() calls Close(), which can throw an exception. See Use Close and Abort to release WCF client resources | Microsoft Docs for information on why this usage pattern is recommended.

Note: When targeting .NET 8 or later, using this method is unnecessary, as the client's IAsyncDisposable.DisposeAsync implementation provides the equivalent functionality in a more natural way using await using.

Exceptions

ArgumentNullException

clientFactory is null.

ArgumentNullException

worker is null.

CommunicationException

A communication error occurred. This includes faults.

TimeoutException

A communication timeout error occurred.

Use<TClient>(Func<TClient>, Action<TClient>)

A helper to perform work with an Acuit Pinpoint service client, properly closing the client and handling errors properly.

public static void Use<TClient>(Func<TClient> clientFactory, Action<TClient> worker) where TClient : IPinpointClient

Parameters

clientFactory Func<TClient>

A factory that will create the Acuit Pinpoint service client client to use.

worker Action<TClient>

The delegate that performs the work, which will be provided the Acuit Pinpoint service client as its only parameter.

Type Parameters

TClient

The client type, which must implement IPinpointClient.

Remarks

Note that PinpointServiceClient and PinpointFileServiceClient have their own similar static helper methods that can simplify usage when using those concrete types.

The Acuit Pinpoint service clients provided by this package are WCF clients. Users of WCF clients should not use the "using" pattern to automatically dispose of them, as Dispose() calls Close(), which can throw an exception. See Use Close and Abort to release WCF client resources | Microsoft Docs for information on why this usage pattern is recommended.

Exceptions

ArgumentNullException

clientFactory is null.

ArgumentNullException

worker is null.

CommunicationException

A communication error occurred. This includes faults.

TimeoutException

A communication timeout error occurred.

Use<TClient, TResult>(Func<TClient>, Func<TClient, TResult>)

A helper to perform work with an Acuit Pinpoint service client, properly closing the client and handling errors properly.

public static TResult Use<TClient, TResult>(Func<TClient> clientFactory, Func<TClient, TResult> worker) where TClient : IPinpointClient

Parameters

clientFactory Func<TClient>

A factory that will create the Acuit Pinpoint service client client to use.

worker Func<TClient, TResult>

The delegate that performs the work, which will be provided the Acuit Pinpoint service client as its only parameter and should return a value of type TResult.

Returns

TResult

The return value from worker.

Type Parameters

TClient

The client type, which must implement IPinpointClient.

TResult

The return value type.

Remarks

Note that PinpointServiceClient and PinpointFileServiceClient have their own similar static helper methods that can simplify usage when using those concrete types.

The Acuit Pinpoint service clients provided by this package are WCF clients. Users of WCF clients should not use the "using" pattern to automatically dispose of them, as Dispose() calls Close(), which can throw an exception. See Use Close and Abort to release WCF client resources | Microsoft Docs for information on why this usage pattern is recommended.

Exceptions

ArgumentNullException

clientFactory is null.

ArgumentNullException

worker is null.

CommunicationException

A communication error occurred. This includes faults.

TimeoutException

A communication timeout error occurred.