> ## Documentation Index
> Fetch the complete documentation index at: https://easyaf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# IMetadataAware

> Defines a message that supports metadata for passing data between handlers in the processing pipeline.

## Definition

**Assembly:** CloudNimble.SimpleMessageBus.Core.dll

**Namespace:** CloudNimble.SimpleMessageBus.Core

## Syntax

```csharp theme={"dark"}
CloudNimble.SimpleMessageBus.Core.IMetadataAware
```

## Summary

Defines a message that supports metadata for passing data between handlers in the processing pipeline.

## Remarks

Metadata provides a way to attach additional context and data to messages without modifying the core message structure.
This is particularly useful for cross-cutting concerns like tracking, auditing, user context, and handler-to-handler
communication. The metadata survives serialization and can be accessed by any handler in the processing chain.

## Examples

```csharp theme={"dark"}
public class OrderCreatedMessage : IMessage, IMetadataAware
{
    public Guid Id { get; set; } = Guid.NewGuid();
    public ConcurrentDictionary<string, object> Metadata { get; set; } = new();
    public string OrderNumber { get; set; }
    public decimal Amount { get; set; }
}

// Usage in handler
public async Task OnNextAsync(MessageEnvelope envelope)
{
    if (envelope.Message is IMetadataAware metadataMessage)
    {
        // Read metadata set by previous handlers
        var userId = metadataMessage.Metadata.GetValueOrDefault("UserId");
        var requestId = metadataMessage.Metadata.GetValueOrDefault("RequestId");

        // Add new metadata for downstream handlers
        metadataMessage.Metadata["ProcessedBy"] = "OrderHandler";
        metadataMessage.Metadata["ProcessedAt"] = DateTime.UtcNow;
    }
}
```

## Properties

### <Icon icon="tag" iconType="duotone" color="#419AC5" size={24} className="mr-2" /> Metadata <Badge color="orange">Abstract</Badge>

Gets or sets the thread-safe metadata storage for passing data between handlers in the processing pipeline.

#### Syntax

```csharp theme={"dark"}
System.Collections.Concurrent.ConcurrentDictionary<string, object> Metadata { get; set; }
```

#### Property Value

Type: `System.Collections.Concurrent.ConcurrentDictionary<string, object>`
A [ConcurrentDictionary\`2](https://learn.microsoft.com/dotnet/api/system.collections.concurrent.concurrentdictionary-2) where keys are string identifiers and values are objects
containing the metadata. The dictionary must be thread-safe as it may be accessed concurrently.

#### Examples

```csharp theme={"dark"}
// Setting metadata in a publisher
var message = new OrderCreatedMessage { OrderNumber = "ORD-001" };
message.Metadata["UserId"] = currentUser.Id;
message.Metadata["RequestId"] = Guid.NewGuid();
message.Metadata["Source"] = "WebAPI";

// Reading metadata in a handler
var userId = message.Metadata.GetValueOrDefault("UserId")?.ToString();
var isFromAPI = message.Metadata.ContainsKey("Source") &amp;&amp;
                message.Metadata["Source"].ToString() == "WebAPI";
```

#### Remarks

This metadata dictionary is preserved during message serialization/deserialization and provides a mechanism
for handlers to communicate with each other without coupling their interfaces. Common use cases include
tracking user context, request IDs, processing timestamps, and handler-specific state.

When using metadata, prefer well-known key names and document their usage to avoid conflicts between handlers.
Values should be serializable types to ensure compatibility across different storage providers.