Hsm.DataAnalysisService.Client 5.0.0

Hsm.DataAnalysisService.Client

Interfaces:

• 'IDataAnalysisServiceClientApiV1'

ExampleUsage:

services
    .AddGeneratedRestClient<IDataAnalysisServiceClientApiV1>(() => ServiceClientConfiguration)

Caching

Adds AddRecommendedMethods(). These can change over time and should be considered volatile. Does only cache. nothing about invalidation.

.AddCaching(
    config => config.AddRecommendedMethods(),
    sp => sp.GetRequiredService<IDistributedCache>())

ExceptionTransformer

public class DataAnalysisExceptionTransformer : AbstractDataAnalysisServiceClientApiV1ExceptionTransformer
{
    ...
}

Generic Client Documentation

Basic Usage

Example using the client IOperationalContextClientApiV1:

services
    .AddGeneratedRestClient<IOperationalContextClientApiV1>(() => ServiceClientConfiguration)
    .Register();

This registers the generated REST client with a configured base URL.

Full Example

services
.AddDistributedMemoryCache()
.AddGeneratedRestClient<IOperationalContextClientApiV1>(() => ServiceClientConfiguration)
.AddStandardHttpResilience()
.AddExceptionTransformer(new DigitalTwinExceptionTransformer())
.AddCaching(
    config => config.AddRecommendedMethods(),
    sp => sp.GetRequiredService<IDistributedCache>())
.Register();

Features

Resilience

.AddStandardHttpResilience()

Adds default HTTP resilience (retries, timeouts, etc.). Optional overrides can be provided if needed.

Exception Transformation

//create a instance of your exceptionTransformer
public class DigitalTwinExceptionTransformer : AbstractDigitalTwinServiceClientApiV2ExceptionTransformer
{
    ...
}

//register it
.AddExceptionTransformation(new DigitalTwinExceptionTransformer())

Allows mapping API exceptions to domain-specific exceptions based on:

• called method
• returned errorDto(s) (while providing fallback for incorrect swagger docs)

Caching

Setup Caching Definitions

Caching is opt-in and method-based:

• Only methods returning Task<T> can be cached
• Each method maps to a CacheOptions (TTL, etc.)
• Re-registering a method overwrites previous configuration

Selection

• Add(...) → single method
• AddWhere(...) → bulk selection by predicate
• Remove(...) / RemoveWhere(...) → exclusions

⚠️ AddWhere(_ ⇒ true) will cache everything returning Task<T> (including POST-like calls)

Exceptions are never cached

.AddCaching(
    config => config
        .Add(client => client.GetSomethingAsync(id))                 // cache specific method
        .SetNewOptionsDefault(new CacheOptions(TimeSpan.FromHours(1))) // default TTL for all methods following
        .AddWhere(m => m.Name.StartsWith("Get"))                     // cache multiple methods
        .Remove(client => client.GetSomethingAsync(otherId)),        // remove if needed
    sp => sp.GetRequiredService<IDistributedCache>()                // backing cache
)

Initialization/setting with existent values

If caching is added automatically adds ICacheSetter<IOperationalContextClientApiV1> If you have DTOs eg after you retreived pages or you want to set the value from a response you can explicitly set the cache while still respecting your caching options. It will behave exactly the same for the method as defined in the Cacheoptions but the service-call will be replaced with a noop returning the response you defined.

        await _cacheSetter.TrySetReturnValueAsync(
            client =>  client.GetStringAsync(23), // the exact mathod will be cached => only with parameter 23 in this case
            "newString", // with this response
            cancellationToken);

Invalidation

If caching is added automatically adds ICacheInvalidator<IOperationalContextClientApiV1>

await cacheInvalidator.InvalidateAsync(client => client.GetSomethingAsync(id), cancellationToken);

Invalidates exactly one method call (method + arguments). the arguments have to match exactly for the cache to be invalidated (ignoring CancellationTokens)

Health Checks

If the client supports it, you can register a health check:

Only works for clients implementing the required health interface inside the Client, otherwise, this call will fail at compile time.

services.AddRestClientHealthCheck<IOperationalContextClientApiV1>();

Order of Operations

TIClient (resolved from DI)
└── ExceptionTransformationDecorator (Optional)
    └── CacheDecorator (Optional)
        └── TClient (generated REST client)
            └── HttpClient
                ├── OAuth2 Token Handler (Optional)
                └── Resilience Handler (retries, timeouts, etc.) (Optional)

Notes

• All features are optional and composable
• Order of builder calls does not matter (eg ExcepiontTransformation and Caching will not change their order of operations)
• Internally uses decorators to build the pipeline