From c751d70dadba96c52ba4a9c3333b12fa1853e2da Mon Sep 17 00:00:00 2001 From: Quezlatch Date: Mon, 6 Jul 2026 08:56:20 +0100 Subject: [PATCH 1/2] add azure blob storage section --- .../dotnet-next/infra/azure-blob-storage.md | 114 ++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 src/content/docs/dotnet-next/infra/azure-blob-storage.md diff --git a/src/content/docs/dotnet-next/infra/azure-blob-storage.md b/src/content/docs/dotnet-next/infra/azure-blob-storage.md new file mode 100644 index 0000000..1fc0266 --- /dev/null +++ b/src/content/docs/dotnet-next/infra/azure-blob-storage.md @@ -0,0 +1,114 @@ +--- +title: "Azure Blob Storage" +description: "Projections for Azure Blob Storage" +sidebar: + order: 8 +--- + +[Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs/) is a fully managed object storage in the cloud. Eventuous supports Azure Service Bus for projections using the `Eventuous.Azure.Storage.Blobs` package. +It allows you to project event store events to Azure Blob Storage as state objects, maintaining a separate state document for each event stream. + +## Using projections + +Create your own projection class that inherits from `BlobStorageProjector` where `T` is your state type. The state type must be a class with a parameterless constructor. + +Register event handlers using the `On` methods. When an event is received, the projector retrieves the current state blob (or creates a new state instance if the blob doesn't exist), applies the event to the state using the registered event handler, and uploads the updated state back to Blob Storage. + +```csharp +public class BookingProjection : BlobStorageProjector { + public BookingProjection(BlobServiceClient client, IOptions serializerOptions) + : base(client, "bookings-container", serializerOptions.Value) { + + // Uses default blob ID from stream + On((state, evt) => { + state.RoomId = evt.RoomId; + state.CheckInDate = evt.CheckIn; + return state; + }); + + // Custom blob ID using event data + On( + (state, evt) => { + state.PaidAmount += evt.AmountPaid; + return state; + }, + context => new ValueTask($"custom-{context.Message.BookingId}") + ); + } +} +``` + +By using `IOptions` we can also use the Json serialization options as set in ASP DI. + +The blob name itself is constructed using the projection type name and stream id. This can be overriden. + + +## Projector options + +The `BlobStorageProjectorOptions` class provides several configuration options for fine-tuning the projector behavior. + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `JsonOptions` | `JsonSerializerOptions?` | `null` (uses `JsonSerializerOptions.Web`) | JSON serializer options for state serialization/deserialization. Controls formatting, naming policies, etc. | +| `RaceRetries` | `int` | `0` | Number of retry attempts for optimistic concurrency conflicts. Increase when concurrent updates are likely. | +| `IdempotencyMode` | `IdempotencyMode` | `IdempotencyMode.None` | Controls duplicate message detection behavior. | + +### Idempotency modes + +The `IdempotencyMode` enum controls how the projector handles duplicate messages: + +- **`None`** - No idempotency checks. Always processes messages and updates blobs. +- **`ByGlobalPosition`** - Skips processing if existing blob has matching global position metadata. +- **`ByMessageId`** - Skips processing if existing blob has matching message ID metadata. + +### Custom blob naming + +By default, blob names are generated using `GetBlobName(string id)` which creates names in the format `{id}/{T}.json`, where `id` defaults to the stream ID from `context.Stream.GetId()`. + +You can customize blob naming in two ways: + +**1. Override the virtual methods globally for all events:** + +```csharp +protected override string GetBlobName(string id, IMessageConsumeContext context) { + // Use stream name and type in the path + var streamName = context.Stream.ToString(); + return $"projections/{streamName}/{id}.json"; +} + +protected override string GetBlobName(string id) { + return $"{id}/{typeof(T).Name}.json"; +} +``` + +**2. Override blob ID per event handler using `getBlobId`:** + +```csharp +On( + (state, evt) => { + state.PaidAmount += evt.AmountPaid; + return state; + }, + // Custom blob ID for this specific event only + context => new ValueTask($"payments/{context.Message.BookingId}.json") +); +``` + +Use per-event blob ID overrides when you need different events to target different blob paths or naming conventions within the same projector, such as when the business identifier differs from the stream identifier. +## Features + +- **Automatic state management** - Creates new state instances when blobs don't exist +- **Optimistic concurrency control** - Uses ETags for safe concurrent updates +- **Idempotency** - Prevents duplicate processing with configurable modes +- **Retry handling** - Automatic retries for race conditions +- **Flexible blob naming** - Customizable blob ID and naming conventions +- **Metadata storage** - Automatically stores stream info, positions, and message IDs + +## Background + +The projector stores each state as a separate blob in Azure Blob Storage. Each blob contains: +- The serialized state object (JSON by default) +- Metadata including stream name, message ID, stream position, and global position +- Content type set to `application/json` + +This approach provides natural partitioning by stream and enables efficient state retrieval for individual streams. \ No newline at end of file From ef2e11fe4a157c9b2989315a73290b4533b8c5f4 Mon Sep 17 00:00:00 2001 From: Quezlatch Date: Sun, 2 Aug 2026 18:23:48 +0100 Subject: [PATCH 2/2] update idempotency mode info --- .../docs/dotnet-next/infra/azure-blob-storage.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/content/docs/dotnet-next/infra/azure-blob-storage.md b/src/content/docs/dotnet-next/infra/azure-blob-storage.md index 1fc0266..36f30c5 100644 --- a/src/content/docs/dotnet-next/infra/azure-blob-storage.md +++ b/src/content/docs/dotnet-next/infra/azure-blob-storage.md @@ -45,7 +45,7 @@ The blob name itself is constructed using the projection type name and stream id ## Projector options -The `BlobStorageProjectorOptions` class provides several configuration options for fine-tuning the projector behavior. +The `BlobStorageProjectorOptions` class provides several configuration options for fine-tuning the projector behavior. | Option | Type | Default | Description | |--------|------|---------|-------------| @@ -57,9 +57,13 @@ The `BlobStorageProjectorOptions` class provides several configuration option The `IdempotencyMode` enum controls how the projector handles duplicate messages: -- **`None`** - No idempotency checks. Always processes messages and updates blobs. -- **`ByGlobalPosition`** - Skips processing if existing blob has matching global position metadata. -- **`ByMessageId`** - Skips processing if existing blob has matching message ID metadata. +- **`None`** - No idempotency checks. Will process messages and updates blob, without +checking for duplicates. +- **`ByGlobalPosition`** - Skips processing if the existing blob has a global position set in +its metadata that indicates it has already been processed. The event global position must be greater than that stored in the blob. +- **`ByMessageId`** - Use this when building projections directly from integration events. Skips +processing if the message ID in the blob metadata matches that in the event. +Note, this means the idempotency is weaker as only the last message ID is checked. Older messages that are replayed will be processed as normal. ### Custom blob naming