diff --git a/docs/fundamentals/integrations-overview.md b/docs/fundamentals/integrations-overview.md index e2d6b255b8..f9299dc629 100644 --- a/docs/fundamentals/integrations-overview.md +++ b/docs/fundamentals/integrations-overview.md @@ -33,6 +33,9 @@ Client integrations wire up client libraries to [dependency injection (DI)](/dot These packages configure existing client libraries to connect to hosting integrations. They extend the 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. +> [!IMPORTANT] +> .NET Aspire integrations require and are **not compatible** with `HostingStartup` implementations, which only provide access to . 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. + For more information on creating a custom client integration, see [Create custom .NET Aspire client integrations](../extensibility/custom-client-integration.md). ### Relationship between hosting and client integrations diff --git a/docs/toc.yml b/docs/toc.yml index 1f5d459171..f1cfc4b031 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -490,6 +490,9 @@ items: - name: Allow unsecure transport displayName: unsecure transport,http,non-tls href: troubleshooting/allow-unsecure-transport.md + - name: HostingStartup is not supported + displayName: hosting startup,IWebHostBuilder,IHostApplicationBuilder,migration + href: troubleshooting/hosting-startup-not-supported.md - name: Untrusted localhost certificate href: troubleshooting/untrusted-localhost-certificate.md - name: Unable to install .NET Aspire workload diff --git a/docs/troubleshooting/hosting-startup-not-supported.md b/docs/troubleshooting/hosting-startup-not-supported.md new file mode 100644 index 0000000000..f29bc60355 --- /dev/null +++ b/docs/troubleshooting/hosting-startup-not-supported.md @@ -0,0 +1,73 @@ +--- +title: HostingStartup is not supported with .NET Aspire integrations +description: Learn how to migrate from HostingStartup to the IHostApplicationBuilder pattern for use with .NET Aspire integrations. +ms.date: 08/04/2025 +ai-usage: ai-generated +--- + +# HostingStartup is not supported with .NET Aspire integrations + +.NET Aspire integrations require the use of , but `HostingStartup` only provides access to . This fundamental incompatibility means that you can't configure .NET Aspire integrations from within a `HostingStartup` implementation. + +## Symptoms + +When attempting to use .NET Aspire integrations within a HostingStartup implementation, you might encounter: + +- **Compilation errors**: Aspire integration extension methods like `AddNpgsqlDbContext` or `AddRedis` are not available on `IWebHostBuilder`. +- **Runtime configuration issues**: Even if you access the underlying services, the proper configuration and service registration won't occur. +- **Missing telemetry and resilience**: Aspire's built-in observability, health checks, and resilience patterns won't be applied. + +## Why HostingStartup doesn't work with .NET Aspire + +.NET Aspire integrations extend to provide: + +- Standardized configuration patterns. +- Built-in health checks. +- Telemetry and observability. +- Resilience patterns. +- Service discovery integration. + +The `HostingStartup` feature was designed for the older ASP.NET Core hosting model and only provides access to , which doesn't include these modern hosting capabilities. + +## Migrating from HostingStartup + +The `HostingStartup` feature represents an older ASP.NET Core hosting model that predates the modern pattern that .NET Aspire requires. Migration is necessary to leverage .NET Aspire's integrations and modern hosting capabilities. + +### Understanding the API changes + +The fundamental difference lies in the hosting abstractions: + +**Before (HostingStartup pattern):** + +:::code language="csharp" source="snippets/hosting-startup-not-supported/hosting-startup-before.cs"::: + +**After (Modern hosting pattern):** + +:::code language="csharp" source="snippets/hosting-startup-not-supported/host-application-builder-after.cs"::: + +### Key conceptual changes + +When migrating from `HostingStartup` to the modern hosting model, you're moving between these approaches: + +| Legacy pattern | Modern pattern | Benefit | +|---|---|---| +| `IWebHostBuilder` | `IHostApplicationBuilder` | Access to modern hosting features and .NET Aspire integrations. | +| Separate startup classes | Program.cs configuration | Service configuration moves directly into the application's entry point for better clarity and debugging. | +| Manual service registration | Integration packages | .NET Aspire integrations handle service registration, configuration, health checks, and telemetry automatically. | + +### Migration resources + +For detailed migration guidance, see: + +- [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 +- [David Fowl's ASP.NET Core 6.0 migration guide](https://gist.github.com/davidfowl/0e0372c3c1d895c3ce195ba983b1e03d) - Provides practical migration patterns and examples + +## Additional considerations + +- **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). + +- **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. + +- **Testing**: .NET Aspire provides [testing capabilities](../testing/overview.md) that work with the new hosting model. + +For more information about .NET Aspire integrations and the hosting model, see [.NET Aspire integrations overview](../fundamentals/integrations-overview.md). diff --git a/docs/troubleshooting/snippets/hosting-startup-not-supported/MyDbContext.cs b/docs/troubleshooting/snippets/hosting-startup-not-supported/MyDbContext.cs new file mode 100644 index 0000000000..28b85a9112 --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/MyDbContext.cs @@ -0,0 +1,6 @@ +using Microsoft.EntityFrameworkCore; + +public class MyDbContext : DbContext +{ + public MyDbContext(DbContextOptions options) : base(options) { } +} \ No newline at end of file diff --git a/docs/troubleshooting/snippets/hosting-startup-not-supported/host-application-builder-after.cs b/docs/troubleshooting/snippets/hosting-startup-not-supported/host-application-builder-after.cs new file mode 100644 index 0000000000..4caff24eff --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/host-application-builder-after.cs @@ -0,0 +1,23 @@ +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.Hosting; + +// Example of modern hosting pattern that works with .NET Aspire +public class ModernHostingExample +{ + public static void ConfigureServices() + { + // Program.cs equivalent + var builder = WebApplication.CreateBuilder(); + + // Add service defaults first + // builder.AddServiceDefaults(); + + // Now you can use Aspire integrations + // builder.AddNpgsqlDbContext("postgres"); + + var app = builder.Build(); + + // app.MapDefaultEndpoints(); + // app.Run(); + } +} \ No newline at end of file diff --git a/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-before.cs b/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-before.cs new file mode 100644 index 0000000000..0bd0a81263 --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-before.cs @@ -0,0 +1,17 @@ +using Microsoft.AspNetCore.Hosting; +using Microsoft.EntityFrameworkCore; +using Microsoft.Extensions.DependencyInjection; + +// MyDatabaseStartup.cs +public class MyDatabaseStartup : IHostingStartup +{ + public void Configure(IWebHostBuilder builder) + { + builder.ConfigureServices(services => + { + // This won't work with Aspire integrations + services.AddDbContext(options => + options.UseNpgsql("Host=localhost;Database=mydb;Username=user;Password=password")); + }); + } +} \ No newline at end of file diff --git a/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-not-supported.csproj b/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-not-supported.csproj new file mode 100644 index 0000000000..9fa417ff9c --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-not-supported.csproj @@ -0,0 +1,18 @@ + + + + net8.0 + enable + enable + + Library + + + + + + + + + + \ No newline at end of file