Add legacy transport bridge docs (#6117)

Snippets/Bridge/TransportBridge_1/API.cs

@@ -0,0 +1,23 @@
+using NServiceBus;
+
+public class API
+{
+    public void Configuration()
+    {
+        var connectionString = string.Empty;
+        var bridgeConfiguration = new BridgeConfiguration();
+
+        #region bridgeconfiguration
+
+        var msmq = new BridgeTransport(new MsmqTransport());
+        var asb = new BridgeTransport(new AzureServiceBusTransport(connectionString));
+
+        msmq.HasEndpoint("Sales");
+        asb.HasEndpoint("Billing");
+
+        bridgeConfiguration.AddTransport(msmq);
+        bridgeConfiguration.AddTransport(asb);
+
+        #endregion
+    }
+}

Snippets/Bridge/TransportBridge_1/Bridge_2.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <LangVersion>10.0</LangVersion>
+    <TargetFramework>net48</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="NServiceBus.Transport.AzureServiceBus" Version="3.*" />
+    <PackageReference Include="NServiceBus.Transport.Bridge" Version="1.*" />
+    <PackageReference Include="NServiceBus.Transport.Msmq" Version="2.*" />
+  </ItemGroup>
+</Project>

Snippets/Bridge/TransportBridge_1/Configuration.cs

@@ -0,0 +1,205 @@
+namespace Bridge_1
+{
+    using Messages;
+    using Microsoft.Extensions.Configuration;
+    using Microsoft.Extensions.Hosting;
+    using NServiceBus;
+    using System.Threading.Tasks;
+
+    public class Configuration
+    {
+        public async Task GenericHost()
+        {
+            #region generic-host
+
+            await Host.CreateDefaultBuilder()
+                .UseNServiceBusBridge(bridgeConfiguration =>
+                {
+                    // Configure the bridge
+                })
+                .Build()
+                .RunAsync();
+
+            #endregion
+        }
+
+        public async Task GenericHostBuilderContext()
+        {
+            #region generic-host-builder-context
+
+            await Host.CreateDefaultBuilder()
+                .UseNServiceBusBridge((hostBuilderContext, bridgeConfiguration) =>
+                {
+                    var connectionString = hostBuilderContext.Configuration.GetValue<string>("MyBridge:AzureServiceBusConnectionString");
+                    var concurrency = hostBuilderContext.Configuration.GetValue<int>("MyBridge:Concurrency");
+
+                    var transport = new BridgeTransport(new AzureServiceBusTransport(connectionString))
+                    {
+                        Concurrency = concurrency
+                    };
+
+                    bridgeConfiguration.AddTransport(transport);
+
+                    // more configuration...
+                })
+                .Build()
+                .RunAsync().ConfigureAwait(false);
+
+            #endregion
+        }
+
+        public async Task EndpointRegistration()
+        {
+            #region endpoint-registration
+
+            await Host.CreateDefaultBuilder()
+                .UseNServiceBusBridge((ctx, bridgeConfiguration) =>
+                {
+                    var msmq = new BridgeTransport(new MsmqTransport());
+                    msmq.HasEndpoint("Sales");
+                    msmq.HasEndpoint("Shipping");
+
+                    var asb = new BridgeTransport(new AzureServiceBusTransport(connectionString));
+                    asb.HasEndpoint("Finance.Invoicing");
+                    asb.HasEndpoint("Finance.Billing");
+
+                    bridgeConfiguration.AddTransport(msmq);
+                    bridgeConfiguration.AddTransport(asb);
+                })
+                .Build()
+                .RunAsync().ConfigureAwait(false);
+
+            #endregion
+        }
+
+        public void RegisterPublishers()
+        {
+            #region register-publisher
+
+            var msmq = new BridgeTransport(new MsmqTransport());
+            msmq.HasEndpoint("Sales");
+            msmq.HasEndpoint("Finance.Billing");
+
+            var asb = new BridgeTransport(new AzureServiceBusTransport(connectionString));
+            asb.HasEndpoint("Shipping");
+
+            var invoicing = new BridgeEndpoint("Finance.Invoicing");
+            invoicing.RegisterPublisher(typeof(OrderBilled), "Finance.Billing");
+            invoicing.RegisterPublisher<OrderShipped>("Shipping");
+            invoicing.RegisterPublisher("Messages.OrderPlaced", "Sales");
+
+            asb.HasEndpoint(invoicing);
+
+            #endregion
+
+            #region register-publisher-legacy
+
+            // Type.AssemblyQualifiedName Property value
+            invoicing.RegisterPublisher("CreditApproved, CreditScoring.Messages, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null", "Sales");
+            // Type.AssemblyQualifiedName Property but trimmed without Culture and PublicKeyToken as these are ignored by the message driven pub/sub feature
+            invoicing.RegisterPublisher("CreditApproved, CreditScoring.Messages, Version=1.0.0.0", "Sales");
+
+
+            #endregion
+        }
+
+        public void AutoCreateQueues()
+        {
+            #region auto-create-queues
+
+            var msmq = new BridgeTransport(new MsmqTransport())
+            {
+                AutoCreateQueues = true
+            };
+
+            var azureServiceBus = new BridgeTransport(new AzureServiceBusTransport(connectionString))
+            {
+                AutoCreateQueues = true
+            };
+
+            #endregion
+        }
+
+        public void CustomConcurrency()
+        {
+            #region custom-concurrency
+
+            var msmq = new BridgeTransport(new MsmqTransport())
+            {
+                Concurrency = 10
+            };
+
+            var azureServiceBus = new BridgeTransport(new AzureServiceBusTransport(connectionString))
+            {
+                Concurrency = 5
+            };
+
+            #endregion
+        }
+
+        public void CustomErrorQueue()
+        {
+            #region custom-error-queue
+
+            var msmq = new BridgeTransport(new MsmqTransport())
+            {
+                ErrorQueue = "my-msmq-bridge-error-queue"
+            };
+
+            var azureServiceBus = new BridgeTransport(new AzureServiceBusTransport(connectionString))
+            {
+                ErrorQueue = "my-asb-bridge-error-queue"
+            };
+
+            #endregion
+        }
+
+        public void CustomTransportName()
+        {
+            #region custom-transport-name
+
+            var azureServiceBus1 = new BridgeTransport(new AzureServiceBusTransport(connectionStringNamepace1))
+            {
+                Name = "asb-namespace-1"
+            };
+
+            var azureServiceBus2 = new BridgeTransport(new AzureServiceBusTransport(connectionStringNamepace2))
+            {
+                Name = "asb-namespace-2"
+            };
+
+            #endregion
+        }
+
+        public void PlatformBridging()
+        {
+            #region platform-bridging
+
+            var transportWhereServiceControlIsInstalled = new BridgeTransport(new MsmqTransport());
+
+            transportWhereServiceControlIsInstalled.HasEndpoint("Particular.ServiceControl");
+            transportWhereServiceControlIsInstalled.HasEndpoint("Particular.Monitoring");
+            transportWhereServiceControlIsInstalled.HasEndpoint("error");
+            transportWhereServiceControlIsInstalled.HasEndpoint("audit");
+
+            #endregion
+        }
+
+        public void QueueName()
+        {
+            #region custom-address
+
+            var transport = new BridgeTransport(new MsmqTransport());
+            transport.HasEndpoint("Finance", "finance@machinename");
+
+            var endpoint = new BridgeEndpoint("Sales", "sales@another-machine");
+            transport.HasEndpoint(endpoint);
+
+            #endregion
+        }
+
+        string connectionString = string.Empty;
+        string connectionStringNamepace1 = string.Empty;
+        string connectionStringNamepace2 = string.Empty;
+    }
+}

Snippets/Bridge/TransportBridge_1/ConfigureTransactionMode.cs

@@ -0,0 +1,15 @@
+using NServiceBus;
+
+class ConfigureTransactionMode
+{
+    void SetExplicitReceiveOnly()
+    {
+        #region bridge-configuration-explicit-receive-only-mode
+
+        var bridgeConfiguration = new BridgeConfiguration();
+
+        bridgeConfiguration.RunInReceiveOnlyTransactionMode();
+
+        #endregion
+    }
+}

Snippets/Bridge/TransportBridge_1/DummyMessages.cs

@@ -0,0 +1,13 @@
+namespace Messages;
+
+public class OrderPlaced
+{
+}
+
+public class OrderBilled
+{
+}
+
+public class OrderShipped
+{
+}

components/components.yaml

@@ -90,6 +90,7 @@
   ProjectUrl: https://github.com/Particular/NServiceBus.MessagingBridge
   NugetOrder:
     - NServiceBus.MessagingBridge
+    - NServiceBus.Transport.Bridge
 
 - Key: Callbacks
   Name: Callbacks

components/nugetAlias.txt

@@ -72,6 +72,7 @@ Testing: NServiceBus.Testing
 Templates: ParticularTemplates
 Unity: NServiceBus.Unity
 Wcf: NServiceBus.Wcf
+TransportBridge: NServiceBus.Transport.Bridge
 Bridge: NServiceBus.MessagingBridge
 Router: NServiceBus.Router
 RouterConnector: NServiceBus.Router.Connector

nservicebus/bridge/configuration.md

@@ -2,12 +2,12 @@
 title: Bridge configuration options
 summary: Configuration options for the messaging bridge.
 component: Bridge
-reviewed: 2022-04-01
+reviewed: 2023-07-04
 ---
 
 ## Hosting
 
-`NServiceBus.MessagingBridge` is hosted using the [.NET Generic Host](https://docs.microsoft.com/en-us/dotnet/core/extensions/generic-host) which takes care of life cycle management, configuration, logging, and other concerns.
+NServiceBus Messaging Bridge is hosted using the [.NET Generic Host](https://docs.microsoft.com/en-us/dotnet/core/extensions/generic-host) which takes care of life cycle management, configuration, logging, and other concerns.
 
 snippet: generic-host
 
@@ -19,8 +19,6 @@ snippet: generic-host-builder-context
 
 If a logical endpoint communicates with other endpoints that use a different transport, it must be registered with the bridge. Endpoints are registered with the bridge on the transport they run on. The bridge then creates a proxy endpoint on each transport that needs to be bridged.
 
-WARNING: Mappings are case-sensitive
-
 snippet: endpoint-registration
 
 ## Registering publishers
@@ -33,6 +31,8 @@ The result is duplicate subscriptions for any endpoint that subscribes to an eve
 
 snippet: register-publisher
 
+WARN: The endpoint name used when creating a `BridgeEndpoint` is case-sensitive, even if one or both transports don't require it. This is to accommodate all transports, some of which require a case-sensitive endpoint name. More details can be found on [this issue](https://github.com/Particular/NServiceBus.MessagingBridge/issues/175).
+
 Legacy transports versions that use [message-driven pub/sub](/nservicebus/messaging/publish-subscribe/#mechanics-message-driven-persistence-based) require the fully qualified assembly type name value to be passed. Note that passing the culture and public key is not needed as only the type name, assembly name, and assembly version are used in filtering subscribers by the message-driven pub/sub-feature.
 
 snippet: register-publisher-legacy
@@ -67,8 +67,6 @@ The bridge provides the ability to change the address of the queue of incoming m
 
 NOTE: When forwarding messages to MSMQ endpoints that run on different servers than the bridge, the addresses of the queues that messages should be forwarded to _must_ be provided.
 
-WARNING: Mappings are case-sensitive
-
 snippet: custom-address
 
 ## Recoverability
@@ -106,6 +104,8 @@ The bridge can be configured to allow a single ServiceControl installation to ma
 
 snippet: platform-bridging
 
+WARN: The endpoint name used when creating a `BridgeEndpoint` is case-sensitive, even if one or both transports don't require it. This is to accommodate all transports, some of which require a case-sensitive endpoint name. More details can be found on [this issue](https://github.com/Particular/NServiceBus.MessagingBridge/issues/175).
+
 ### Audit queue
 
 Special considerations are required for the audit queue due to potentially high message volume. For example, a [dedicated ServiceControl audit instance](/servicecontrol/audit-instances/) could be created for each bridged transport, to make audit ingestion more efficient.

nservicebus/bridge/index.md

@@ -1,15 +1,15 @@
 ---
 title: Bridge
 summary: Connect endpoints in a system that use different transports with the messaging bridge
-reviewed: 2022-04-01
+reviewed: 2023-07-04
 component: Bridge
 related:
  - samples/bridge/simple
  - samples/bridge/azure-service-bus-msmq-bridge
  - samples/bridge/sql-multi-instance
 ---
 
-`NServiceBus.MessagingBridge` allows NServiceBus endpoints to connect to other endpoints that are not using the same transport using the [Messaging Bridge Pattern](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessagingBridge.html).
+The NServiceBus Messaging Bridge allows NServiceBus endpoints to connect to other endpoints that are not using the same transport using the [Messaging Bridge Pattern](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessagingBridge.html).
 
 The bridge is transparent to sending and receiving endpoints. That is, endpoints are not aware of the bridge or that it is transferring messages to a different transport. Endpoints send and receive messages to and from logical endpoints as they normally would if there were no bridge involved.
 
@@ -25,7 +25,7 @@ More details on these scenarios are provided in the [messaging bridge scenarios]
 
 ## Bridge configuration
 
-`NServiceBus.MessagingBridge` is packaged as a host-agnostic library. It can be hosted in a console application, a Windows service, a Docker container, or any service that supports the Microsoft Generic Host, similar to how [endpoints are hosted](/nservicebus/hosting/selecting.md).
+partial: configuration
 
 The following snippet shows a simple MSMQ-to-AzureServiceBus configuration.
 
@@ -35,7 +35,7 @@ The life cycle of the bridge is managed by the .NET Generic Host.
 
 ## Errors
 
-When the messaging bridge encounters an error while transferring a message between transports it will move the message to the `bridge.error` queue, which is specific to the messaging bridge. An additional header `NServiceBus.MessagingBridge.FailedQ` is added to allow moving a message back to its originating queue, so the messaging bridge can pick them up again. 
+partial: errors
 
 NOTE: The messages in the `bridge.error` queue are not compatible with ServiceControl at this moment.
 

nservicebus/bridge/index_configuration_bridge_[2,).partial.md

@@ -0,0 +1 @@
+`NServiceBus.MessagingBridge` is packaged as a host-agnostic library. It can be hosted in a console application, a Windows service, a Docker container, or any service that supports the Microsoft Generic Host, similar to how [endpoints are hosted](/nservicebus/hosting/selecting.md).

nservicebus/bridge/index_configuration_transportbridge_[1,2).partial.md

@@ -0,0 +1 @@
+`NServiceBus.Transport.Bridge` is packaged as a host-agnostic library. It can be hosted in a console application, a Windows service, a Docker container, or any service that supports the Microsoft Generic Host, similar to how [endpoints are hosted](/nservicebus/hosting/selecting.md).

nservicebus/bridge/index_errors_bridge_[2,).partial.md

@@ -0,0 +1,2 @@
+When the messaging bridge encounters an error while transferring a message between transports it will move the message to the `bridge.error` queue, which is specific to the messaging bridge. An additional header `NServiceBus.MessagingBridge.FailedQ` is added to allow moving a message back to its originating queue, so the messaging bridge can pick them up again.
+

nservicebus/bridge/index_errors_transportbridge_[1,2).partial.md

@@ -0,0 +1 @@
+When the messaging bridge encounters an error while transferring a message between transports it will move the message to the `bridge.error` queue, which is specific to the messaging bridge. An additional header `NServiceBus.Transport.Bridge.FailedQ` is added to allow moving a message back to its originating queue, so the messaging bridge can pick them up again.