From e6bf37d8eb173cc6fa133856aec10101d6ea5dea Mon Sep 17 00:00:00 2001 From: "Jeremy D. Miller" Date: Thu, 12 Feb 2026 10:58:42 -0600 Subject: [PATCH] Document PrefixIdentifiers usage for shared broker environments Add documentation for identifier prefixing to RabbitMQ, Amazon SQS, Azure Service Bus, GCP Pub/Sub, and NATS transport pages showing how to use PrefixIdentifiers() and PrefixIdentifiersWithMachineName() to isolate broker resources per developer or environment. Closes GH-548 Co-Authored-By: Claude Opus 4.6 --- .../azureservicebus/object-management.md | 29 +++++++++++++++++-- .../messaging/transports/gcp-pubsub/index.md | 29 +++++++++++++++++++ docs/guide/messaging/transports/nats.md | 9 +++++- .../transports/rabbitmq/object-management.md | 29 +++++++++++++++++++ docs/guide/messaging/transports/sqs/index.md | 29 +++++++++++++++++++ 5 files changed, 121 insertions(+), 4 deletions(-) diff --git a/docs/guide/messaging/transports/azureservicebus/object-management.md b/docs/guide/messaging/transports/azureservicebus/object-management.md index 0b82f96db..75cba5e25 100644 --- a/docs/guide/messaging/transports/azureservicebus/object-management.md +++ b/docs/guide/messaging/transports/azureservicebus/object-management.md @@ -61,11 +61,34 @@ using var host = await Host.CreateDefaultBuilder() snippet source | anchor -And lastly, because Azure Service Bus is a centralized broker model and you may have to share a single -environment between multiple developers or development environments, you can use prefixing with Azure Service Bus -so that every queue, topic, and subscription is quietly prefixed for uniqueness: +## Identifier Prefixing for Shared Brokers +Because Azure Service Bus is a centralized broker model, you may need to share a single namespace between multiple developers or development environments. You can use `PrefixIdentifiers()` to automatically prepend a prefix to every queue, topic, and subscription name created by Wolverine, isolating the cloud resources for each environment: +```csharp +using var host = await Host.CreateDefaultBuilder() + .UseWolverine(opts => + { + opts.UseAzureServiceBus("some connection string") + .AutoProvision() + + // Prefix all queue, topic, and subscription names with "dev-john." + .PrefixIdentifiers("dev-john"); + + // A queue named "orders" becomes "dev-john.orders" + opts.ListenToAzureServiceBusQueue("orders"); + }).StartAsync(); +``` + +You can also use `PrefixIdentifiersWithMachineName()` as a convenience to use the current machine name as the prefix: + +```csharp +opts.UseAzureServiceBus("some connection string") + .AutoProvision() + .PrefixIdentifiersWithMachineName(); +``` + +The default delimiter between the prefix and the original name is `.` for Azure Service Bus (e.g., `dev-john.orders`). ## Configuring Queues diff --git a/docs/guide/messaging/transports/gcp-pubsub/index.md b/docs/guide/messaging/transports/gcp-pubsub/index.md index a8ce438a6..dcf563b27 100644 --- a/docs/guide/messaging/transports/gcp-pubsub/index.md +++ b/docs/guide/messaging/transports/gcp-pubsub/index.md @@ -71,3 +71,32 @@ var host = await Host.CreateDefaultBuilder() ``` snippet source | anchor + +## Identifier Prefixing for Shared Environments + +When sharing a single GCP project between multiple developers or development environments, you can use `PrefixIdentifiers()` to automatically prepend a prefix to every topic and subscription name created by Wolverine. This helps isolate the cloud resources for each developer or environment: + +```csharp +using var host = await Host.CreateDefaultBuilder() + .UseWolverine(opts => + { + opts.UsePubsub("your-project-id") + .AutoProvision() + + // Prefix all topic and subscription names with "dev-john." + .PrefixIdentifiers("dev-john"); + + // A topic named "orders" becomes "dev-john.orders" + opts.ListenToPubsubTopic("orders"); + }).StartAsync(); +``` + +You can also use `PrefixIdentifiersWithMachineName()` as a convenience to use the current machine name as the prefix: + +```csharp +opts.UsePubsub("your-project-id") + .AutoProvision() + .PrefixIdentifiersWithMachineName(); +``` + +The default delimiter between the prefix and the original name is `.` for GCP Pub/Sub (e.g., `dev-john.orders`). diff --git a/docs/guide/messaging/transports/nats.md b/docs/guide/messaging/transports/nats.md index c6a3dd0f5..1d12acb1d 100644 --- a/docs/guide/messaging/transports/nats.md +++ b/docs/guide/messaging/transports/nats.md @@ -362,7 +362,7 @@ opts.Services.AddResourceSetupOnStartup(); ## Subject Prefix -Add a prefix to all NATS subjects: +When sharing a NATS server between multiple developers or development environments, you can add a prefix to all NATS subjects to isolate each environment's messaging. Use `WithSubjectPrefix()` or the generic `PrefixIdentifiers()` method: ```csharp opts.UseNats("nats://localhost:4222") @@ -371,6 +371,13 @@ opts.UseNats("nats://localhost:4222") // Subject "orders" becomes "myapp.orders" ``` +You can also use `PrefixIdentifiersWithMachineName()` as a convenience to use the current machine name as the prefix: + +```csharp +opts.UseNats("nats://localhost:4222") + .PrefixIdentifiersWithMachineName(); +``` + ## Complete Example ```csharp diff --git a/docs/guide/messaging/transports/rabbitmq/object-management.md b/docs/guide/messaging/transports/rabbitmq/object-management.md index 9516a48da..5df8fff23 100644 --- a/docs/guide/messaging/transports/rabbitmq/object-management.md +++ b/docs/guide/messaging/transports/rabbitmq/object-management.md @@ -238,3 +238,32 @@ public class MyModuleExtension : IWolverineExtension snippet source | anchor +## Identifier Prefixing for Shared Brokers + +Because Rabbit MQ is a centralized broker model, you may need to share a single broker between multiple developers or development environments. To isolate the broker objects (queues, exchanges, bindings) created by each environment, you can use the `PrefixIdentifiers()` method to automatically prepend a prefix to every queue and exchange name created by Wolverine: + +```csharp +using var host = await Host.CreateDefaultBuilder() + .UseWolverine(opts => + { + opts.UseRabbitMq() + .AutoProvision() + + // Prefix all queue and exchange names with "dev-john-" + .PrefixIdentifiers("dev-john"); + + // A queue named "orders" becomes "dev-john-orders" + opts.ListenToRabbitQueue("orders"); + }).StartAsync(); +``` + +You can also use `PrefixIdentifiersWithMachineName()` as a convenience to use the current machine name as the prefix, which is often a good default for local development: + +```csharp +opts.UseRabbitMq() + .AutoProvision() + .PrefixIdentifiersWithMachineName(); +``` + +The default delimiter between the prefix and the original name is `-` for Rabbit MQ (e.g., `dev-john-orders`). + diff --git a/docs/guide/messaging/transports/sqs/index.md b/docs/guide/messaging/transports/sqs/index.md index 5100138c2..e581958bb 100644 --- a/docs/guide/messaging/transports/sqs/index.md +++ b/docs/guide/messaging/transports/sqs/index.md @@ -152,3 +152,32 @@ using var host = await Host.CreateDefaultBuilder() Note that the `Uri` scheme within Wolverine for any endpoints from a "named" Amazon SQS broker is the name that you supply for the broker. So in the example above, you might see `Uri` values for `emea://colors` or `americas://red`. + +## Identifier Prefixing for Shared Brokers + +When sharing a single AWS account or SQS namespace between multiple developers or development environments, you can use `PrefixIdentifiers()` to automatically prepend a prefix to every queue name created by Wolverine. This helps isolate cloud resources for each developer or environment: + +```csharp +using var host = await Host.CreateDefaultBuilder() + .UseWolverine(opts => + { + opts.UseAmazonSqsTransport() + .AutoProvision() + + // Prefix all queue names with "dev-john-" + .PrefixIdentifiers("dev-john"); + + // A queue named "orders" becomes "dev-john-orders" + opts.ListenToSqsQueue("orders"); + }).StartAsync(); +``` + +You can also use `PrefixIdentifiersWithMachineName()` as a convenience to use the current machine name as the prefix: + +```csharp +opts.UseAmazonSqsTransport() + .AutoProvision() + .PrefixIdentifiersWithMachineName(); +``` + +The default delimiter between the prefix and the original name is `-` for Amazon SQS (e.g., `dev-john-orders`).