Add routing diagnostics to diagnostics doc page Closes GH-324

jeremydmiller · jeremydmiller · commit 68aa4a135e65 · 2023-11-21T07:31:59.000-06:00
diff --git a/docs/guide/diagnostics.md b/docs/guide/diagnostics.md
@@ -150,3 +150,36 @@ public static void assert_configuration_is_valid(IHost host)
 Note that this method will attempt to generate and compile the source code for each message type and use [Lamar's own
 diagnostics](https://jasperfx.github.io/lamar/guide/ioc/diagnostics/) as well.
 
+## Troubleshooting Message Routing
+
+Among other information, you can find a preview of how Wolverine will route known message types through the command line
+with:
+
+```bash
+dotnet run -- describe
+```
+
+Part of this output is a table of the known message types and the routed destination of any subscriptions. You can enhance
+this diagnostic by helping Wolverine to [discover message types](/guide/messages#message-discovery) in your system. 
+
+And lastly, there's a programmatic way to "preview" the Wolverine message routing at runtime that might 
+be helpful:
+
+<!-- snippet: sample_using_preview_subscriptions -->
+<a id='snippet-sample_using_preview_subscriptions'></a>
+```cs
+public static void using_preview_subscriptions(IMessageBus bus)
+{
+    // Preview where Wolverine is wanting to send a message
+    var outgoing = bus.PreviewSubscriptions(new BlueMessage());
+    foreach (var envelope in outgoing)
+    {
+        // The URI value here will identify the endpoint where the message is
+        // going to be sent (Rabbit MQ exchange, Azure Service Bus topic, Kafka topic, local queue, etc.)
+        Debug.WriteLine(envelope.Destination);
+    }
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Testing/CoreTests/Runtime/Routing/routing_precedence.cs#L76-L90' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_preview_subscriptions' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
diff --git a/docs/guide/durability/efcore.md b/docs/guide/durability/efcore.md
@@ -31,7 +31,7 @@ builder.Host.UseWolverine(opts =>
     opts.Policies.UseDurableLocalQueues();
 });
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L35-L52' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_registering_efcore_middleware' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L36-L53' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_registering_efcore_middleware' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ::: tip
@@ -124,7 +124,7 @@ this syntax for the service registration:
 builder.Services.AddDbContextWithWolverineIntegration<ItemsDbContext>(
     x => x.UseSqlServer(connectionString), "wolverine");
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L18-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_optimized_efcore_registration' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L19-L26' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_optimized_efcore_registration' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 That registration will:
@@ -219,7 +219,7 @@ public async Task Post(
     await outbox.SaveChangesAndFlushMessagesAsync();
 }
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/CreateItemController.cs#L8-L38' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_dbcontext_outbox_1' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/CreateItemController.cs#L10-L40' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_dbcontext_outbox_1' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Or use the `IDbContextOutbox` as shown below, but in this case you will need to explicitly call `Enroll()` on
@@ -261,7 +261,7 @@ public async Task Post3(
     await outbox.SaveChangesAndFlushMessagesAsync();
 }
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/CreateItemController.cs#L41-L76' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_dbcontext_outbox_2' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/CreateItemController.cs#L43-L78' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_dbcontext_outbox_2' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ## As Saga Storage
diff --git a/docs/guide/durability/managing.md b/docs/guide/durability/managing.md
@@ -75,7 +75,7 @@ To have any missing database schema objects built as needed on application start
 // This is rebuilding the persistent storage database schema on startup
 builder.Host.UseResourceSetupOnStartup();
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L54-L59' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_resource_setup_on_startup' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L55-L60' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_resource_setup_on_startup' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ## Command Line Management
@@ -89,7 +89,7 @@ shown in this last line of a .NET 6/7 `Program` code file:
 // Opt into using Oakton for command parsing
 await app.RunOaktonCommands(args);
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L80-L85' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_oakton_for_command_line_parsing' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L83-L88' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_oakton_for_command_line_parsing' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 And you're using the message persistence from either the `WolverineFx.SqlServer` or `WolverineFx.Postgresql`
diff --git a/docs/guide/durability/sqlserver.md b/docs/guide/durability/sqlserver.md
@@ -30,7 +30,7 @@ builder.Host.UseWolverine(opts =>
     opts.Policies.UseDurableLocalQueues();
 });
 ```
-<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L35-L52' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_registering_efcore_middleware' title='Start of snippet'>anchor</a></sup>
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Samples/EFCoreSample/ItemService/Program.cs#L36-L53' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_registering_efcore_middleware' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 ## Sql Server Messaging Transport
diff --git a/docs/tutorials/best-practices.md b/docs/tutorials/best-practices.md
@@ -224,4 +224,4 @@ has quite a bit of features specifically to support a "Vertical Slice Architectu
 to utilize Wolverine to create a maintainable codebase with much less complexity than the state of the art Clean/Onion
 layered approach.
 
-See [Low Ceremony Vertical Slice Architecture with Wolverine](https://jeremydmiller.com/2023/07/10/low-ceremony-vertical-slice-architecture-with-wolverine/)
+See [Low Ceremony Vertical Slice Architecture with Wolverine](https://jeremydmiller.com/2023/07/10/low-ceremony-vertical-slice-architecture-with-wolverine/)
diff --git a/src/Testing/CoreTests/Runtime/Routing/routing_precedence.cs b/src/Testing/CoreTests/Runtime/Routing/routing_precedence.cs
@@ -1,6 +1,7 @@
 using System;
 using System.CodeDom.Compiler;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Linq;
 using System.Threading.Tasks;
 using Microsoft.Extensions.DependencyInjection;
@@ -71,6 +72,22 @@ public async Task explicit_routing_to_local_wins()
         bus.PreviewSubscriptions(new BlueMessage())
             .Single().Destination.ShouldBe(new Uri("local://purple"));
     }
+
+    #region sample_using_preview_subscriptions
+
+    public static void using_preview_subscriptions(IMessageBus bus)
+    {
+        // Preview where Wolverine is wanting to send a message
+        var outgoing = bus.PreviewSubscriptions(new BlueMessage());
+        foreach (var envelope in outgoing)
+        {
+            // The URI value here will identify the endpoint where the message is
+            // going to be sent (Rabbit MQ exchange, Azure Service Bus topic, Kafka topic, local queue, etc.)
+            Debug.WriteLine(envelope.Destination);
+        }
+    }
+
+    #endregion
     
     [Fact]
     public async Task explicit_routing_to_elsewhere_wins()
