Documentation for NServiceBus 10.2.0

Snippets/Core/Core_10/BasicUsageOfIBus.cs

@@ -5,13 +5,12 @@
 
 class BasicUsageOfIBus
 {
-    async Task Send(EndpointConfiguration endpointConfiguration)
+    async Task Send(IMessageSession messageSession)
     {
         #region BasicSend
 
-        var endpointInstance = await Endpoint.Start(endpointConfiguration);
         var message = new MyMessage();
-        await endpointInstance.Send(message);
+        await messageSession.Send(message);
 
         #endregion
     }
@@ -30,86 +29,86 @@ public Task Handle(MyMessage message, IMessageHandlerContext context)
 
     #endregion
 
-    async Task SetDestination(IEndpointInstance endpoint)
+    async Task SetDestination(IMessageSession messageSession)
     {
         #region BasicSendSetDestination
 
         var options = new SendOptions();
         options.SetDestination("MyDestination");
-        await endpoint.Send(new MyMessage(), options);
+        await messageSession.Send(new MyMessage(), options);
 
         #endregion
     }
 
-    async Task SpecificInstance(IEndpointInstance endpoint)
+    async Task SpecificInstance(IMessageSession messageSession)
     {
         #region BasicSendSpecificInstance
 
         var options = new SendOptions();
         options.RouteToSpecificInstance("MyInstance");
         var message = new MyMessage();
-        await endpoint.Send(message, options);
+        await messageSession.Send(message, options);
 
         #endregion
     }
 
-    async Task ThisEndpoint(IEndpointInstance endpoint)
+    async Task ThisEndpoint(IMessageSession messageSession)
     {
         #region BasicSendToAnyInstance
 
         var options = new SendOptions();
         options.RouteToThisEndpoint();
-        await endpoint.Send(new MyMessage(), options);
+        await messageSession.Send(new MyMessage(), options);
         // or
-        await endpoint.SendLocal(new MyMessage());
+        await messageSession.SendLocal(new MyMessage());
 
         #endregion
     }
 
-    async Task ThisInstance(IEndpointInstance endpoint)
+    async Task ThisInstance(IMessageSession messageSession)
     {
         #region BasicSendToThisInstance
 
         var options = new SendOptions();
         options.RouteToThisInstance();
         var message = new MyMessage();
-        await endpoint.Send(message, options);
+        await messageSession.Send(message, options);
 
         #endregion
     }
 
-    async Task SendReplyToThisInstance(IEndpointInstance endpoint)
+    async Task SendReplyToThisInstance(IMessageSession messageSession)
     {
         #region BasicSendReplyToThisInstance
 
         var options = new SendOptions();
         options.RouteReplyToThisInstance();
         var message = new MyMessage();
-        await endpoint.Send(message, options);
+        await messageSession.Send(message, options);
 
         #endregion
     }
 
-    async Task SendReplyToAnyInstance(IEndpointInstance endpoint)
+    async Task SendReplyToAnyInstance(IMessageSession messageSession)
     {
         #region BasicSendReplyToAnyInstance
 
         var options = new SendOptions();
         options.RouteReplyToAnyInstance();
         var message = new MyMessage();
-        await endpoint.Send(message, options);
+        await messageSession.Send(message, options);
 
         #endregion
     }
 
-    async Task SendReplyTo(IEndpointInstance endpoint)
+    async Task SendReplyTo(IMessageSession messageSession)
     {
         #region BasicSendReplyToDestination
 
         var options = new SendOptions();
         options.RouteReplyTo("MyDestination");
         var message = new MyMessage();
-        await endpoint.Send(message, options);
+        await messageSession.Send(message, options);
 
         #endregion
     }

Snippets/Core/Core_10/Container/ExternallyManaged.cs

@@ -10,6 +10,7 @@ public class ExternallyManaged
 {
     async Task Usage(EndpointConfiguration endpointConfiguration)
     {
+#pragma warning disable CS0618 // Type or member is obsolete
         #region ExternalPrepare
 
         IServiceCollection serviceCollection = new ServiceCollection();
@@ -25,5 +26,6 @@ async Task Usage(EndpointConfiguration endpointConfiguration)
         var startedEndpoint = await startableEndpoint.Start(builder);
 
         #endregion
+#pragma warning restore CS0618 // Type or member is obsolete
     }
 }

Snippets/Core/Core_10/Container/Usage.cs

@@ -5,6 +5,7 @@
 
 class Usage
 {
+#pragma warning disable CS0618 // Type or member is obsolete
     void InstancePerCall(EndpointConfiguration endpointConfiguration)
     {
         #region InstancePerCall
@@ -82,4 +83,5 @@ void DelegateSingleInstance(EndpointConfiguration endpointConfiguration)
 
         #endregion
     }
+#pragma warning restore CS0618 // Type or member is obsolete
 }

Snippets/Core/Core_10/Core_10.csproj

@@ -10,9 +10,9 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.*" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.*" />
     <PackageReference Include="Newtonsoft.Json" Version="13.*" />
-    <PackageReference Include="NServiceBus" Version="10.*" />
+    <PackageReference Include="NServiceBus" Version="10.2.0-alpha.5" />
     <PackageReference Include="NServiceBus.Callbacks" Version="6.*" />
     <PackageReference Include="NServiceBus.ClaimCheck" Version="2.*" />
     <PackageReference Include="NServiceBus.Encryption.MessageProperty" Version="6.*" />

Snippets/Core/Core_10/DelayedDelivery/DeferForDateTime.cs

@@ -6,15 +6,15 @@ namespace Core.DelayedDelivery;
 
 class DeferForDateTime
 {
-    async Task SendDelayedMessage(IEndpointInstance endpoint, IMessageHandlerContext handlerContext)
+    async Task SendDelayedMessage(IMessageSession messageSession, IMessageHandlerContext handlerContext)
     {
         #region delayed-delivery-datetime
         var options = new SendOptions();
         options.DoNotDeliverBefore(new DateTime(2016, 12, 25));
 
         await handlerContext.Send(new MessageToBeSentLater(), options);
         // OR
-        await endpoint.Send(new MessageToBeSentLater(), options, handlerContext.CancellationToken);
+        await messageSession.Send(new MessageToBeSentLater(), options, handlerContext.CancellationToken);
         #endregion
     }
 

Snippets/Core/Core_10/DelayedDelivery/DeferForTimeSpan.cs

@@ -6,7 +6,7 @@
 
 class DeferForTimeSpan
 {
-    async Task SendDelayedMessage(EndpointConfiguration endpointConfiguration, IEndpointInstance endpoint, IMessageHandlerContext handlerContext)
+    async Task SendDelayedMessage(EndpointConfiguration endpointConfiguration, IMessageSession messageSession, IMessageHandlerContext handlerContext)
     {
         #region configure-persistence-timeout
 
@@ -22,7 +22,7 @@ async Task SendDelayedMessage(EndpointConfiguration endpointConfiguration, IEndp
 
         await handlerContext.Send(new MessageToBeSentLater(), sendOptions);
         // OR
-        await endpoint.Send(new MessageToBeSentLater(), sendOptions, handlerContext.CancellationToken);
+        await messageSession.Send(new MessageToBeSentLater(), sendOptions, handlerContext.CancellationToken);
 
         #endregion
     }

Snippets/Core/Core_10/Features/FeatureConfiguration.cs

@@ -30,8 +30,6 @@ async Task EndpointConfiguration(EndpointConfiguration endpointConfiguration)
 
         // disable features not in use
         endpointConfiguration.DisableFeature<Sagas>();
-
-        var startableEndpoint = await Endpoint.Create(endpointConfiguration);
         #endregion
     }
 

Snippets/Core/Core_10/Handlers/ConventionBasedHandlers.cs

@@ -0,0 +1,116 @@
+using System.Net.Http;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Configuration;
+using NServiceBus;
+
+namespace OuterNS.InnerNS;
+
+public record MyMessage();
+public record Msg1();
+public record Msg2();
+
+#region SimpleConventionBasedHandler
+
+public class ConventionHandler
+{
+    public async Task Handle(MyMessage message, IMessageHandlerContext context)
+    {
+        // do something with the message data
+    }
+}
+
+#endregion
+
+#region ConventionsBasedHandlerExtraParams
+
+public class ConventionHandlerWithExtraParams
+{
+    public async Task Handle(MyMessage message,
+        IMessageHandlerContext context,
+        DatabaseService database,
+        CancellationToken cancellationToken)
+    {
+        // do something with the message data
+    }
+}
+
+#endregion
+
+#region DecoratedConventionHandler
+
+[Handler]
+public class DecoratedConventionHandler
+{
+    public async Task Handle(MyMessage message, IMessageHandlerContext context)
+    {
+    }
+}
+
+#endregion
+
+
+#region ConventionHandlersTldrSample
+
+[Handler]
+public class HandlersByConvention
+{
+    public async Task Handle(Msg1 message,
+        IMessageHandlerContext context,
+        CancellationToken cancellationToken)
+    {
+    }
+
+    public static async Task Handle(Msg2 message,
+        IMessageHandlerContext context,
+        DatabaseService database,
+        IConfiguration configuration,
+        IHttpClientFactory httpClientFactory,
+        CancellationToken cancellationToken)
+    {
+    }
+}
+#endregion
+
+public class DatabaseService;
+
+public class ConventionHandlerRegistration
+{
+    public static void Setup(EndpointConfiguration endpointConfiguration)
+    {
+        #region ConventionHandlerRegistrationWithoutAttribute
+
+        endpointConfiguration.AddHandler<ConventionHandler>();
+
+        #endregion
+
+        #region ConventionHandlerAddAllFromAssembly
+        endpointConfiguration.Handlers.SampleProject.AddAll();
+        #endregion
+
+        #region ConventionHandlerAllGeneratedAddMethods
+
+        // Add just one handler
+        endpointConfiguration.Handlers.SampleProject.OuterNS.InnerNS
+            .AddDecoratedConventionHandler();
+
+        // Add all handlers or sagas from a namespace…
+        endpointConfiguration.Handlers.SampleProject.OuterNS.InnerNS.AddAllHandlers();
+        endpointConfiguration.Handlers.SampleProject.OuterNS.InnerNS.AddAllSagas();
+        endpointConfiguration.Handlers.SampleProject.OuterNS.InnerNS.AddAll();
+        // …at any point in the namespace hierarchy
+        endpointConfiguration.Handlers.SampleProject.OuterNS.AddAllHandlers();
+        endpointConfiguration.Handlers.SampleProject.OuterNS.AddAllSagas();
+        endpointConfiguration.Handlers.SampleProject.OuterNS.AddAll();
+
+        // Or add all from an entire assembly
+        endpointConfiguration.Handlers.SampleProject.AddAllHandlers();
+        endpointConfiguration.Handlers.SampleProject.AddAllSagas();
+        endpointConfiguration.Handlers.SampleProject.AddAll();
+
+        #endregion
+    }
+}
+
+[HandlerRegistryExtensions(EntryPointName = "SampleProject")]
+public static partial class RegistrationExtensions;

Snippets/Core/Core_10/Headers/Writers/HeaderWriterAudit.cs

@@ -1,4 +1,7 @@
-namespace Core.Headers.Writers;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+namespace Core.Headers.Writers;
 
 using System.Threading;
 using System.Threading.Tasks;
@@ -31,10 +34,15 @@ public async Task Write()
         endpointConfiguration.RegisterMessageMutator(new Mutator());
         endpointConfiguration.UseSerialization<SystemJsonSerializer>();
 
-        var endpointInstance = await Endpoint.Start(endpointConfiguration);
-        await endpointInstance.SendLocal(new MessageToSend());
+        var builder = Host.CreateApplicationBuilder();
+        builder.Services.AddNServiceBusEndpoint(endpointConfiguration);
+        var host = builder.Build();
+        await host.StartAsync();
+        var messageSession = host.Services.GetRequiredService<IMessageSession>();
+
+        await messageSession.SendLocal(new MessageToSend());
         ManualResetEvent.WaitOne();
-        await endpointInstance.Stop();
+        await host.StopAsync();
     }
 
     class MessageToSend :

Snippets/Core/Core_10/Headers/Writers/HeaderWriterAuditAudit.txt

@@ -1,22 +1,23 @@
 Snippet is code generated by HeaderWriterAudit.cs
 startcode HeaderWriterAuditAudit 
 $.diagnostics.hostdisplayname = MACHINENAME
-$.diagnostics.hostid = 7f787fc8e0611a3fab8a93c8767f6639
-$.diagnostics.originating.hostid = 7f787fc8e0611a3fab8a93c8767f6639
+$.diagnostics.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
+$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
 NServiceBus.ContentType = application/json
-NServiceBus.ConversationId = 74c7b4a9-65f5-4c15-b173-b33e015e0c71
-NServiceBus.CorrelationId = 7b89fe9e-14f8-4ee4-be40-b33e015e0c70
+NServiceBus.ConversationId = 5520abbd-7b30-4914-a3d4-b43b016d917e
+NServiceBus.CorrelationId = 4ad00d77-6e0d-44cc-bd3e-b43b016d917d
 NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
-NServiceBus.MessageId = 7b89fe9e-14f8-4ee4-be40-b33e015e0c70
+NServiceBus.MessageId = 4ad00d77-6e0d-44cc-bd3e-b43b016d917d
 NServiceBus.MessageIntent = Send
+NServiceBus.OpenTelemetry.StartNewTrace = False
 NServiceBus.OriginatingEndpoint = HeaderWriterAudit
 NServiceBus.OriginatingMachine = MACHINENAME
-NServiceBus.ProcessingEnded = 2025-08-19 23:22:04:600525 Z
+NServiceBus.ProcessingEnded = 2026-04-29 22:10:59:647662 Z
 NServiceBus.ProcessingEndpoint = HeaderWriterAudit
 NServiceBus.ProcessingMachine = MACHINENAME
-NServiceBus.ProcessingStarted = 2025-08-19 23:22:04:600177 Z
+NServiceBus.ProcessingStarted = 2026-04-29 22:10:59:639234 Z
 NServiceBus.ReplyToAddress = HeaderWriterAudit
-NServiceBus.TimeSent = 2025-08-19 21:14:29:280127 Z
-NServiceBus.Version = 10.0.0
+NServiceBus.TimeSent = 2026-04-29 22:10:59:617241 Z
+NServiceBus.Version = 10.2.0
 
 endcode