Class MongoDbPersistenceProvider
MongoDB implementation of the persistence provider.
public sealed class MongoDbPersistenceProvider : IDocumentPersistenceProvider, IPersistenceProvider, IAsyncDisposable, IDisposable, IPersistenceProviderHealth, IPersistenceProviderTransaction, IPersistenceProviderConnection
- Inheritance
-
MongoDbPersistenceProvider
- Implements
- Inherited Members
Constructors
MongoDbPersistenceProvider(ILogger<MongoDbPersistenceProvider>)
Initializes a new instance of the MongoDbPersistenceProvider class for testing.
public MongoDbPersistenceProvider(ILogger<MongoDbPersistenceProvider> logger)
Parameters
loggerILogger<MongoDbPersistenceProvider>The logger instance.
MongoDbPersistenceProvider(IOptions<MongoDbProviderOptions>, ILogger<MongoDbPersistenceProvider>)
Initializes a new instance of the MongoDbPersistenceProvider class.
public MongoDbPersistenceProvider(IOptions<MongoDbProviderOptions> options, ILogger<MongoDbPersistenceProvider> logger)
Parameters
optionsIOptions<MongoDbProviderOptions>The MongoDB provider options.
loggerILogger<MongoDbPersistenceProvider>The logger instance.
Properties
ConnectionString
Gets the connection string or connection configuration for the provider.
public string ConnectionString { get; }
Property Value
- string
The connection string or connection configuration for the provider.
DocumentStoreType
Gets the document store type (e.g., "MongoDB", "ElasticSearch", "CosmosDB").
public string DocumentStoreType { get; }
Property Value
- string
The document store type (e.g., "MongoDB", "ElasticSearch", "CosmosDB").
IsAvailable
Gets a value indicating whether the provider is ready to serve requests.
public bool IsAvailable { get; }
Property Value
Remarks
Readiness may be established either at construction — when the provider is handed an already
connected dependency, such as a client it does not own — or by InitializeAsync for
providers that build their own connection from configuration. Both are supported; which one
applies is a property of the constructor you chose, not of the interface.
Implementations must report false once disposed, and may report false while otherwise ready if the underlying connection has dropped. This is a cheap, non-blocking status flag rather than a probe: reading it must not perform I/O.
Name
Gets the identity of this configured provider instance.
public 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 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.
RetryPolicy
Gets the retry policy used for DataRequest execution.
public IDataRequestRetryPolicy RetryPolicy { get; }
Property Value
- IDataRequestRetryPolicy
The retry policy used for DataRequest execution.
Methods
BeginSessionAsync(CancellationToken)
Begins a new MongoDB session.
public Task<IClientSessionHandle> BeginSessionAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IClientSessionHandle>
A new MongoDB client session.
Exceptions
CreateTransactionScope(IsolationLevel, TimeSpan?)
Creates a new transaction scope for coordinating operations across multiple DataRequests.
public ITransactionScope CreateTransactionScope(IsolationLevel isolationLevel = IsolationLevel.ReadCommitted, TimeSpan? timeout = null)
Parameters
isolationLevelIsolationLevelThe transaction isolation level.
timeoutTimeSpan?The transaction timeout.
Returns
- ITransactionScope
A new transaction scope.
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
DisposeAsync()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.
public ValueTask DisposeAsync()
Returns
- ValueTask
A task that represents the asynchronous dispose operation.
ExecuteAggregationAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult>, CancellationToken)
public Task<TResult> ExecuteAggregationAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult> aggregationRequest, CancellationToken cancellationToken)
Parameters
aggregationRequestIDocumentDataRequest<TConnection, TResult>cancellationTokenCancellationToken
Returns
- Task<TResult>
Type Parameters
TConnectionTResult
ExecuteBulkDocumentAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult>, CancellationToken)
public Task<TResult> ExecuteBulkDocumentAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult> bulkDocumentRequest, CancellationToken cancellationToken)
Parameters
bulkDocumentRequestIDocumentDataRequest<TConnection, TResult>cancellationTokenCancellationToken
Returns
- Task<TResult>
Type Parameters
TConnectionTResult
ExecuteDocumentAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult>, CancellationToken)
Executes a DocumentDataRequest with document store-specific optimizations.
public Task<TResult> ExecuteDocumentAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult> documentRequest, CancellationToken cancellationToken)
Parameters
documentRequestIDocumentDataRequest<TConnection, TResult>The document data request to execute.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<TResult>
The result of the document request execution.
Type Parameters
TConnectionThe type of the document database connection.
TResultThe type of the result.
ExecuteDocumentBatchAsync<TConnection>(IEnumerable<IDocumentDataRequest<TConnection, object>>, CancellationToken)
Executes a batch of DocumentDataRequests as a single unit for improved performance.
public Task<IEnumerable<object>> ExecuteDocumentBatchAsync<TConnection>(IEnumerable<IDocumentDataRequest<TConnection, object>> documentRequests, CancellationToken cancellationToken)
Parameters
documentRequestsIEnumerable<IDocumentDataRequest<TConnection, object>>The collection of DocumentDataRequests to execute as a batch.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IEnumerable<object>>
A collection of results corresponding to each request in the batch.
Type Parameters
TConnectionThe type of the document database connection.
ExecuteDocumentInTransactionAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult>, ITransactionScope, CancellationToken)
Executes a DocumentDataRequest within a transaction scope (if supported by the document store).
public Task<TResult> ExecuteDocumentInTransactionAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult> documentRequest, ITransactionScope transactionScope, CancellationToken cancellationToken)
Parameters
documentRequestIDocumentDataRequest<TConnection, TResult>The document data request to execute.
transactionScopeITransactionScopeThe transaction scope to use.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<TResult>
The result of the document request execution.
Type Parameters
TConnectionThe type of the document database connection.
TResultThe type of the result.
ExecuteInTransactionAsync<TConnection, TResult>(IDataRequest<TConnection, TResult>, ITransactionScope, CancellationToken)
Executes a DataRequest within a transaction scope with retry logic.
public Task<TResult> ExecuteInTransactionAsync<TConnection, TResult>(IDataRequest<TConnection, TResult> request, ITransactionScope transactionScope, CancellationToken cancellationToken) where TConnection : IDisposable
Parameters
requestIDataRequest<TConnection, TResult>The data request to execute.
transactionScopeITransactionScopeThe transaction scope to use.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<TResult>
The result of the data request execution.
Type Parameters
TConnectionThe type of the database connection.
TResultThe type of the result.
ExecuteInTransactionAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult>, ITransactionScope, CancellationToken)
Executes a MongoDB-specific document data request within a transaction scope with automatic commit/rollback handling.
public Task<TResult> ExecuteInTransactionAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult> request, ITransactionScope transactionScope, CancellationToken cancellationToken)
Parameters
requestIDocumentDataRequest<TConnection, TResult>The MongoDB document data request to execute.
transactionScopeITransactionScopeThe transaction scope to use. Must be a Excalibur.Data.MongoDB.MongoDbTransactionScope.
cancellationTokenCancellationTokenA token to observe while waiting for the task to complete.
Returns
- Task<TResult>
A task that represents the asynchronous operation. The task result contains the result of the document request execution.
Type Parameters
TConnectionThe type of the MongoDB database connection.
TResultThe type of the result.
Exceptions
- ArgumentNullException
Thrown when
requestortransactionScopeis null.- ArgumentException
Thrown when
transactionScopeis not a Excalibur.Data.MongoDB.MongoDbTransactionScope.- InvalidOperationException
Thrown when the MongoDB database is not initialized.
- ObjectDisposedException
Thrown when this provider has been disposed.
ExecuteIndexOperationAsync<TConnection>(IDocumentDataRequest<TConnection, string>, CancellationToken)
public Task<string> ExecuteIndexOperationAsync<TConnection>(IDocumentDataRequest<TConnection, string> indexRequest, CancellationToken cancellationToken)
Parameters
indexRequestIDocumentDataRequest<TConnection, string>cancellationTokenCancellationToken
Returns
Type Parameters
TConnection
GetCollectionInfoAsync(string, CancellationToken)
public Task<IDictionary<string, object>> GetCollectionInfoAsync(string collectionName, CancellationToken cancellationToken)
Parameters
collectionNamestringcancellationTokenCancellationToken
Returns
GetCollection<T>(string)
Gets a MongoDB collection.
public IMongoCollection<T> GetCollection<T>(string collectionName)
Parameters
collectionNamestringThe collection name.
Returns
- IMongoCollection<T>
The MongoDB collection.
Type Parameters
TThe document type.
Exceptions
GetDatabase()
Gets the MongoDB database instance.
public IMongoDatabase GetDatabase()
Returns
- IMongoDatabase
The MongoDB database.
Exceptions
GetDocumentStoreStatisticsAsync(CancellationToken)
public Task<IDictionary<string, object>> GetDocumentStoreStatisticsAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationToken
Returns
GetMetricsAsync(CancellationToken)
Gets provider-specific health and performance metrics.
public Task<IDictionary<string, object>> GetMetricsAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task<IDictionary<string, object>>
A dictionary of metric names and values.
Remarks
The returned dictionary MUST contain two identifying entries, and they carry different dimensions:
-
"Provider"is the engine identity — a fixed literal, constant per implementation and identical for every instance of it (for example"SqlServer"for every SQL Server instance). It MUST NOT vary with configuration, and in particular MUST NOT be set from Name, which is the instance dimension and would make the engine unreadable. -
"Name"is the instance identity — the value of Name, which distinguishes two separately configured instances of the same engine.
Together they let a consumer aggregating across a mixed deployment group by engine and still
attribute a reading to the instance that produced it. Keys are compared with an ordinal comparer,
so the casing is part of the contract -- "provider" is a different key and does not satisfy
it. Every other key is provider-specific; the convention is PascalCase. The conformance suite
verifies the required entries.
GetService(Type)
Gets an implementation-specific service. Returns this for IPersistenceProviderHealth and IPersistenceProviderTransaction.
public object? GetService(Type serviceType)
Parameters
serviceTypeTypeThe type of the requested service.
Returns
GetSupportedOperationTypes()
public IEnumerable<string> GetSupportedOperationTypes()
Returns
InitializeAsync(IPersistenceOptions, CancellationToken)
Initializes the provider with the specified options.
public Task InitializeAsync(IPersistenceOptions options, CancellationToken cancellationToken)
Parameters
optionsIPersistenceOptionsThe persistence options.
cancellationTokenCancellationTokenThe cancellation token.
Returns
- Task
A task representing the asynchronous operation.
TestConnectionAsync(CancellationToken)
Tests the connection to the persistence provider.
public Task<bool> TestConnectionAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenThe cancellation token.
Returns
ValidateDocumentRequest<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult>)
Validates that a DocumentDataRequest is compatible with this document store provider.
public bool ValidateDocumentRequest<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult> documentRequest)
Parameters
documentRequestIDocumentDataRequest<TConnection, TResult>The DocumentDataRequest to validate.
Returns
- bool
True if the request is valid for this provider; otherwise, false.
Type Parameters
TConnectionThe type of the document database connection.
TResultThe type of the result.