Use partials in ASB tool docs (#6995)

* Use partials in asbs tool docs

* Topology selection

* More partials

* Latest alpha

* Fix snippet

* Split up shortening

* Overlap

* Further split the topology

* Inline hierarchy

* Hack it for now

---------

Co-authored-by: Daniel Marbach <[email protected]>

Author: SzymonPobiega

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;
+}

Snippets/ASBS/ASBS_5/prerelease.txt

@@ -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.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/compatibility_shortening_asbs_[5,).partial.md

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