Core-hosting with AddNServiceBusEndpoint by mattmercurio · Pull Request #8206 · Particular/docs.particular.net

mattmercurio · 2026-04-24T20:58:19Z

No description provided.

danielmarbach · 2026-04-28T09:56:09Z

This is already pretty good!

Co-authored-by: Daniel Marbach <daniel.marbach@openplace.net>

Co-authored-by: David Boike <david.boike@gmail.com>

danielmarbach · 2026-04-28T20:32:32Z

+{
+    async Task SingleEndpoint()
+    {
+        #region AddNServiceBusEndpointSingle


Would it be helpful for each scenario to show an example on how to resolve things explicitely? For example we could show something like this for a single endpoint

Using the provider directly

serviceProvider.GetRequiredService<IMessageSession>();

injected into a class

MyComponent(IMessageSession session)

and for the other samples accordingly

serviceProvider.GetRequiredKeyedService<IMessageSession>("ChosenIdentifier");

and

MyComponent([FromKeyedServices("ChosenIdentifier")] IMessageSession session)

and maybe even something like

// otherThing is global MyComponent(IMyOtherThing otherThing, [FromKeyedServices("ChosenIdentifier")] IMessageSession session)

and so on until it becomes clear?

DavidBoike · 2026-04-28T20:23:43Z

@@ -0,0 +1,80 @@
+---
+title: Recommended hosting model


I'm struggling with what we call this. This can only be the "recommended hosting model" as long as we don't replace it, then what would it be called? But "Microsoft Generic Host" is a dead term, right?

@DavidBoike Yea, I've gone back and forth on this title a few times. What about "Hosting with Microsoft.Extensions.Hosting" ? Technically right but not "hey you should favor this"

DavidBoike · 2026-04-28T20:25:29Z

+  - samples/hosting/generic-host
+---
+
+Starting in NServiceBus version 10.2, the recommended way to host NServiceBus is through `Microsoft.Extensions.Hosting` by registering endpoints with `IServiceCollection` using `AddNServiceBusEndpoint`. This aligns endpoint startup, dependency injection, and logging with the standard .NET hosting model, and it supports both the common single-endpoint case and advanced scenarios that host multiple endpoints in one process.


Wouldn't it be more accurate to say something like 10.2 takes a dependency on Microsoft.Extensions.Hosting and offers hosting capabilities without requiring any other NServiceBus packages?

BUT

Remember that 6 months after 10.2 is released, 10.1 is no longer supported, and this page is V10 and up only. We should be thinking about this documentation through the lens of what it will look like to someone building an endpoint after NServiceBus 11 is released, and less like an upgrade guide.

DavidBoike · 2026-04-28T20:31:42Z

+
+Starting in NServiceBus version 10.2, the recommended way to host NServiceBus is through `Microsoft.Extensions.Hosting` by registering endpoints with `IServiceCollection` using `AddNServiceBusEndpoint`. This aligns endpoint startup, dependency injection, and logging with the standard .NET hosting model, and it supports both the common single-endpoint case and advanced scenarios that host multiple endpoints in one process.
+
+## Choosing an integration path


Because of the previous comment, this should not be presented as "yet another choice you have to make" to use NServiceBus. We need to consider how people reading this when V11 is out and presenting it as "This is the way".

If we want to put in a partial that shows a note box about the old way in V10 only, that's possible though.

DavidBoike · 2026-04-28T20:33:25Z

+
+## Hosting a single endpoint
+
+Register the endpoint on the host's service collection. For new development, this is the recommended alternative to the `UseNServiceBus` pattern in `NServiceBus.Extensions.Hosting`.


Don't compare to UseNServiceBus just tell how to do it

DavidBoike · 2026-04-28T20:34:20Z

+
+snippet: AddNServiceBusEndpointSingle
+
+The endpoint starts and stops with the host's lifecycle. `IMessageSession` is available in dependency injection for components that need to send or publish from outside a message handler.


Could we use slightly more precise language about what happens with the IMessageSession?

DavidBoike · 2026-04-28T20:51:52Z

+
+## Endpoint identity and the DI identifier
+
+- **Endpoint name** — the NServiceBus identity set on `EndpointConfiguration`. Drives the input queue, routing, diagnostics, and log context. Unique across the system.


Unique across the system

I don't think that's true?

Also, either we can write complete sentences, or if we're really trying to be terse, we can put all of this in a comparison table.

DavidBoike · 2026-04-28T20:54:02Z

+
+In a single-endpoint host, the two are the same value and the distinction does not matter. In a multi-endpoint host, each endpoint retains its own input queue, `IMessageSession`, and per-endpoint configuration.
+
+## Logging


I could see a sample of how log output looks with multiple endpoints, but most of the stuff below this line is upgrade guide material.

DavidBoike · 2026-04-28T20:55:31Z

 ### Stop the endpoint

-[Microsoft Generic Host's](/nservicebus/hosting/extensions-hosting.md) `IHostApplicationLifetime.Stop` method stops the NServiceBus endpoint gracefully.
+When hosted with [`Microsoft.Extensions.Hosting`](https://learn.microsoft.com/en-us/dotnet/core/extensions/generic-host), calling `IHostApplicationLifetime.StopApplication()` stops the host gracefully, which in turn stops the NServiceBus endpoint.


I don't know if "when hosting with package I never added to the project myself" is going to land right?

DavidBoike · 2026-04-28T20:57:12Z

+- [Recommended hosting model](/nservicebus/hosting/core-hosting.md) using the built-in `AddNServiceBusEndpoint` integration.
+- [NServiceBus.Extensions.Hosting](/nservicebus/hosting/extensions-hosting.md) for the existing package-based `UseNServiceBus` integration.


This needs to be turned into partials, because in V9 and below there is only option and in V10 and above (discounting 10.0 and 10.1 which ultimately go away) there is only one (albeit different) choice.

DavidBoike · 2026-04-28T20:57:37Z

+### Using Microsoft.Extensions.Hosting

-NServiceBus can be integrated into any web host that supports the [Microsoft Generic Host](https://docs.microsoft.com/en-us/dotnet/core/extensions/generic-host) using the [NServiceBus Generic Host integration](/nservicebus/hosting/extensions-hosting.md). The Generic Host integration automatically registers `IMessageSession` with the dependency injection container.
+NServiceBus integrates with any web host that supports the [.NET Generic Host](https://docs.microsoft.com/en-us/dotnet/core/extensions/generic-host). For new development, use the [recommended hosting model](/nservicebus/hosting/core-hosting.md). Existing applications can continue with [NServiceBus.Extensions.Hosting](/nservicebus/hosting/extensions-hosting.md). In both paths, `IMessageSession` is available through dependency injection.


Same here about partials.

mattmercurio self-assigned this Apr 24, 2026

mattmercurio requested a review from DavidBoike April 24, 2026 22:53

mattmercurio force-pushed the docs-addnservicebusendpoint-multi branch from 7faf837 to 547cd44 Compare April 27, 2026 15:40

mattmercurio added 4 commits April 27, 2026 12:40

Add AddNServiceBusEndpoint hosting page

1e43994

Core hosting guidance

69ae2b7

Core hosting guidance

be2f35e

Modern hosting language changes

c36de1a

mattmercurio force-pushed the docs-addnservicebusendpoint-multi branch from 547cd44 to c36de1a Compare April 27, 2026 17:41

DavidBoike reviewed Apr 27, 2026

View reviewed changes

Comment thread nservicebus/hosting/core-hosting.md

Core-hosting and snippets

c8c98d0

mattmercurio requested review from andreasohlund and danielmarbach April 28, 2026 00:40

'Recommended' hosting wording

476ecbe

mattmercurio marked this pull request as ready for review April 28, 2026 00:52

andreasohlund reviewed Apr 28, 2026

View reviewed changes

Comment thread Snippets/Core/Core_10/Hosting/AddNServiceBusEndpoint.cs Outdated

Comment thread nservicebus/hosting/core-hosting.md

Comment thread nservicebus/hosting/core-hosting.md

danielmarbach reviewed Apr 28, 2026

View reviewed changes

Comment thread nservicebus/hosting/core-hosting.md Outdated

danielmarbach reviewed Apr 28, 2026

View reviewed changes

Comment thread nservicebus/hosting/core-hosting.md Outdated

danielmarbach reviewed Apr 28, 2026

View reviewed changes

Comment thread nservicebus/hosting/core-hosting.md Outdated

danielmarbach reviewed Apr 28, 2026

View reviewed changes

Comment thread nservicebus/hosting/core-hosting.md Outdated

mattmercurio and others added 4 commits April 28, 2026 14:11

Update nservicebus/hosting/core-hosting.md

d642fbe

Co-authored-by: Daniel Marbach <daniel.marbach@openplace.net>

Apply suggestions from code review

c24b1d2

Co-authored-by: Daniel Marbach <daniel.marbach@openplace.net>

Update nservicebus/hosting/core-hosting.md

69b5fa4

Co-authored-by: David Boike <david.boike@gmail.com>

Per-tenant hosting scenario

aad94f8

danielmarbach reviewed Apr 28, 2026

View reviewed changes

DavidBoike reviewed Apr 28, 2026

View reviewed changes


		Starting in NServiceBus version 10.2, the recommended way to host NServiceBus is through `Microsoft.Extensions.Hosting` by registering endpoints with `IServiceCollection` using `AddNServiceBusEndpoint`. This aligns endpoint startup, dependency injection, and logging with the standard .NET hosting model, and it supports both the common single-endpoint case and advanced scenarios that host multiple endpoints in one process.

		## Choosing an integration path


		## Hosting a single endpoint

		Register the endpoint on the host's service collection. For new development, this is the recommended alternative to the `UseNServiceBus` pattern in `NServiceBus.Extensions.Hosting`.


		snippet: AddNServiceBusEndpointSingle

		The endpoint starts and stops with the host's lifecycle. `IMessageSession` is available in dependency injection for components that need to send or publish from outside a message handler.


		## Endpoint identity and the DI identifier

		- Endpoint name — the NServiceBus identity set on `EndpointConfiguration`. Drives the input queue, routing, diagnostics, and log context. Unique across the system.


		In a single-endpoint host, the two are the same value and the distinction does not matter. In a multi-endpoint host, each endpoint retains its own input queue, `IMessageSession`, and per-endpoint configuration.

		## Logging

		- [Recommended hosting model](/nservicebus/hosting/core-hosting.md) using the built-in `AddNServiceBusEndpoint` integration.
		- [NServiceBus.Extensions.Hosting](/nservicebus/hosting/extensions-hosting.md) for the existing package-based `UseNServiceBus` integration.

Conversation

mattmercurio commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danielmarbach commented Apr 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mattmercurio commented Apr 24, 2026 •

edited

Loading