Table of Contents

Class MongoDbPersistenceProvider

Namespace
Excalibur.Data.MongoDB
Assembly
Excalibur.Data.MongoDB.dll

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

logger ILogger<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

options IOptions<MongoDbProviderOptions>

The MongoDB provider options.

logger ILogger<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

bool

true while the provider is ready to serve and has not been disposed; otherwise, false.

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

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IClientSessionHandle>

A new MongoDB client session.

Exceptions

InvalidOperationException

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

isolationLevel IsolationLevel

The transaction isolation level.

timeout TimeSpan?

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

aggregationRequest IDocumentDataRequest<TConnection, TResult>
cancellationToken CancellationToken

Returns

Task<TResult>

Type Parameters

TConnection
TResult

ExecuteBulkDocumentAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult>, CancellationToken)

public Task<TResult> ExecuteBulkDocumentAsync<TConnection, TResult>(IDocumentDataRequest<TConnection, TResult> bulkDocumentRequest, CancellationToken cancellationToken)

Parameters

bulkDocumentRequest IDocumentDataRequest<TConnection, TResult>
cancellationToken CancellationToken

Returns

Task<TResult>

Type Parameters

TConnection
TResult

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

documentRequest IDocumentDataRequest<TConnection, TResult>

The document data request to execute.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<TResult>

The result of the document request execution.

Type Parameters

TConnection

The type of the document database connection.

TResult

The 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

documentRequests IEnumerable<IDocumentDataRequest<TConnection, object>>

The collection of DocumentDataRequests to execute as a batch.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<IEnumerable<object>>

A collection of results corresponding to each request in the batch.

Type Parameters

TConnection

The 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

documentRequest IDocumentDataRequest<TConnection, TResult>

The document data request to execute.

transactionScope ITransactionScope

The transaction scope to use.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<TResult>

The result of the document request execution.

Type Parameters

TConnection

The type of the document database connection.

TResult

The 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

request IDataRequest<TConnection, TResult>

The data request to execute.

transactionScope ITransactionScope

The transaction scope to use.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<TResult>

The result of the data request execution.

Type Parameters

TConnection

The type of the database connection.

TResult

The 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

request IDocumentDataRequest<TConnection, TResult>

The MongoDB document data request to execute.

transactionScope ITransactionScope

The transaction scope to use. Must be a Excalibur.Data.MongoDB.MongoDbTransactionScope.

cancellationToken CancellationToken

A 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

TConnection

The type of the MongoDB database connection.

TResult

The type of the result.

Exceptions

ArgumentNullException

Thrown when request or transactionScope is null.

ArgumentException

Thrown when transactionScope is 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

indexRequest IDocumentDataRequest<TConnection, string>
cancellationToken CancellationToken

Returns

Task<string>

Type Parameters

TConnection

GetCollectionInfoAsync(string, CancellationToken)

public Task<IDictionary<string, object>> GetCollectionInfoAsync(string collectionName, CancellationToken cancellationToken)

Parameters

collectionName string
cancellationToken CancellationToken

Returns

Task<IDictionary<string, object>>

GetCollection<T>(string)

Gets a MongoDB collection.

public IMongoCollection<T> GetCollection<T>(string collectionName)

Parameters

collectionName string

The collection name.

Returns

IMongoCollection<T>

The MongoDB collection.

Type Parameters

T

The document type.

Exceptions

InvalidOperationException

GetDatabase()

Gets the MongoDB database instance.

public IMongoDatabase GetDatabase()

Returns

IMongoDatabase

The MongoDB database.

Exceptions

InvalidOperationException

GetDocumentStoreStatisticsAsync(CancellationToken)

public Task<IDictionary<string, object>> GetDocumentStoreStatisticsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Returns

Task<IDictionary<string, object>>

GetMetricsAsync(CancellationToken)

Gets provider-specific health and performance metrics.

public Task<IDictionary<string, object>> GetMetricsAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The 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

serviceType Type

The type of the requested service.

Returns

object

The service instance, or null if not supported.

GetSupportedOperationTypes()

public IEnumerable<string> GetSupportedOperationTypes()

Returns

IEnumerable<string>

InitializeAsync(IPersistenceOptions, CancellationToken)

Initializes the provider with the specified options.

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

TestConnectionAsync(CancellationToken)

Tests the connection to the persistence provider.

public Task<bool> TestConnectionAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token.

Returns

Task<bool>

true if the connection is successful; otherwise, false.

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

documentRequest IDocumentDataRequest<TConnection, TResult>

The DocumentDataRequest to validate.

Returns

bool

True if the request is valid for this provider; otherwise, false.

Type Parameters

TConnection

The type of the document database connection.

TResult

The type of the result.