Table of Contents

Interface IPersistenceProvider

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

Defines the contract for persistence providers that manage DataRequest execution and lifecycle. Providers focus on connection management and infrastructure concerns rather than specific CRUD operations.

public interface IPersistenceProvider : IAsyncDisposable, IDisposable
Inherited Members

Remarks

This is the core interface with ≤5 members. Optional capabilities are accessed via GetService(Type):

Properties

Name

Gets the identity of this configured provider instance.

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".

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

GetService(Type)

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

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.

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.