Skip to content

Commit 456389e

Browse files
committed
Explains queue names vs. queue IDs
Clarifies the distinction between queue names and queue IDs, emphasizing that `Name` is the stable identifier used for data routing and sharing across processes, while `QueueId` is a runtime identifier used for logging. Adds a tip about sharing queues across processes by ensuring they use the same `Name`. Also adds a note that `InMemoryQueue` is an in-process only implementation.
1 parent 28da909 commit 456389e

File tree

1 file changed

+29
-0
lines changed

1 file changed

+29
-0
lines changed

docs/guide/queues.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -931,6 +931,35 @@ await queue.EnqueueAsync(reminder, new QueueEntryOptions
931931
});
932932
```
933933

934+
## Queue Name vs Queue ID
935+
936+
Every queue has two distinct identifiers that serve different purposes:
937+
938+
| Property | Purpose | Stable across restarts? | Shared across processes? |
939+
|----------|---------|------------------------|--------------------------|
940+
| `Name` | Identifies the queue in the **backing store** (Redis key prefix, SQS queue name, etc.) | ✅ Yes | ✅ Yes — two processes with the same `Name` share the same data |
941+
| `QueueId` | Runtime **instance identifier** used only for logging and diagnostics | ❌ No (random suffix by default) | N/A — never used for data routing |
942+
943+
**`Name`** is what controls which data is read and written. All distributed queue implementations (Redis, SQS, Azure Service Bus, Azure Storage) route messages based on `Name`, not `QueueId`. Two processes or application restarts using the same `Name` will naturally share queue data and continue from where the other left off.
944+
945+
**`QueueId`** exists purely so that multiple queue instances within the same process (e.g., priority queues or keyed queues) produce distinguishable log output. It has no effect on the backing store.
946+
947+
::: tip Sharing queues across processes
948+
If you want multiple processes (or application restarts) to share a queue, just ensure they all configure the same `Name` value. The default is `typeof(T).Name` (the message type name), so it is consistent by default as long as you use the same message type.
949+
950+
```csharp
951+
// Both processes use the same Name → they share the same queue in Redis
952+
var queue = new RedisQueue<WorkItem>(o => {
953+
o.ConnectionMultiplexer = redis;
954+
o.Name = "work-items"; // This is the stable backing-store identifier
955+
});
956+
```
957+
:::
958+
959+
::: info InMemoryQueue
960+
`InMemoryQueue` is an in-process implementation only. It cannot share data across processes regardless of `Name` or `QueueId`. Use a distributed implementation (Redis, SQS, Azure) for cross-process sharing.
961+
:::
962+
934963
## Next Steps
935964

936965
- [Jobs](./jobs) - Queue processor jobs for automatic background processing with `QueueJobBase<T>`

0 commit comments

Comments
 (0)