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):
- IPersistenceProviderHealth — health checks, metrics, pool stats
- IPersistenceProviderTransaction — ambient transaction scopes and transactional request execution
- IPersistenceProviderConnection — connection string and retry policy
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
serviceTypeTypeThe type of the requested service.
Returns
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
serviceTypeis null.
InitializeAsync(IPersistenceOptions, CancellationToken)
Initializes the provider with the specified options.
Task InitializeAsync(IPersistenceOptions options, CancellationToken cancellationToken)
Parameters
optionsIPersistenceOptionsThe persistence options.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
A task representing the asynchronous operation.