CoreEx.Cosmos 4.1.0

CoreEx.Cosmos

Provides the core Azure Cosmos DB access layer: ICosmosDb/CosmosDb as the CoreEx-Cosmos bridge, CosmosDbContainer<TModel> and CosmosDbMappedContainer<TValue, TModel, TMapper> for typed CRUD + query operations, CosmosDbQuery<TModel> as the composable, invoker-wrapped query/materialization type, CosmosDbInvoker for structured operation logging and exception mapping, a CosmosDbUnitOfWork transactional outbox (TransactionalBatch-based), and a Change Feed Processor-based outbox relay.

Overview

CoreEx.Cosmos wraps the Microsoft.Azure.Cosmos SDK with the same CoreEx data conventions used elsewhere in the framework: ETag/optimistic-concurrency checking (via Cosmos DB's native If-Match semantics), multi-tenancy filtering, logical-delete filtering, type-discriminator filtering (for several business model types sharing one container/partition), change-log stamping, PagingArgs paging, and Result<T> (Railway-Oriented Programming) pipeline integration.

The central type is CosmosDb, which holds the CosmosClient/Database and exposes Container<TModel>(id, configure?) as the entry point for all strongly-typed CRUD. CosmosDbContainer<TModel> provides GetAsync, CreateAsync, UpdateAsync, DeleteAsync, UpsertAsync, and Query (returning a CosmosDbQuery<TModel>) — each applying the applicable CoreEx cross-cutting pipeline. CosmosDbMappedContainer<TValue, TModel, TMapper> adds an IBiDirectionMapper layer for use cases where the Cosmos document model type differs from the domain entity type.

The Outbox sub-namespace implements the Transactional Outbox pattern for Cosmos DB: CosmosDbUnitOfWork enlists business mutations and outbox event documents into the same TransactionalBatch (Cosmos DB's only atomic multi-operation primitive - atomic within a single container/logical partition key only), so the write is genuinely all-or-nothing without a separate outbox table. A Change Feed Processor-based relay (CosmosDbOutboxRelay) then decodes, publishes, and cleans up these documents, self-pausing/self-resuming via a circuit breaker on sustained publish failure.

This is a sibling package to CoreEx.Database/CoreEx.Database.SqlServer/CoreEx.Database.Postgres, not a provider underneath CoreEx.Database — Cosmos DB is a document store with no ADO.NET-shaped connection/transaction/parameter surface, so it warrants its own package family while still sharing the same ergonomic CRUD/ROP/paging conventions, and (for the outbox relay specifically) the same harmonized metric names and shared trace-linking helper as CoreEx.Database.SqlServer/CoreEx.Database.Postgres.

This package provides the core CRUD + query access layer, a TransactionalBatch-based transactional outbox (CosmosDbUnitOfWork/CosmosDbEventPublisher), and a Change Feed Processor-based outbox relay (CosmosDbOutboxRelay) - happy path only. Not included: poison-message/dead-letter handling for the relay (a permanently-failing outbox document is redelivered forever by the Change Feed Processor's own native backoff, with no built-in give-up - to be designed as one shared pattern across the SQL Server/Postgres/Cosmos relays, not Cosmos-specific), a multi-query (IMultiQueryArgs) equivalent, and any EF Core-Cosmos integration.

Key capabilities

• 🔗 Cosmos DB bridge: CosmosDb wraps a DI-resolved CosmosClient (typically registered via Aspire's builder.AddAzureCosmosClient("Cosmos")) and caches both raw SDK Container instances (per container id) and CosmosDbContainer<TModel> instances (per (containerId, TModel) pair - not container id alone, since a container may legitimately host more than one type-discriminated model).
• 📖 Typed CRUD: CosmosDbContainer<TModel> provides GetAsync, CreateAsync, UpdateAsync, DeleteAsync, UpsertAsync with automatic ETag/concurrency validation (native Cosmos DB If-Match), tenant isolation, and logical-delete handling.
• 🔁 Mapped CRUD: CosmosDbMappedContainer<TValue, TModel, TMapper> layers an IBiDirectionMapper<TValue, TModel> over CosmosDbContainer<TModel>, mapping between the domain entity type and the Cosmos DB document model type transparently for all CRUD operations.
• 🔍 Composable query: CosmosDbContainer<TModel>.Query(query?, args?) returns a CosmosDbQuery<TModel> — a dedicated wrapper (not a bare IQueryable<TModel>) constructed over Container.GetItemLinqQueryable<TModel>(); additional filtering/ordering is composed via the query delegate (standard LINQ Where/OrderBy), and any WithTenantFilter/WithLogicalDeleteFilter/WithTypeDiscriminator predicates from CosmosDbModelOptions are applied automatically (see CosmosDbQuery<TModel>.AsQueryable(CosmosDbArgs?), with an optional CosmosDbArgs.BypassFilters override).
• 📄 Invoker-wrapped materializers: CosmosDbQuery<TModel> provides instance-method materializers — ToListAsync, ToCollectionAsync<TColl>, ToItemsResultAsync, SingleAsync/SingleOrDefaultAsync/FirstAsync/FirstOrDefaultAsync, ToMappedItemsAsync, ToMappedItemsResultAsync (plus a WithResultAsync ROP counterpart for each) — using Skip/Take (translated by the Cosmos DB LINQ provider to OFFSET…LIMIT) via WithPaging(PagingArgs?). Being instance methods on CosmosDbQuery<TModel> rather than IQueryable<T> extensions, they structurally cannot collide with CoreEx.EntityFrameworkCore's identically-named EfDbExtensions (see AGENTS.md), and every materializer routes through CosmosDbInvoker for structured logging and CosmosException mapping.
• 🏷️ ETag / concurrency: for an UpdateAsync, the model's IETag.ETag is mapped into ItemRequestOptions.IfMatchEtag (where CosmosDbArgs.AutoMapETag is true, the default); Cosmos DB enforces the optimistic-concurrency check server-side and returns a 412 Precondition Failed, which CosmosDbInvoker converts to a ConcurrencyException/Result.ConcurrencyError.
• 🧠 Change tracker: a per-scope snapshot cache (ICosmosDb.ChangeTracker) makes repeat point GetAsync calls free of RU cost; UpdateAsync pre-reads to copy back server-managed values (created audit, unmapped additional properties) and skips the write when nothing changed (DataResult.WasMutated == false). Opt out per call with CosmosDbArgs.ClearChangeTrackerAfterGet; cleared when the root unit-of-work transaction ends. Per-document version checks prevent in-flight reads from repopulating snapshots after eviction or clearing; immediate writes also evict on completion. Needs UseSystemTextJsonSerializerWithOptions.
• 🔒 Multi-tenancy: non-query operations automatically reject a mismatched IReadOnlyTenantId.TenantId as not-found; Query() only applies the equivalent TenantId == executionContext.TenantId predicate when CosmosDbModelOptions.WithTenantFilter() has been configured.
• 🗑️ Logical delete: entities implementing ILogicallyDeleted are soft-deleted (IsDeleted = true via a read-modify-ReplaceItemAsync) on DeleteAsync rather than physically removed; a physical DeleteAsync is idempotent (a 404 is not an error).
• 🏷️ Type discriminator (multi-type containers): CosmosDbModelOptions<TModel>.WithTypeDiscriminator() reuses the existing ITypeDiscriminator/IReadOnlyTypeDiscriminator hook (auto-populated by Model.PrepareCreate/PrepareUpdate) to let several business model types safely share one container/partition — no envelope/wrapper type required.
• ⏳ Time-to-live: CosmosDbModelOptions<TModel>.WithTimeToLive(Func<TModel, int?>) computes and applies a document's ttl on CreateAsync/UpdateAsync (requires TModel to implement the mutable ITimeToLive — Cosmos DB's ttl is a document-body field, not a separate SDK request option, so a computed value can only take effect by being written back onto the model). Where not configured, a model's own ITimeToLive.TimeToLive value (if any) simply serializes through as-is; ITimeToLive/IReadOnlyTimeToLive live in core CoreEx.Data (alongside IPartitionKey/ITypeDiscriminator) for reuse by a future non-Cosmos NoSQL package.
• 📚 Reference data: CosmosDbReferenceData provides CreateAsync/UpdateAsync/ActivateAsync/DeactivateAsync/DeleteAsync for reference data (Cosmos counterpart of EfDbReferenceData); wired up by CoreEx.CodeGen when a repository: Cosmos entity sets mutability.
• 🔑 Fixed partition key: CosmosDbModelOptions<TModel>.WithFixedPartitionKey(string?) configures one constant partition key value for the whole container — suitable for small, bounded containers where partitioning isn't meaningful (Cosmos DB's own guidance: a container well under the 20 GB/10,000 RU/s per-logical-partition limits typically needs only one or two physical partitions regardless of partition key cardinality). It also defaults GetAsync/DeleteAsync's partitionKey parameter (now optional) when the caller omits it — WithPartitionKey(Func<TModel, string?>)'s per-model function cannot do this, since Get/Delete have no model instance to invoke it against. The two are mutually exclusive (configuring both throws InvalidOperationException), and either always wins over — but must not silently disagree with — a non-null value the model already carries via IReadOnlyPartitionKey (a genuine mismatch throws rather than being overridden, since Cosmos DB itself requires the document body's partition-key-path value to agree with the value supplied for the operation).
• 📝 Structured logging: CosmosDbInvoker wraps every CRUD CosmosDb operation with structured log entries (tracing/Activity spans are intentionally disabled via IsTracingDisabled - CRUD is high-frequency) and converts CosmosException into the corresponding CoreEx exception (NotFoundException/DuplicateException/ConcurrencyException). The outbox relay's CosmosDbOutboxRelayInvoker (Outbox sub-namespace) is a separate, tracing-enabled invoker - relay batch processing is comparatively low-frequency and specifically where distributed-tracing visibility matters most.
• 🔄 Transactional outbox: CosmosDbUnitOfWork implements IUnitOfWork, enlisting CosmosDbContainer<TModel> Create/Update/Delete calls made within its TransactionAsync scope into one ambient TransactionalBatch (client-side fail-fast if two enlisted operations target different containers/partition keys); CosmosDbEventPublisher (an IEventPublisher) enlists outbox event documents into the same batch, so the business mutation and its event are atomic without a separate outbox table. Outbox documents are auto-excluded from ordinary business queries via a reserved $outbox id-prefix (no opt-in required). IUnitOfWork.SynchronizeETag<T> resolves a mapped contract's true, server-assigned ETag after the batch commits (deferred execution means it isn't known upfront) by correlating on CompositeKey, not object reference.
• 📤 Outbox relay: CosmosDbOutboxRelay/CosmosDbOutboxRelayProcessor (Outbox sub-namespace) consume outbox event documents via a Cosmos DB Change Feed Processor (push-based, SDK-managed - not a polling loop like the SQL Server/Postgres relay), decode/publish/cleanup-delete each batch, and self-pause/self-resume via a CircuitBreakerResiliency<TOwner>-based circuit breaker on a sustained publish-failure ratio. Register via builder.AddCosmosDbOutboxRelayHostedService(containerId, servicesCount?) - one call per outbox-hosting container, each with its own concurrency count. This registers the relay only; a genuine destination IEventPublisher (e.g. Azure Service Bus, matching the SQL Server/Postgres samples) must also be registered - see AGENTS.md. CosmosDbEventPublisher (the write-side publisher, above) must never be registered for this role; CosmosDbOutboxRelayProcessor.ProcessBatchAsync detects that misconfiguration and throws immediately with an actionable message rather than failing deeper inside the publish call.
• 📊 Outbox metrics: CosmosMetrics exposes .NET Meter instruments harmonized with SqlServerMetrics/PostgresMetrics: cosmos.outbox.enqueue (counter), cosmos.outbox.relay.publish and cosmos.outbox.relay.publish.failed (counters), cosmos.outbox.relay.oldest_lag and cosmos.outbox.relay.newest_lag (histograms in ms), plus Cosmos-specific cosmos.outbox.relay.cleanup.deleted/cosmos.outbox.relay.cleanup.failed (the relay's own post-publish document cleanup has no SQL Server/Postgres equivalent).
• 📥 Batch import & container provisioning: CosmosDbBatch.ImportBatchAsync(Async)/ImportDiscriminatedBatchAsync load raw JSON directly into a Container/Database (no CoreEx.Cosmos model type involved); CosmosDbContainerExtensions.ReplaceOrCreateContainerAsync/DeleteContainerIfExistsAsync provision or reset a container from code. Neither depends on the rest of this package - useful for data seeding, bulk/one-off loads, and migrations alike. On top of these, CoreEx.Cosmos.Provisioning (CosmosDbProvisioner, CosmosDbConsole, CosmosDbProvisionArgs) provides a reusable, DbEx-style Drop/Create/Reset/Data migration console for dev/test - see Contoso.Customers.Database.
• 🧩 Multi-set queries: ICosmosDb.SelectMultiSetAsync/SelectMultiSetWithResultAsync(containerId, MultiSetOptions, cancellationToken?) (Extended namespace) read multiple, type-discriminator-keyed sets of documents from the same container/partition in one round-trip - the Cosmos DB equivalent of CoreEx.Database.Extended's positional/ordered multi-set queries, adapted for a discriminator-keyed (not positional) demux. MultiSetSingleArgs<TModel>/MultiSetCollArgs<TColl, TModel> accumulate matching documents (each per-item tenant/logical-delete/additive-filter-checked via CosmosDbContainer<TModel>.CheckModel); TModel must implement IReadOnlyTypeDiscriminator. The type-discriminator's JSON property name is resolved once per call from the ambient CosmosClientOptions.UseSystemTextJsonSerializerWithOptions naming policy (e.g. camelCase). Co-located outbox event documents are always excluded server-side; where a model's CosmosDbModelOptions<TModel>.WithTenantFilter/WithLogicalDeleteFilter is configured, an additional defensive, IS_DEFINED-guarded SQL predicate is layered in as a server-side (RU/bandwidth) optimization - never excluding a document purely for predating the property. MultiSetOptions.Args.QueryRequestOptions, where supplied, takes precedence over one built from MultiSetOptions.PartitionKey (a genuine mismatch between the two throws ArgumentException). SelectMultiSetWithResultAsync returns a Result (Railway-Oriented Programming) only for a genuine business/domain-level outcome (a mapped CosmosException, or a WithFilter authorization-style denial) - MinimumRows/MaximumRows/malformed-response/argument-validation conditions remain plain exceptions even from this method, consistent with Result being reserved for expected errors, not exceptions; SelectMultiSetAsync is a thin ThrowOnError() wrapper over it. See AGENTS.md for the full mechanism.

Outbox tracing defaults mirror the relational relays: background change-feed polling, lease maintenance, and cleanup SDK/HTTP spans are suppressed, while publishing spans and originating-trace relay markers remain enabled. Metrics and warning/error logs remain available. Set CosmosDbOutboxRelayOptions.IsInstrumentationEnabledForPolling to true before start/resume to diagnose background processing; CosmosDbOutboxRelayProcessor.IsInstrumentationEnabledForPublishing independently controls publishing instrumentation (default true).

Key types

Namespaces

Related Namespaces

• CoreEx.Data - IUnitOfWork, PagingArgs, ItemsResult<T>, DataResult, IPartitionKey/IReadOnlyPartitionKey, ITenantId, ILogicallyDeleted, ITypeDiscriminator, Model (PrepareCreate/PrepareUpdate), IMultiSetArgsCore (shared base for Extended.IMultiSetArgs's discriminator-keyed multi-set queries) — all reused as-is, unchanged; CosmosDbUnitOfWork implements IUnitOfWork directly (not a Cosmos-specific sub-interface), keeping application-layer services provider-agnostic.
• CoreEx.Mapping - IBiDirectionMapper<TSource, TDestination> is the mapper contract used by CosmosDbMappedContainer.
• CoreEx.EntityFrameworkCore - the closest structural analogue (EfDb/EfDbModel/EfDbMappedModel); CosmosDbContainer<TModel> mirrors EfDbModel<TModel>'s CRUD/ROP shape, adapted to the Cosmos DB SDK.
• CoreEx.Invokers - CosmosDbInvoker and CosmosDbOutboxRelayInvoker extend InvokerBase for structured logging/tracing.
• CoreEx.Events - IEventPublisher/EventPublisherBase (CosmosDbEventPublisher's base), CloudEventTracingExtensions.LinkTraceContext (used by the relay to connect its publish span back to each original producer's trace), and EventFormatter's CloudEvents conversion, shared unchanged with CoreEx.Database's outbox relay.
• CoreEx.Hosting - HostedServiceBase, CircuitBreakerResiliency<TOwner> (the relay's self-pause/self-resume mechanism, shared with CoreEx.Azure.Messaging.ServiceBus's receiver), ResilienceOwner<TOwner>.
• CoreEx.Database - the relational sibling family's equivalent outbox relay (DatabaseOutboxRelayBase); Cosmos DB's Change Feed Processor-based push model is deliberately structured differently (mirroring the Azure Service Bus receiver instead), but shares metric naming and trace-linking with it.

Additional Resources

• Microsoft.Azure.Cosmos - The Azure Cosmos DB SDK this package uses.
• Change Feed Processor - The push-based mechanism underlying CosmosDbOutboxRelay.

AI Usage Guide

An AGENTS.md file is included with this package. AI coding assistants (GitHub Copilot, Claude, Cursor, etc.) that support workspace-injected package documentation will automatically surface concise usage guidance, code examples, and Do Not rules for this package without requiring a local CoreEx checkout.