Use partials in ASB tool docs

Snippets/ASBS/ASBS.sln

@@ -1,4 +1,5 @@
-Microsoft Visual Studio Solution File, Format Version 12.00
+
+Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.4.33122.133
 MinimumVisualStudioVersion = 15.0.26730.12
@@ -14,6 +15,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ASBS_3.2", "ASBS_3.2\ASBS_3
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ASBS_4", "ASBS_4\ASBS_4.csproj", "{87EF58A5-99B5-4D4F-AB4A-5B10F7806499}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ASBS_5", "ASBS_5\ASBS_5.csproj", "{6CA4021C-42C5-45F3-9AFA-50A6DBA42BAE}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -44,6 +47,10 @@ Global
 		{87EF58A5-99B5-4D4F-AB4A-5B10F7806499}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{87EF58A5-99B5-4D4F-AB4A-5B10F7806499}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{87EF58A5-99B5-4D4F-AB4A-5B10F7806499}.Release|Any CPU.Build.0 = Release|Any CPU
+		{6CA4021C-42C5-45F3-9AFA-50A6DBA42BAE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6CA4021C-42C5-45F3-9AFA-50A6DBA42BAE}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6CA4021C-42C5-45F3-9AFA-50A6DBA42BAE}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6CA4021C-42C5-45F3-9AFA-50A6DBA42BAE}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

Snippets/ASBS/ASBS_5/ASBS_5.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" Version="1.12.0" />
+    <PackageReference Include="NServiceBus.Transport.AzureServiceBus" Version="5.0.0-alpha.4" />
+  </ItemGroup>
+</Project>

Snippets/ASBS/ASBS_5/AccessToNativeMessage.cs

@@ -0,0 +1,48 @@
+using Azure.Messaging.ServiceBus;
+using NServiceBus;
+using NServiceBus.Pipeline;
+using System;
+using System.Threading.Tasks;
+
+public class AccessToNativeMessage
+{
+    #region access-native-incoming-message
+
+    class DoNotAttemptMessageProcessingIfMessageIsNotLocked : Behavior<ITransportReceiveContext>
+    {
+        public override Task Invoke(ITransportReceiveContext context, Func<Task> next)
+        {
+            var lockedUntilUtc = context.Extensions.Get<ServiceBusReceivedMessage>().LockedUntil;
+
+            if (lockedUntilUtc <= DateTime.UtcNow)
+            {
+                return next();
+            }
+
+            throw new Exception($"Message lock lost for MessageId {context.Message.MessageId} and it cannot be processed.");
+        }
+    }
+
+    #endregion
+
+    class AccessOutgoingNativeMessage
+    {
+        async Task AccessNativeOutgoingMessageFromHandler(IMessageHandlerContext context)
+        {
+            #region access-native-outgoing-message
+            // send a command
+            var sendOptions = new SendOptions();
+            sendOptions.CustomizeNativeMessage(m => m.Subject = "custom-label");
+            await context.Send(new MyCommand(), sendOptions);
+
+            // publish an event
+            var publishOptions = new PublishOptions();
+            publishOptions.CustomizeNativeMessage(m => m.Subject = "custom-label");
+            await context.Publish(new MyEvent(), publishOptions);
+            #endregion
+        }
+
+        class MyCommand { }
+        class MyEvent { }
+    }
+}

Snippets/ASBS/ASBS_5/Usage.cs

@@ -0,0 +1,58 @@
+using System;
+using System.Security.Cryptography;
+using System.Text;
+
+using Azure.Identity;
+
+using NServiceBus;
+
+class Usage
+{
+    Usage(EndpointConfiguration endpointConfiguration)
+    {
+        #region azure-service-bus-for-dotnet-standard
+
+        var transport = new AzureServiceBusTransport("Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]", TopicTopology.Default);
+        endpointConfiguration.UseTransport(transport);
+
+        #endregion
+
+        #region token-credentials
+
+        var transportWithTokenCredentials = new AzureServiceBusTransport("[NAMESPACE].servicebus.windows.net", new DefaultAzureCredential(), TopicTopology.Default);
+        endpointConfiguration.UseTransport(transportWithTokenCredentials);
+
+        #endregion
+
+        #region custom-prefetch-multiplier
+
+        transport.PrefetchMultiplier = 3;
+
+        #endregion
+
+        #region custom-prefetch-count
+
+        transport.PrefetchCount = 100;
+
+        #endregion
+
+        #region custom-auto-lock-renewal
+
+        transport.MaxAutoLockRenewalDuration = TimeSpan.FromMinutes(10);
+
+        #endregion
+
+#pragma warning disable CS0618 // Type or member is obsolete
+        #region asb-sanitization-compatibility
+
+        var migrationTopology = TopicTopology.MigrateFromSingleDefaultTopic();
+        migrationTopology.OverrideSubscriptionNameFor("QueueName", "ShortenedSubscriptionName");
+
+        migrationTopology.EventToMigrate<MyEvent>("ShortenedRuleName");
+
+        #endregion
+#pragma warning restore CS0618 // Type or member is obsolete
+    }
+
+    class MyEvent;
+}

transports/azure-service-bus/compatibility.md

@@ -35,6 +35,4 @@ The Azure Service Bus transport doesn't support namespace aliases.
 
 If the legacy transport [sanitizes](/transports/azure-service-bus/configuration.md#entity-creation) entity names, the sanitization logic must be updated to be compatible with the new transport.
 
-For example, for the `ValidateAndHashIfNeeded` strategy, the sanitization functions must include the strategy logic to preserve the same entity names.
-
-snippet: asb-sanitization-compatibility
+partial: Shortening

transports/azure-service-bus/compatibility_shortening_asbs_[,5).partial.md

@@ -0,0 +1,3 @@
+For example, for the `ValidateAndHashIfNeeded` strategy, the sanitization functions must include the strategy logic to preserve the same entity names.
+
+snippet: asb-sanitization-compatibility

transports/azure-service-bus/compatibility_shortening_asbs_[5,).partial.md

@@ -0,0 +1,5 @@
+For example, for the `ValidateAndHashIfNeeded` strategy, the sanitization functions must include the strategy logic to preserve the same entity names.
+
+For queue names or event names that crossed the threshold of 50 characters it is necessary to precalculate the MD5 hash and store that as the subscription or rule name. Alternatively simply configure the subscription or rule name already used in production as a hardcoded value.
+
+snippet: asb-sanitization-compatibility

transports/azure-service-bus/configuration_entity-topology_asbs_[5,).partial.md

@@ -0,0 +1 @@
+### Topology

transports/azure-service-bus/operational-scripting.md

@@ -2,7 +2,7 @@
 title: Operational Scripting
 summary: Explains how to create queues and topics with the Azure Service Bus transport using scripting
 component: ASBS
-reviewed: 2022-11-15
+reviewed: 2025-02-17
 ---
 
 ## Operational Scripting
@@ -19,90 +19,7 @@ Once installed, the `asb-transport` command line tool will be available for use.
 
 `asb-transport <command> [options]`
 
-### Available commands
-
-- `endpoint create`
-- `endpoint subscribe`
-- `endpoint unsubscribe`
-- `queue create`
-- `queue delete`
-
-### asb-transport endpoint create
-
-Create a new endpoint using:
-
-```
-asb-transport endpoint create name
-                              [--size]
-                              [--partitioned]
-                              [--topic]
-                              [--topic-to-publish-to] [--topic-to-subscribe-on]
-                              [--subscription]
-```
-
-#### options
-
-`-c` | `--connection-string` : Overrides the environment variable 'AzureServiceBus_ConnectionString'
-
-`-n` | `--namespace` : Sets the fully qualified namespace to connect with cached credentials, e.g., credentials from Azure PowerShell or CLI. This setting cannot be used in conjunction with the connection string setting.
-
-`-s` | `--size` : Queue size in GB (defaults to 5)
-
-`-p` | `--partitioned`: Enable partitioning
-
-`-t` | `--topic`: Topic name (defaults to 'bundle-1')
-
-`-tp` | `--topic-to-publish-to`: The topic name to publish to.
-
-`-ts` | `--topic-to-subscribe-on`: The topic name to subscribe on.
-
-`-b` | `--subscription`: Subscription name (defaults to endpoint name)
-
-### asb-transport endpoint subscribe
-
-Create a new subscription for an endpoint using:
-
-```
-asb-transport endpoint subscribe name event-type
-                              [--topic]
-                              [--subscription]
-                              [--rule-name]
-```
-
-#### Options
-
-`-c` | `--connection-string` : Overrides the environment variable 'AzureServiceBus_ConnectionString'
-
-`-n` | `--namespace` : Sets the fully qualified namespace to connect with cached credentials, e.g., credentials from Azure PowerShell or CLI. This setting cannot be used in conjunction with the connection string setting.
-
-`-t` | `--topic`: Topic name to subscribe on (defaults to 'bundle-1')
-
-`-b` | `--subscription`: Subscription name (defaults to endpoint name)
-
-`-r` | `--rule-name`: Rule name (defaults to event type)
-
-### asb-transport endpoint unsubscribe
-
-Delete a subscription for an endpoint using:
-
-```
-asb-transport endpoint unsubscribe name event-type
-                              [--topic]
-                              [--subscription]
-                              [--rule-name]
-```
-
-#### Options
-
-`-c` | `--connection-string` : Overrides the environment variable 'AzureServiceBus_ConnectionString'
-
-`-n` | `--namespace` : Sets the fully qualified namespace to connect with cached credentials, e.g., credentials from Azure PowerShell or CLI. This setting cannot be used in conjunction with the connection string setting.
-
-`-t` | `--topic`: Topic name to unsubscribe from (defaults to 'bundle-1')
-
-`-b` | `--subscription`: Subscription name (defaults to endpoint name)
-
-`-r` | `--rule-name`: Rule name (defaults to event type)
+partial: endpoint-command
 
 ### asb-transport queue create
 
@@ -160,48 +77,4 @@ asb-transport [command] [subcommand] -c "<connection-string>"
 asb-transport [command] [subcommand] -n "somenamespace.servicebus.windows.net"
 ```
 
-#### Provisioning endpoints
-
-Create the topology for an endpoint named `MyEndpoint` using the default settings:
-
-```
-asb-transport endpoint create MyEndpoint -c "<connection-string>"
-```
-
-Create the topology for an endpoint named `MyEndpoint` and override the topic name to be `custom-topic` and the subscription name to be `my-endpoint`:
-
-```
-asb-transport endpoint create MyEndpoint -t custom-topic -s my-endpoint -c "<connection-string>"
-```
-
-Create the topology for an endpoint named `MyEndpoint` and override the publish topic name to be `custom-publish-topic` and the subscription topic name to be `custom-subscribe-topic`:
-
-```
-asb-transport endpoint create MyEndpoint -tp custom-publish-topic -ts custom-subscribe-topic -c "<connection-string>"
-```
-
-#### Subscribing to events
-
-Subscribe `MyOtherEndpoint` to the event `Contracts.Events.SomeEvent` using the default settings:
-
-```
-asb-transport endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -c "<connection-string>"
-```
-
-Subscribe `MyOtherEndpoint` to the event `Contracts.Events.SomeEvent` and override the topic name to be `custom-topic`:
-
-```
-asb-transport endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -t custom-topic -c "<connection-string>"
-```
-
-Subscribe `MyOtherEndpoint` to the event `Contracts.Events.SomeEvent` and override the subscription name to be `my-other-endpoint`
-
-```
-asb-transport endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -s my-other-endpoint -c "<connection-string>"
-```
-
-Subscribe `MyOtherEndpoint` to the event `Contracts.Events.SomeEvent` and override the subscription rule name to be `SomeEvent`:
-
-```
-asb-transport endpoint subscribe MyOtherEndpoint Contracts.Events.SomeEvent -r SomeEvent -c "<connection-string>"
-```
+partial: examples