Skip to content

Commit 5b2305c

Browse files
CopilotIEvangelistadegeo
authored
Document HostingStartup incompatibility and migration to modern hosting patterns for .NET Aspire (#4187)
* Initial plan * Add troubleshooting documentation for HostingStartup incompatibility Co-authored-by: IEvangelist <[email protected]> * Fix duplicate link and complete documentation Co-authored-by: IEvangelist <[email protected]> * Fix style guide compliance: remove package-lock.json, add trailing newline, move code snippets to external files, fix ordered list format Co-authored-by: IEvangelist <[email protected]> * Remove Option 4 and dependency injection plugin example code Co-authored-by: IEvangelist <[email protected]> * Refactor troubleshooting doc to focus on migration concepts rather than multiple options Co-authored-by: IEvangelist <[email protected]> * Fix bullet points to be complete sentences with proper punctuation Co-authored-by: IEvangelist <[email protected]> * Update docs/troubleshooting/hosting-startup-not-supported.md * Fix build errors in hosting-startup snippet files Co-authored-by: IEvangelist <[email protected]> * Replace non-standard arrow characters with table format for better accessibility Co-authored-by: adegeo <[email protected]> * Fix punctuation in table benefit column - add periods to complete sentences Co-authored-by: adegeo <[email protected]> * Update ai-usage metadata from ai-assisted to ai-generated Co-authored-by: adegeo <[email protected]> * Update ai-usage metadata back to ai-assisted based on team decision Co-authored-by: adegeo <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: IEvangelist <[email protected]> Co-authored-by: David Pine <[email protected]> Co-authored-by: adegeo <[email protected]>
1 parent 9c0b581 commit 5b2305c

File tree

7 files changed

+143
-0
lines changed

7 files changed

+143
-0
lines changed

‎docs/fundamentals/integrations-overview.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ Client integrations wire up client libraries to [dependency injection (DI)](/dot
3333

3434
These packages configure existing client libraries to connect to hosting integrations. They extend the <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> interface allowing client-consuming projects, such as your web app or API, to use the connected resource. The official [client integration NuGet packages](https://www.nuget.org/packages?q=owner%3A+aspire+tags%3A+aspire+client+integration&includeComputedFrameworks=true&prerel=true&sortby=relevance) are tagged with `aspire`, `integration`, and `client`. In addition to the official client integrations, the [community has created client integrations](../community-toolkit/overview.md) for various services and platforms as part of the Community Toolkit.
3535

36+
> [!IMPORTANT]
37+
> .NET Aspire integrations require <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> and are **not compatible** with `HostingStartup` implementations, which only provide access to <xref:Microsoft.AspNetCore.Hosting.IWebHostBuilder>. If you're using `HostingStartup` for modular configuration, see [HostingStartup is not supported with .NET Aspire integrations](../troubleshooting/hosting-startup-not-supported.md) for migration guidance.
38+
3639
For more information on creating a custom client integration, see [Create custom .NET Aspire client integrations](../extensibility/custom-client-integration.md).
3740

3841
### Relationship between hosting and client integrations

‎docs/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -493,6 +493,9 @@ items:
493493
- name: Allow unsecure transport
494494
displayName: unsecure transport,http,non-tls
495495
href: troubleshooting/allow-unsecure-transport.md
496+
- name: HostingStartup is not supported
497+
displayName: hosting startup,IWebHostBuilder,IHostApplicationBuilder,migration
498+
href: troubleshooting/hosting-startup-not-supported.md
496499
- name: Untrusted localhost certificate
497500
href: troubleshooting/untrusted-localhost-certificate.md
498501
- name: Unable to install .NET Aspire workload

‎docs/troubleshooting/hosting-startup-not-supported.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: HostingStartup is not supported with .NET Aspire integrations
3+
description: Learn how to migrate from HostingStartup to the IHostApplicationBuilder pattern for use with .NET Aspire integrations.
4+
ms.date: 08/04/2025
5+
ai-usage: ai-assisted
6+
---
7+
8+
# HostingStartup is not supported with .NET Aspire integrations
9+
10+
.NET Aspire integrations require the use of <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder>, but `HostingStartup` only provides access to <xref:Microsoft.AspNetCore.Hosting.IWebHostBuilder>. This fundamental incompatibility means that you can't configure .NET Aspire integrations from within a `HostingStartup` implementation.
11+
12+
## Symptoms
13+
14+
When attempting to use .NET Aspire integrations within a HostingStartup implementation, you might encounter:
15+
16+
- **Compilation errors**: Aspire integration extension methods like `AddNpgsqlDbContext` or `AddRedis` are not available on `IWebHostBuilder`.
17+
- **Runtime configuration issues**: Even if you access the underlying services, the proper configuration and service registration won't occur.
18+
- **Missing telemetry and resilience**: Aspire's built-in observability, health checks, and resilience patterns won't be applied.
19+
20+
## Why HostingStartup doesn't work with .NET Aspire
21+
22+
.NET Aspire integrations extend <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> to provide:
23+
24+
- Standardized configuration patterns.
25+
- Built-in health checks.
26+
- Telemetry and observability.
27+
- Resilience patterns.
28+
- Service discovery integration.
29+
30+
The `HostingStartup` feature was designed for the older ASP.NET Core hosting model and only provides access to <xref:Microsoft.AspNetCore.Hosting.IWebHostBuilder>, which doesn't include these modern hosting capabilities.
31+
32+
## Migrating from HostingStartup
33+
34+
The `HostingStartup` feature represents an older ASP.NET Core hosting model that predates the modern <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> pattern that .NET Aspire requires. Migration is necessary to leverage .NET Aspire's integrations and modern hosting capabilities.
35+
36+
### Understanding the API changes
37+
38+
The fundamental difference lies in the hosting abstractions:
39+
40+
**Before (HostingStartup pattern):**
41+
42+
:::code language="csharp" source="snippets/hosting-startup-not-supported/hosting-startup-before.cs":::
43+
44+
**After (Modern hosting pattern):**
45+
46+
:::code language="csharp" source="snippets/hosting-startup-not-supported/host-application-builder-after.cs":::
47+
48+
### Key conceptual changes
49+
50+
When migrating from `HostingStartup` to the modern hosting model, you're moving between these approaches:
51+
52+
| Legacy pattern | Modern pattern | Benefit |
53+
|---|---|---|
54+
| `IWebHostBuilder` | `IHostApplicationBuilder` | Access to modern hosting features and .NET Aspire integrations. |
55+
| Separate startup classes | Program.cs configuration | Service configuration moves directly into the application's entry point for better clarity and debugging. |
56+
| Manual service registration | Integration packages | .NET Aspire integrations handle service registration, configuration, health checks, and telemetry automatically. |
57+
58+
### Migration resources
59+
60+
For detailed migration guidance, see:
61+
62+
- [Migrate from ASP.NET Core 5.0 to 6.0](/aspnet/core/migration/50-to-60?view=aspnetcore-9.0) - Covers the transition to the minimal hosting model
63+
- [David Fowl's ASP.NET Core 6.0 migration guide](https://gist.github.com/davidfowl/0e0372c3c1d895c3ce195ba983b1e03d) - Provides practical migration patterns and examples
64+
65+
## Additional considerations
66+
67+
- **Service discovery**: .NET Aspire integrations automatically configure service discovery. If you were using HostingStartup for service-to-service communication, consider using Aspire's [service discovery features](../service-discovery/overview.md).
68+
69+
- **Configuration management**: Instead of hard-coding connection strings in HostingStartup, use .NET Aspire's configuration patterns with connection string names that map to resources in your app host.
70+
71+
- **Testing**: .NET Aspire provides [testing capabilities](../testing/overview.md) that work with the new hosting model.
72+
73+
For more information about .NET Aspire integrations and the hosting model, see [.NET Aspire integrations overview](../fundamentals/integrations-overview.md).

‎docs/troubleshooting/snippets/hosting-startup-not-supported/MyDbContext.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
using Microsoft.EntityFrameworkCore;
2+
3+
public class MyDbContext : DbContext
4+
{
5+
public MyDbContext(DbContextOptions<MyDbContext> options) : base(options) { }
6+
}

‎docs/troubleshooting/snippets/hosting-startup-not-supported/host-application-builder-after.cs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
using Microsoft.AspNetCore.Builder;
2+
using Microsoft.Extensions.Hosting;
3+
4+
// Example of modern hosting pattern that works with .NET Aspire
5+
public class ModernHostingExample
6+
{
7+
public static void ConfigureServices()
8+
{
9+
// Program.cs equivalent
10+
var builder = WebApplication.CreateBuilder();
11+
12+
// Add service defaults first
13+
// builder.AddServiceDefaults();
14+
15+
// Now you can use Aspire integrations
16+
// builder.AddNpgsqlDbContext<MyDbContext>("postgres");
17+
18+
var app = builder.Build();
19+
20+
// app.MapDefaultEndpoints();
21+
// app.Run();
22+
}
23+
}

‎docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-before.cs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
using Microsoft.AspNetCore.Hosting;
2+
using Microsoft.EntityFrameworkCore;
3+
using Microsoft.Extensions.DependencyInjection;
4+
5+
// MyDatabaseStartup.cs
6+
public class MyDatabaseStartup : IHostingStartup
7+
{
8+
public void Configure(IWebHostBuilder builder)
9+
{
10+
builder.ConfigureServices(services =>
11+
{
12+
// This won't work with Aspire integrations
13+
services.AddDbContext<MyDbContext>(options =>
14+
options.UseNpgsql("Host=localhost;Database=mydb;Username=user;Password=password"));
15+
});
16+
}
17+
}

‎docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-not-supported.csproj‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<TargetFramework>net8.0</TargetFramework>
5+
<ImplicitUsings>enable</ImplicitUsings>
6+
<Nullable>enable</Nullable>
7+
<!-- This is just a snippet project, not meant to be executed -->
8+
<OutputType>Library</OutputType>
9+
</PropertyGroup>
10+
11+
<ItemGroup>
12+
<FrameworkReference Include="Microsoft.AspNetCore.App" />
13+
<PackageReference Include="Microsoft.AspNetCore.Hosting.Abstractions" Version="2.2.0" />
14+
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.11" />
15+
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.11" />
16+
</ItemGroup>
17+
18+
</Project>

0 commit comments

Comments
 (0)