Extensions hosting upgrade guide draft

menu/menu.yaml

@@ -1361,6 +1361,10 @@
         Title: Version 6 to 7
       - Url: nservicebus/upgrades/host-4to5
         Title: Version 4 to 5
+    - Title: Extensions.Hosting
+      Articles:
+      - Url: nservicebus/upgrades/extensions-hosting-4to5
+        Title: Version 4 to 5
     - Title: NServiceBus.Azure deprecated
       Url: nservicebus/upgrades/azure-deprecation
     - Title: Azure Cloud Services Host

nservicebus/hosting/extensions-hosting.md

@@ -9,7 +9,7 @@ related:
 ---
 
 > [!NOTE]
-> For new development, prefer [hosting with Microsoft.Extensions.Hosting](/nservicebus/hosting/core-hosting.md) using the built-in `AddNServiceBusEndpoint` integration on `IServiceCollection`. The **NServiceBus.Extensions.Hosting** package's `UseNServiceBus` hosting method described on this page is deprecated starting with NServiceBus 10.2.0. See the [upgrade guide](/nservicebus/upgrades/10to11/) for migration details.
+> For new development, prefer [hosting with Microsoft.Extensions.Hosting](/nservicebus/hosting/core-hosting.md) using the built-in `AddNServiceBusEndpoint` integration on `IServiceCollection`. The **NServiceBus.Extensions.Hosting** package's `UseNServiceBus` hosting method described on this page is deprecated starting with NServiceBus 10.2.0. See the [upgrade guide](/nservicebus/upgrades/extensions-hosting-4to5.md) for migration details.
 
 ## Configuration
 

nservicebus/upgrades/extensions-hosting-4to5.md

@@ -0,0 +1,70 @@
+---
+title: NServiceBus.Extensions.Hosting Upgrade Version 4 to 5
+summary: How to upgrade NServiceBus.Extensions.Hosting from version 4 to 5
+component: Extensions.Hosting
+reviewed: 2026-05-22
+isUpgradeGuide: true
+upgradeGuideCoreVersions:
+  - 10
+---
+
+NServiceBus 10.2 introduces built-in support for hosting endpoints in .NET Generic Host applications via `IServiceCollection.AddNServiceBusEndpoint`. This makes the `NServiceBus.Extensions.Hosting` package's `UseNServiceBus` extension methods unnecessary.
+
+> [!NOTE]
+> NServiceBus version 10.2 or later is required.
+
+## UseNServiceBus is deprecated
+
+The `UseNServiceBus` extension methods on `HostApplicationBuilder` and `IHostBuilder` have been deprecated. Replace calls to `UseNServiceBus` with `AddNServiceBusEndpoint` on the host's service collection, then remove the `NServiceBus.Extensions.Hosting` package reference.
+
+### HostApplicationBuilder
+
+Replace:
+
+```csharp
+var builder = Host.CreateApplicationBuilder();
+
+builder.UseNServiceBus(endpointConfiguration);
+
+var host = builder.Build();
+```
+
+with:
+
+```csharp
+var builder = Host.CreateApplicationBuilder();
+
+builder.Services.AddNServiceBusEndpoint(endpointConfiguration);
+
+var host = builder.Build();
+```
+
+### IHostBuilder
+
+Replace:
+
+```csharp
+var host = Host.CreateDefaultBuilder()
+    .UseNServiceBus(context =>
+    {
+        var endpointConfiguration = new EndpointConfiguration("MyEndpoint");
+        return endpointConfiguration;
+    })
+    .Build();
+```
+
+with:
+
+```csharp
+var builder = Host.CreateApplicationBuilder();
+
+var endpointConfiguration = new EndpointConfiguration("MyEndpoint");
+
+builder.Services.AddNServiceBusEndpoint(endpointConfiguration);
+
+var host = builder.Build();
+```
+
+## Remove the package
+
+After replacing `UseNServiceBus` with `AddNServiceBusEndpoint`, remove the `NServiceBus.Extensions.Hosting` package reference from the project. The `AddNServiceBusEndpoint` method is provided by the core `NServiceBus` package starting with version 10.2.