Hsm.CatalogService.Client 1.0.0-alpha.3

Hsm.CatalogService.Client

Interfaces:

• 'ICatalogServiceCommonApi'
• 'ICatalogServiceBrowseApiV3'

ExampleUsage:

services
    .AddGeneratedRestClient<ICatalogServiceCommonApi>(() => 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>())

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()

    .AddExceptionTransformation((_, exception) =>
        exception switch
        {
            OperationalContextApiException<ErrorContainer> typedError
                when typedError.Result.Error.Code == "NoOperationalContext"
                => new TestException("OperationalContext NotFound", exception),

            _ => exception,
        })

    .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

.AddExceptionTransformation((method, exception) => ...)

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

• called method
• returned error

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
)

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