feat: add servicebus sender correlation extensions (#312)

* feat: add servicebus sender correlation extensions

* pr-style: remove blank lines

docs/preview/02-Features/04-service-bus-extensions.md

@@ -1,17 +1,11 @@
----
+---
 title: "Azure Service Bus Extensions"
 layout: default
 ---
 
 # Azure Service Bus Extensions
 
-We provide several additional features related to message creation and message/context discoverability.
-
-- [Azure Service Bus Extensions](#azure-service-bus-extensions)
-  - [Installation](#installation)
-  - [Simplify Creating Service Bus Messages](#simplify-creating-service-bus-messages)
-  - [Simplify Message Information Discovery](#simplify-message-information-discovery)
-  - [Simplify Message Context Information Discovery](#simplify-message-context-information-discovery)
+We provide several additional features related to message creation/sending and message/context discoverability.
 
 ## Installation
 
@@ -21,6 +15,68 @@ This features requires to install our NuGet package:
 PM > Install-Package Arcus.Messaging.ServiceBus.Core
 ```
 
+## Automatic tracked and correlated Service Bus messages
+
+The Arcus message pump/router automatically makes sure that received Azure Service Bus messages are tracked as request telemetry in Application Insights. 
+If you also want the sender (dependency tracking) to be linked to the request, we provide a set of easy extensions on the `ServiceBusSender` to make this happen.
+For more information on dependency tracking, see the [Arcus Observability feature documentation on telemetry tracking](https://observability.arcus-azure.net/features/writing-different-telemetry-types/).
+
+Internally, we enrich the `ServiceBusMessage` with the message correlation and track the entire operation as an Azure Service Bus dependency.
+The result of this operation will result in a parent-child relationship between the dependency-request.
+
+Following example shows how any business content (`Order`) can be wrapped automatically internally in a `ServiceBusMessage`, and send as a correlated tracked message to the Azure Service Bus resource:
+
+```csharp
+using Azure.Messaging.ServiceBus;
+
+Order order = ... // Your business model.
+MessageCorrelationInfo correlation = ... // Retrieved from your message handler implementation.
+ILogger logger = ... // Your dependency injected logger from your application.
+
+await using (var client = new ServiceBusClient(...))
+await using (ServiceBusSender sender = client.CreateSender("my-queue-or-topic"))
+{
+    await sender.SendMessageAsync(order, correlation, logger);
+    // Output: {"DependencyType": "Azure Service Bus", "DependencyId": "c55c7885-30c5-4785-ad15-a96e03903bfa", "TargetName": "ordersqueue", "Duration": "00:00:00.2521801", "StartTime": "03/23/2020 09:56:31 +00:00", "IsSuccessful": true, "Context": {"EntityType": "Queue"}}
+}
+```
+
+The dependency tracking can also be configured with additional options to your needs. 
+You can also create your own `ServiceBusMessage` with one of the method overloads, so you have influence on the entire message's contents and application properties.
+
+> ⚠ Note that changes to the application property names should also reflect in changes in the application properties at the receiving side, so that the message pump/router knows where it will find these correlation properties.
+
+```csharp
+await sender.SendMessageAsync(order, correlation, logger, options =>
+{
+    // The Azure Service Bus application property name where the message correlation transaction ID will be set.
+    // Default: Transaction-Id
+    options.TransactionIdPropertyName = "My-Transaction-Id";
+
+    // The Azure Service Bus application property name where the dependency ID property will be set.
+    // This ID is by default generated and added to both the dependency tracking as the message.
+    // Default: Operation-Parent-Id
+    options.UpstreamServicepropertyName = "My-UpstreamService-Id";
+
+    // The Azure Service Bus application function to generate a dependency ID which will be added to both the message as the dependency tracking.
+    // Default: GUID generation.
+    options.GenerateDependencyId = () => $"dependency-{Guid.NewGuid()}";
+});
+
+ServiceBusMessage message = ...
+await sender.SendMessageAsync(message, ...);
+```
+
+We also support multiple message bodies or messages:
+
+```csharp
+Order[] orders = ...
+await sender.SendMessagesAsync(orders, ...);
+
+ServiceBusMessage[] messages = ...
+await sender.SendMessagesAsync(mesages, ...);
+```
+
 ## Simplify Creating Service Bus Messages
 
 Starting from the message body, we provide an extension to quickly wrap the content in a valid Azure Service Bus `Message` type that can be send.

src/Arcus.Messaging.Abstractions.ServiceBus/Arcus.Messaging.Abstractions.ServiceBus.csproj

@@ -34,7 +34,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Arcus.Observability.Telemetry.Core" Version="[2.4.0,3.0.0)" />
+    <PackageReference Include="Arcus.Observability.Telemetry.Core" Version="[2.5.0,3.0.0)" />
   </ItemGroup>
 
   <ItemGroup>

src/Arcus.Messaging.Abstractions/Arcus.Messaging.Abstractions.csproj

@@ -26,8 +26,6 @@
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
-    <PackageReference Include="Arcus.Observability.Correlation" Version="[2.4.0,3.0.0)" />
-    <PackageReference Include="Arcus.Observability.Telemetry.Serilog.Enrichers" Version="[2.4.0,3.0.0)" />
     <PackageReference Include="Guard.NET" Version="2.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="6.0.0" />
@@ -36,8 +34,6 @@
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' != 'net6.0'">
-    <PackageReference Include="Arcus.Observability.Correlation" Version="[2.2.0,3.0.0)" />
-    <PackageReference Include="Arcus.Observability.Telemetry.Serilog.Enrichers" Version="[2.2.0,3.0.0)" />
     <PackageReference Include="Guard.NET" Version="1.2.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="[3.1.8,5.0.0)" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="[3.1.8,5.0.0)" />
@@ -46,6 +42,9 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="Arcus.Observability.Correlation" Version="[2.5.0,3.0.0)" />
+    <PackageReference Include="Arcus.Observability.Telemetry.Core" Version="[2.5.0,3.0.0)" />
+    <PackageReference Include="Arcus.Observability.Telemetry.Serilog.Enrichers" Version="[2.5.0,3.0.0)" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
   </ItemGroup>
 

src/Arcus.Messaging.Pumps.Abstractions/Arcus.Messaging.Pumps.Abstractions.csproj

@@ -26,7 +26,6 @@
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
-    <PackageReference Include="Arcus.Observability.Telemetry.Serilog.Enrichers" Version="[2.4.0,3.0.0)" />
     <PackageReference Include="Guard.NET" Version="2.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="6.0.0" />
@@ -36,7 +35,6 @@
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' != 'net6.0'">
-    <PackageReference Include="Arcus.Observability.Telemetry.Serilog.Enrichers" Version="[2.2.0,3.0.0)" />
     <PackageReference Include="Guard.NET" Version="1.2.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="[3.1.8,5.0.0)" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="[3.1.8,5.0.0)" />
@@ -46,6 +44,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="Arcus.Observability.Telemetry.Serilog.Enrichers" Version="[2.5.0,3.0.0)" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
   </ItemGroup>
 

src/Arcus.Messaging.Pumps.ServiceBus/Arcus.Messaging.Pumps.ServiceBus.csproj

@@ -27,7 +27,6 @@
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net6.0'">
     <PackageReference Include="Arcus.Security.Providers.AzureKeyVault" Version="[1.7.0,2.0.0)" />
-    <PackageReference Include="Azure.Identity" Version="1.4.0" />
     <PackageReference Include="Guard.NET" Version="2.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="6.0.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="6.0.0" />
@@ -38,7 +37,6 @@
 
   <ItemGroup Condition="'$(TargetFramework)' != 'net6.0'">
     <PackageReference Include="Arcus.Security.Providers.AzureKeyVault" Version="[1.4.0,2.0.0)" />
-    <PackageReference Include="Azure.Identity" Version="1.2.3" />
     <PackageReference Include="Guard.NET" Version="1.2.0" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="[3.1.8,5.0.0)" />
     <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="[3.1.8,5.0.0)" />
@@ -48,6 +46,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="Azure.Identity" Version="1.6.0" />
     <PackageReference Include="Microsoft.Azure.Management.ServiceBus" Version="2.1.0" />
   </ItemGroup>
 

src/Arcus.Messaging.ServiceBus.Core/Arcus.Messaging.ServiceBus.Core.csproj

@@ -35,6 +35,10 @@
     <PackageReference Include="Guard.NET" Version="1.2.0" />
   </ItemGroup>
 
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Azure" Version="1.2.0" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\Arcus.Messaging.Abstractions\Arcus.Messaging.Abstractions.csproj" />
   </ItemGroup>