Table of Contents

Class DelegatingPersistenceProvider

Namespace
Excalibur.Data.Persistence
Assembly
Excalibur.Data.Abstractions.dll

Abstract base class for IPersistenceProvider decorators. All methods are virtual and forward to the inner provider by default.

public abstract class DelegatingPersistenceProvider : IPersistenceProvider, IAsyncDisposable, IDisposable
Inheritance
DelegatingPersistenceProvider
Implements
Inherited Members

Remarks

Follows the DelegatingHandler / DelegatingChatClient pattern from Microsoft. Subclasses override only the methods they need to intercept (e.g., logging, metrics, retry policies, multi-tenancy routing).

Example: a logging decorator that intercepts InitializeAsync(IPersistenceOptions, CancellationToken):

public class LoggingPersistenceProvider(IPersistenceProvider inner, ILogger logger)
    : DelegatingPersistenceProvider(inner)
{
    public override async Task InitializeAsync(
        IPersistenceOptions options, CancellationToken cancellationToken)
    {
        logger.LogDebug("Initializing {Provider}", Name);
        await base.InitializeAsync(options, cancellationToken);
    }
}

Capabilities reached through GetService(Type) — such as IDataRequestExecutor — are not members of this base, so a decorator that needs to intercept one overrides GetService(Type) and returns its own wrapper for that capability.

Constructors

DelegatingPersistenceProvider(IPersistenceProvider)

Initializes a new instance of the DelegatingPersistenceProvider class.

protected DelegatingPersistenceProvider(IPersistenceProvider inner)

Parameters

inner IPersistenceProvider

The inner persistence provider to delegate to.

Properties

Inner

Gets the inner persistence provider being decorated.

protected IPersistenceProvider Inner { get; }

Property Value

IPersistenceProvider

Name

Gets the identity of this configured provider instance.

public virtual string Name { get; }

Property Value

string

The identity of this configured provider instance.

Remarks

This is the instance dimension, not the engine dimension. Two instances of the same engine configured separately report different names, which is what lets a consumer tell them apart in health output, logs and metrics. The engine an instance runs on is reported separately, under the Provider key of GetMetricsAsync(CancellationToken).

The value is non-null and non-empty, is established at construction, and does not change for the lifetime of the instance — it is readable before InitializeAsync(IPersistenceOptions, CancellationToken) and after disposal. When no name is configured it falls back to a stable per-implementation default.

Known gap: a provider instance shared across several configuration entries reports a single identity, because the shared instance is one object.

ProviderType

Gets the family of store this provider talks to, such as "SQL", "Document" or "KeyValue".

public virtual string ProviderType { get; }

Property Value

string

The family of store this provider talks to.

Remarks

This is the family, not the engine and not the instance: several engines share a family, and it is what a consumer branches on when the shape of the store matters more than which product it is. It is a fixed literal, constant per implementation, and MUST NOT vary with configuration. For the engine, read the Provider key of GetMetricsAsync(CancellationToken); for the configured instance, read Name.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

Releases resources used by the DelegatingPersistenceProvider.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public virtual ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

GetService(Type)

Gets an implementation-specific service. Use to access optional capabilities such as IPersistenceProviderHealth, IPersistenceProviderTransaction, IPersistenceProviderConnection, or provider-specific features.

public virtual object? GetService(Type serviceType)

Parameters

serviceType Type

The type of the requested service.

Returns

object

The service instance, or null if not supported.

Remarks

The default implementation answers for any capability this instance itself implements. Leaf providers need not override it. Decorators MUST override it to defer unknown capabilities to the provider they wrap; a decorator that does not forward silently disables the capability beneath it.

Exceptions

ArgumentNullException

Thrown when serviceType is null.

InitializeAsync(IPersistenceOptions, CancellationToken)

Initializes the provider with the specified options.

public virtual Task InitializeAsync(IPersistenceOptions options, CancellationToken cancellationToken)

Parameters

options IPersistenceOptions

The persistence options.

cancellationToken CancellationToken

The cancellation token.

Returns

Task

A task representing the asynchronous operation.