Franz.Common.AzureCosmosDB 2.2.16

Franz.Common.AzureCosmosDB (v1.7.7)

A specialized persistence library within the Franz Framework, providing seamless integration with Azure Cosmos DB.

This package extends the framework’s polyglot persistence capabilities by enabling:

• NoSQL document storage
• Outbox pattern messaging
• Dead-letter storage
• Cosmos-backed distributed transaction patterns
• EF Core Cosmos provider alignment

All designed following Franz’s deterministic, message-driven architecture.

Features

🚀 Cosmos DB Bootstrapping

• High-level ServiceCollectionExtensions for Cosmos initialization.

• Automatic provisioning of:

  • CosmosClient
  • Database
  • Containers with partitioning

• Supports typed container resolution through configuration patterns.

📬 Outbox & Dead-Letter Messaging

• CosmosDBMessageStore implements IMessageStore from Franz.Common.Messaging.Storage.

• Guarantees:

  • Async-safe writes
  • Deterministic message IDs
  • Automatic dead-lettering
  • Resilient retry-based delivery

Now supports Batch Writes introduced in 1.7.5 for improved performance.

📦 Repository Support

A generic Cosmos repository abstraction:

ICosmosRepository<T>

providing:

• CRUD operations
• Partition key awareness
• Automatic model-to-container mapping
• Optional optimistic concurrency

Now aligned with the Cosmos EF Provider conventions for maximum portability across SQL, Mongo, and Cosmos stores.

🔧 EF Core Cosmos Provider (1.7.x Integration)

Franz 1.7.x unifies Cosmos EF Core support:

• New CosmosDbContextBase
• Conventions via ApplyCosmosConventions()
• Default container fallback for multi-container apps
• Deterministic outbox dispatch integration using IDispatcher

This makes CosmosDB a first-class citizen in the event-sourced pipeline.

⚡ Version 1.7.5 Additions

Major Additions

• Full alignment with .NET 10.0 SDK.
• Cosmos EF provider stabilization & conventions.
• Unified Cosmos document serializer aligned with Franz’s null-safety rules.
• Deterministic container creation logic (optional auto-provisioning).
• Batch persistence for message-based storage.

Fixes & Improvements

• Hardened message serialization for CosmosDB.
• Fixed dead-letter partition routing.
• Improved DI boot ordering for Cosmos-backed message stores.
• Refactored container naming strategy for multi-tenant scenarios.
• Ensured async safety across the entire Cosmos subsystem.

Installation

From Private Azure Feed

dotnet nuget add source "https://your-private-feed-url" \
  --name "AzurePrivateFeed" \
  --username "YourAzureUsername" \
  --password "YourAzurePassword" \
  --store-password-in-clear-text

Install:

dotnet add package Franz.Common.AzureCosmosDB

Usage

1️⃣ Configure Cosmos DB

{
  "CosmosDb": {
    "ConnectionString": "...",
    "DatabaseName": "FranzAppDb",
    "Containers": {
      "Messages": "outbox",
      "DeadLetters": "failed"
    }
  }
}

2️⃣ Register Cosmos in DI

services.AddCosmosDatabase(Configuration);

services.AddCosmosMessageStore(
    Configuration["CosmosDb:ConnectionString"],
    Configuration["CosmosDb:DatabaseName"]);

3️⃣ Using the Message Store

var msg = new Message("hello");
await messageStore.SaveAsync(msg);

Dependencies

• Franz.Common.Messaging
• Franz.Common.Messaging.Storage
• Microsoft.Azure.Cosmos
• Franz.Common.EntityFramework (optional for EF provider)

Current Version: v2.2.16

Changelog

v2.0.1 – Internal Modernization

• Messaging and infrastructure refactored for async, thread-safety, and modern .NET 10 patterns.
• All APIs remain fully backward compatible.
• Tests, listeners, and pipeline components modernized.

Version 1.7.8

🔹 Updated to .NET 10.0.3 SDK.

Version 1.7.5

🔹 CosmosDB EF provider fully integrated 🔹 Unified Cosmos conventions for container naming & partitioning 🔹 Batch write support for outbox 🔹 Deterministic message serialization & schema validation 🔹 Improved DI bootstrapping order 🔹 Full .NET 10 alignment

Version 1.6.2

• Introduced Cosmos DB integration.
• Added CosmosDBMessageStore.
• Added generic repository pattern.
• Added outbox/dead-letter support.

Version 1.6.20

• Updated to .NET 10 SDK.

Contributing

Internal to Franz Framework development team.

License

MIT