Class InboxEntry
Represents a message entry in the inbox store for duplicate detection and processing tracking.
public sealed class InboxEntry
- Inheritance
-
InboxEntry
- Inherited Members
- Extension Methods
Remarks
Each inbox entry tracks the complete lifecycle of an incoming message from receipt through processing
completion for a specific handler. Entries are keyed by (MessageId, HandlerType), allowing the same
message to be processed independently by multiple handlers.
This enables at-most-once processing semantics per handler and provides audit trails for message handling.
Constructors
InboxEntry()
Initializes a new instance of the InboxEntry class.
public InboxEntry()
InboxEntry(string, string, string, byte[], IDictionary<string, object>?)
Initializes a new instance of the InboxEntry class with specified values.
public InboxEntry(string messageId, string handlerType, string messageType, byte[] payload, IDictionary<string, object>? metadata = null)
Parameters
messageIdstringThe unique identifier of the message.
handlerTypestringThe deduplication scope this entry is keyed under, together with
messageId.messageTypestringA type name for the message that the message type registry can resolve.
payloadbyte[]The serialized message payload.
metadataIDictionary<string, object>Additional message metadata.
Properties
CausationId
Gets or sets the causation identifier for tracing.
public string? CausationId { get; set; }
Property Value
- string
The id of the message that caused this one, for distributed tracing and message flow tracking.
CorrelationId
Gets or sets the correlation identifier for tracing.
public string? CorrelationId { get; set; }
Property Value
- string
Correlation ID for distributed tracing and message flow tracking.
HandlerType
Gets or sets the scope this message is deduplicated under, forming the composite key with MessageId.
public string HandlerType { get; set; }
Property Value
- string
An opaque scope name. A caller that deduplicates per handler passes that handler's fully qualified type name, so one message can be processed independently by several handlers. The framework's own inbox writers deduplicate per message type and pass the message type's fully qualified name, so an entry written by the framework carries one scope per message type rather than one per handler.
LastAttemptAt
Gets or sets the timestamp of the last processing attempt.
public DateTimeOffset? LastAttemptAt { get; set; }
Property Value
- DateTimeOffset?
UTC timestamp of the most recent processing attempt.
LastError
Gets or sets the error message if processing failed.
public string? LastError { get; set; }
Property Value
- string
Error description or exception message, null if no error occurred.
MessageId
Gets or sets the unique identifier of the message.
public string MessageId { get; set; }
Property Value
- string
The message identifier, typically a GUID or correlation ID.
MessageType
Gets or sets the name under which the message's .NET type is registered.
public string MessageType { get; set; }
Property Value
- string
A type name the message type registry can resolve. The framework's own inbox writers store the simple name (
Type.Name). An ambiguous simple name — one shared by two registered types — resolves to nothing rather than to either of them, so a collision fails loudly at resolution rather than deserializing the payload as the wrong type.
Metadata
Gets the additional message metadata including headers and context.
public IDictionary<string, object> Metadata { get; init; }
Property Value
- IDictionary<string, object>
A dictionary containing headers, correlation IDs, tenant information, and other context data.
NextAttemptAt
Gets or sets the absolute time before which a failed entry must not be re-claimed for retry.
public DateTimeOffset? NextAttemptAt { get; set; }
Property Value
- DateTimeOffset?
UTC timestamp computed as
now + backoff(attempt)when the entry was marked failed with a backoff schedule, or null when no backoff is recorded (the entry is eligible as soon as the store's re-admission predicate otherwise allows). Honored by stores implementing IBackoffSchedulableInboxStore.
Payload
Gets or sets the serialized message payload.
public byte[] Payload { get; set; }
Property Value
- byte[]
The message data as bytes, typically JSON or binary format.
ProcessedAt
Gets or sets the timestamp when the message processing was completed.
public DateTimeOffset? ProcessedAt { get; set; }
Property Value
- DateTimeOffset?
UTC timestamp of successful processing completion, null if not yet processed.
ReceivedAt
Gets or sets the timestamp when the message was received.
public DateTimeOffset ReceivedAt { get; set; }
Property Value
- DateTimeOffset
UTC timestamp of message receipt.
RetryCount
Gets or sets the number of processing attempts made.
public int RetryCount { get; set; }
Property Value
- int
The retry count, starting from 0 for the first attempt.
Source
Gets or sets the message source or origin.
public string? Source { get; set; }
Property Value
- string
Source system, queue, or endpoint that produced the message.
Status
Gets or sets the current processing status of the message.
public InboxStatus Status { get; set; }
Property Value
- InboxStatus
The inbox status indicating the processing state.
TenantId
Gets or sets the tenant identifier for multi-tenant scenarios.
public string? TenantId { get; set; }
Property Value
- string
Tenant ID for tenant isolation and routing.
Methods
IsEligibleForRetry(int, int)
Determines if the entry is eligible for retry processing.
public bool IsEligibleForRetry(int maxRetries = 3, int retryDelayMinutes = 5)
Parameters
maxRetriesintMaximum number of retry attempts allowed.
retryDelayMinutesintMinimum delay between retry attempts in minutes.
Returns
- bool
True if the entry can be retried, false otherwise.
MarkFailed(string)
Marks the entry as failed with the specified error.
public void MarkFailed(string error)
Parameters
errorstringThe error description.
Remarks
Processed is absorbing: this is a no-op on an entry that has already
been processed. The transition is refused rather than applied because it is not recoverable in
the layer above. A handler that outran its own lease can finish after a second processor has
reclaimed the entry and finalized it; the late caller's finalize then reports "already processed"
and its own error handling calls this method. Demoting the entry to
Failed would make it re-admittable, so the next redelivery would run the
handler a further time and IsProcessedAsync would answer false about a
message that was in fact processed.
Consumers that need to distinguish "recorded the failure" from "the entry was already terminal" should read Status after the call.
MarkProcessed()
Marks the entry as successfully processed.
public void MarkProcessed()
Remarks
Idempotent: re-marking an already-processed entry leaves ProcessedAt at the instant the message was actually handled rather than restamping it.
MarkProcessing()
Marks the entry as currently being processed.
public void MarkProcessing()
Remarks
No-op once the entry is Processed. See MarkFailed(string) for why that state absorbs every later transition.
ToString()
Returns a string that represents the current object.
public override string ToString()
Returns
- string
A string that represents the current object.