GH-3366: ship a real UseAzureServiceBusEmulator() API

[jeremydmiller]

Problem

Several Azure Service Bus doc pages told readers to call UseAzureServiceBusTesting(), but that extension method was never in the shipping WolverineFx.AzureServiceBus package -- it lived only in Wolverine.AzureServiceBus.Tests and depended on the test-infrastructure Servers type. Readers following the docs got a compile error.

Per the maintainer decision on the issue, this takes Option 1: promote a real API into the shipping package rather than walking the docs back.

New public API surface (Wolverine.AzureServiceBus)

AzureServiceBusEmulatorExtensions (new):

public const string DefaultEmulatorConnectionString =
    "Endpoint=sb://localhost:5672;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;";

public const string DefaultEmulatorManagementConnectionString =
    "Endpoint=sb://localhost:5300;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;";

public static AzureServiceBusConfiguration UseAzureServiceBusEmulator(
    this WolverineOptions endpoints,
    Action<ServiceBusClientOptions>? configure = null);

public static AzureServiceBusConfiguration UseAzureServiceBusEmulator(
    this WolverineOptions endpoints,
    string connectionString,
    string managementConnectionString,
    Action<ServiceBusClientOptions>? configure = null);

public static Task DeleteAllAzureServiceBusObjectsAsync(
    string managementConnectionString = DefaultEmulatorManagementConnectionString,
    CancellationToken token = default);

AzureServiceBusConfiguration (new method):

public AzureServiceBusConfiguration DeleteAllExistingObjectsOnStartup();

AzureServiceBusTransport (new property, honored in ConnectAsync):

public bool DeleteAllExistingObjectsOnStartup { get; set; }

Both UseAzureServiceBusEmulator() overloads set ManagementConnectionString and return the same AzureServiceBusConfiguration as UseAzureServiceBus(), so AutoProvision(), AutoPurgeOnStartup(), conventional routing, etc. all chain off of them.

Opt-in cleanup decision

The test-only helper unconditionally deleted every queue and topic in the namespace. That is far too dangerous to make default behavior in a shipped API -- someone who points UseAzureServiceBusEmulator() at a real namespace by mistake (or with a copy/pasted connection string) must not lose their entities. So the wipe is opt in only, via DeleteAllExistingObjectsOnStartup(), and it is documented as destructive and irreversible with a ::: danger callout. DeleteAllAzureServiceBusObjectsAsync(...) is also available for out-of-band cleanup (e.g. once per test run rather than once per host start), which is exactly how Wolverine's own test suite now uses it.

Tests and docs

• Wolverine.AzureServiceBus.Tests/AzureServiceBusTesting.cs now delegates to the shipping API -- no duplicate implementation. The whole ASB suite still goes through it, so the new API is exercised end-to-end on CI.
• New emulator_configuration.cs unit tests cover both overloads and assert the destructive cleanup is off by default.
• emulator.md rewritten around the now-real API (compiled <!-- snippet: ... --> blocks from DocumentationSamples.cs), plus fixes to index.md, session-identifiers.md, and conventional-routing.md. The doc-facing samples that previously pulled from tests calling UseAzureServiceBusTesting() were moved into DocumentationSamples.cs and now show UseAzureServiceBusEmulator(). No UseAzureServiceBusTesting() references remain anywhere in docs/.

Verification

• dotnet build wolverine.slnx -c Release -- clean, 0 warnings / 0 errors.
• New emulator_configuration tests pass locally (4/4).
• The broker-backed ASB tests were not run locally -- they need the Azure Service Bus emulator container -- so I am relying on CI for those.

Fixes #3366

🤖 Generated with Claude Code