MessageEnvelope

Represents a wrapper for an IMessage that will be published to the SimpleMessageBus Queue.

Definition

Assembly: CloudNimble.SimpleMessageBus.Core.dll

Namespace: CloudNimble.SimpleMessageBus.Core

Inheritance: System.Object

Syntax

CloudNimble.SimpleMessageBus.Core.MessageEnvelope

Summary

Represents a wrapper for an IMessage that will be published to the SimpleMessageBus Queue.

Remarks

The MessageEnvelope provides the transport container for messages within the SimpleMessageBus system. It wraps the actual message with metadata needed for processing, error handling, and tracking. The envelope handles message serialization/deserialization and provides processing context for handlers.

Key responsibilities include:

• Serializing messages for storage in queues
• Tracking processing attempts and timestamps
• Providing handler context through service scope and logging
• Managing message state during processing pipeline
• Facilitating message deserialization for handlers

Examples

// Creating an envelope (typically done automatically by publishers)
var message = new OrderCreatedMessage { OrderNumber = "ORD-001" };
var envelope = new MessageEnvelope(message);

// Processing an envelope in a handler
public async Task OnNextAsync(MessageEnvelope envelope)
{
    // Access metadata
    var attempts = envelope.AttemptsCount;
    var published = envelope.DatePublished;

    // Extract the message
    var orderMessage = envelope.GetMessage<OrderCreatedMessage>();

    // Use the logger for this specific message
    envelope.ProcessLog?.LogInformation("Processing order {OrderNumber}", orderMessage.OrderNumber);

    // Process the message...
}

Constructors

.ctor

Initializes a new instance of the MessageEnvelope class.

Syntax

public MessageEnvelope()

Remarks

This parameterless constructor should only be used for deserializing the MessageEnvelope from storage. For creating new envelopes to wrap messages, use the IMessage) constructor instead.

.ctor

Initializes a new instance of the MessageEnvelope class for a given IMessage.

Syntax

public MessageEnvelope(CloudNimble.SimpleMessageBus.Core.IMessage message)

Parameters

Name	Type	Description
message	CloudNimble.SimpleMessageBus.Core.IMessage	The IMessage instance that will be wrapped in a MessageEnvelope to be posted to the SimpleMessageBus.

Exceptions

Exception	Description
ArgumentNullException	Thrown when message is null.

Examples

var message = new OrderCreatedMessage
{
    OrderNumber = "ORD-001",
    CustomerId = customerId,
    TotalAmount = 99.99m
};

var envelope = new MessageEnvelope(message);
// envelope.Id is automatically generated
// envelope.DatePublished is set to now
// envelope.MessageType contains the full type name
// envelope.MessageContent contains the JSON serialized message

Remarks

This constructor automatically serializes the message to JSON, generates a unique envelope ID, sets the publish timestamp to the current UTC time, and extracts the message type information for later deserialization. The resulting envelope is ready to be published to any queue provider.

.ctor Inherited

Inherited from object

Syntax

public Object()

Properties

AttemptsCount

The number of times the system has previously attempted to process this message.

Syntax

public long AttemptsCount { get; set; }

Property Value

Type: long

DatePublished

The UTC date and time that this nessage was published to the queue.

Syntax

public System.DateTimeOffset DatePublished { get; set; }

Property Value

Type: System.DateTimeOffset

Id

A Guid uniquely identifying this message on the queue. Helps when looking at logs or correlating from telemetry.

Syntax

public System.Guid Id { get; set; }

Property Value

Type: System.Guid

Message

Gets the deserialized message instance.

Syntax

public CloudNimble.SimpleMessageBus.Core.IMessage Message { get; }

Property Value

Type: CloudNimble.SimpleMessageBus.Core.IMessage The IMessage instance deserialized from MessageEnvelope.MessageContent using the type specified in MessageEnvelope.MessageType. This property provides convenient access to the message without requiring explicit type specification in handlers.

Exceptions

Exception	Description
InvalidOperationException	Thrown when the message type cannot be resolved or deserialization fails.

Examples

public async Task OnNextAsync(MessageEnvelope envelope)
{
    // Type-safe access without specifying the type
    switch (envelope.Message)
    {
        case OrderCreatedMessage order:
            await ProcessOrderAsync(order);
            break;
        case PaymentProcessedMessage payment:
            await ProcessPaymentAsync(payment);
            break;
        default:
            throw new NotSupportedException($"Unknown message type: {envelope.MessageType}");
    }
}

Remarks

This property deserializes the message on each access. For performance-critical scenarios where the message is accessed multiple times, consider caching the result or using the typed GetMessage``1 method.

The deserialization uses the MessageEnvelope.MessageType to determine the target type and deserializes the MessageEnvelope.MessageContent JSON string into the appropriate message instance.

MessageContent

The serialized content of the IMessage.

Syntax

public string MessageContent { get; set; }

Property Value

Type: string

MessageState

A container to help track the state of a message as it flows between IMessageHandlerIMessageHandlers</see>. This value is ignored by the serializer and will not be persisted between failed message runs.

Syntax

public dynamic MessageState { get; private set; }

Property Value

Type: dynamic

MessageType

A string representing the type name of the message. Defaults to IMessage.GetType().AssemblyQualifiedName”.

Syntax

public string MessageType { get; set; }

Property Value

Type: string

ProcessLog

The processing log for this particular message across all MessageHandlers.

Syntax

public Microsoft.Extensions.Logging.ILogger ProcessLog { get; set; }

Property Value

Type: Microsoft.Extensions.Logging.ILogger

ServiceScope

The processing log for this particular message across all MessageHandlers.

Syntax

public Microsoft.Extensions.DependencyInjection.IServiceScope ServiceScope { get; set; }

Property Value

Type: Microsoft.Extensions.DependencyInjection.IServiceScope

Methods

Equals Inherited Virtual

Inherited from object

Syntax

public virtual bool Equals(object obj)

Parameters

Name	Type	Description
obj	object?	-

Returns

Type: bool

Equals Inherited

Inherited from object

Syntax

public static bool Equals(object objA, object objB)

Parameters

Name	Type	Description
objA	object?	-
objB	object?	-

Returns

Type: bool

GetHashCode Inherited Virtual

Inherited from object

Syntax

public virtual int GetHashCode()

Returns

Type: int

GetMessage

Retrieves the MessageEnvelope.MessageContent deserialized into an IMessage of the specified type.

Syntax

public T GetMessage<T>() where T : CloudNimble.SimpleMessageBus.Core.IMessage

Returns

Type: T A concrete T instance populated with the data from the MessageEnvelope.MessageContent.

Type Parameters

• T - The IMessage type represented by the MessageEnvelope.MessageContent.

Exceptions

Exception	Description
JsonException	Thrown when the MessageEnvelope.MessageContent cannot be deserialized to type T.
ArgumentNullException	Thrown when MessageEnvelope.MessageContent is null.

Examples

public async Task OnNextAsync(MessageEnvelope envelope)
{
    // Type-safe deserialization when you know the expected type
    var orderMessage = envelope.GetMessage<OrderCreatedMessage>();

    // Process the strongly-typed message
    await ProcessOrderAsync(orderMessage.OrderNumber, orderMessage.TotalAmount);
}

Remarks

This method provides type-safe deserialization when you know the exact message type at compile time. It directly deserializes the JSON content without using the MessageEnvelope.MessageType property for type resolution. This can be more performant than the MessageEnvelope.Message property for known types, but requires explicit type specification.

GetType Inherited

Inherited from object

Syntax

public System.Type GetType()

Returns

Type: System.Type

MemberwiseClone Inherited

Inherited from object

Syntax

protected internal object MemberwiseClone()

Returns

Type: object

ReferenceEquals Inherited

Inherited from object

Syntax

public static bool ReferenceEquals(object objA, object objB)

Parameters

Name	Type	Description
objA	object?	-
objB	object?	-

Returns

Type: bool

ToString Override

Syntax

public override string ToString()

Returns

Type: string

ToString Inherited Virtual

Inherited from object

Syntax

public virtual string ToString()

Returns

Type: string?