Interface IDeadLetterQueue

Namespace

DotCompute.Abstractions.Messaging

Assembly

DotCompute.Abstractions.dll

Stores messages that could not be processed successfully.

public interface IDeadLetterQueue : IDisposable

Inherited Members

IDisposable.Dispose()

Extension Methods

BufferExtensions.IsSafeToDispose(IDisposable)

BufferExtensions.SafeDispose(IDisposable)

Remarks

Dead letter queues capture messages that have failed processing due to:

• TTL expiration
• Maximum retry count exceeded
• Processing errors
• Validation failures
• Missing handlers

Messages in the DLQ can be inspected, reprocessed, or archived.

Properties

Count

Gets the current number of entries in the dead letter queue.

int Count { get; }

Property Value

int

MaxCapacity

Gets the maximum capacity of the dead letter queue.

int MaxCapacity { get; }

Property Value

int

Name

Gets the queue name.

string Name { get; }

Property Value

string

TotalDeadLettered

Gets the total number of messages ever dead-lettered.

long TotalDeadLettered { get; }

Property Value

long

Methods

Clear()

Clears all entries from the dead letter queue.

int Clear()

Returns

int

Number of entries removed.

EnqueueAsync<TMessage>(TMessage, DeadLetterReason, string?, Exception?, int, string?, IReadOnlyDictionary<string, string>?, CancellationToken)

Adds a message to the dead letter queue.

Task<DeadLetterEntry> EnqueueAsync<TMessage>(TMessage message, DeadLetterReason reason, string? errorMessage = null, Exception? exception = null, int attemptCount = 1, string? sourceQueue = null, IReadOnlyDictionary<string, string>? metadata = null, CancellationToken cancellationToken = default) where TMessage : IRingKernelMessage

Parameters

message TMessage

The failed message.

reason DeadLetterReason

Why the message was dead-lettered.

errorMessage string

Optional error description.

exception Exception

Optional exception that caused the failure.

attemptCount int

Number of processing attempts.

sourceQueue string

Name of the source queue.

metadata IReadOnlyDictionary<string, string>

Optional custom metadata.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DeadLetterEntry>

The created dead letter entry.

Type Parameters

TMessage

The message type.

GetEntries(Func<DeadLetterEntry, bool>?, int)

Gets all entries matching the specified filter.

IReadOnlyList<DeadLetterEntry> GetEntries(Func<DeadLetterEntry, bool>? predicate = null, int maxResults = 100)

Parameters

predicate Func<DeadLetterEntry, bool>

Optional filter predicate.

maxResults int

Maximum number of results.

Returns

IReadOnlyList<DeadLetterEntry>

Matching dead letter entries.

GetEntriesByReason(DeadLetterReason, int)

Gets entries by dead letter reason.

IReadOnlyList<DeadLetterEntry> GetEntriesByReason(DeadLetterReason reason, int maxResults = 100)

Parameters

reason DeadLetterReason

The reason to filter by.

maxResults int

Maximum number of results.

Returns

IReadOnlyList<DeadLetterEntry>

Matching dead letter entries.

GetEntriesByTimeRange(DateTimeOffset, DateTimeOffset, int)

Gets entries within a time range.

IReadOnlyList<DeadLetterEntry> GetEntriesByTimeRange(DateTimeOffset startTime, DateTimeOffset endTime, int maxResults = 100)

Parameters

startTime DateTimeOffset

Start time (inclusive).

endTime DateTimeOffset

End time (inclusive).

maxResults int

Maximum number of results.

Returns

IReadOnlyList<DeadLetterEntry>

Matching dead letter entries.

GetStatistics()

Gets statistics about the dead letter queue.

DeadLetterStatistics GetStatistics()

Returns

DeadLetterStatistics

Dead letter queue statistics.

Remove(Guid)

Removes an entry by its ID.

bool Remove(Guid entryId)

Parameters

entryId Guid

The entry ID to remove.

Returns

bool

True if the entry was found and removed.

RemoveWhere(Func<DeadLetterEntry, bool>)

Removes all entries matching the predicate.

int RemoveWhere(Func<DeadLetterEntry, bool> predicate)

Parameters

predicate Func<DeadLetterEntry, bool>

Filter for entries to remove.

Returns

int

Number of entries removed.

TryDequeue(out DeadLetterEntry?)

Attempts to dequeue an entry from the dead letter queue.

bool TryDequeue(out DeadLetterEntry? entry)

Parameters

entry DeadLetterEntry

The dequeued entry, or null if empty.

Returns

bool

True if an entry was dequeued.

TryPeek(out DeadLetterEntry?)

Peeks at the next entry without removing it.

bool TryPeek(out DeadLetterEntry? entry)

Parameters

entry DeadLetterEntry

The peeked entry, or null if empty.

Returns

bool

True if an entry exists.

Events

MessageDeadLettered

Occurs when a message is added to the dead letter queue.

event EventHandler<DeadLetterEventArgs>? MessageDeadLettered

Event Type

EventHandler<DeadLetterEventArgs>