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..31ed8eba33 --- /dev/null +++ b/docs/troubleshooting/hosting-startup-not-supported.md @@ -0,0 +1,75 @@ +--- +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 +--- + +# 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. + +## Migration strategies + +### Option 1: Use IHostApplicationBuilder directly (Recommended) + +Instead of using `HostingStartup`, configure your application directly in the `Program.cs` file using the modern hosting pattern: + +**Before (HostingStartup pattern):** + +:::code language="csharp" source="snippets/hosting-startup-not-supported/hosting-startup-before.cs"::: + +**After (IHostApplicationBuilder pattern):** + +:::code language="csharp" source="snippets/hosting-startup-not-supported/host-application-builder-after.cs"::: + +### Option 2: Create configuration extensions + +If you need modular configuration, create extension methods that work with `IHostApplicationBuilder`: + +:::code language="csharp" source="snippets/hosting-startup-not-supported/configuration-extensions.cs"::: + +### Option 3: Use feature flags or configuration-based service registration + +For conditional service registration based on configuration: + +:::code language="csharp" source="snippets/hosting-startup-not-supported/feature-flags-configuration.cs"::: + +## Best practices for modular configuration + +1. **Use configuration-based decisions**: Instead of having separate startup classes, use configuration values to determine which services to register. + +1. **Create extension methods**: Group related service registrations into extension methods on `IHostApplicationBuilder`. + +1. **Leverage service defaults**: Always call `builder.AddServiceDefaults()` to get the full benefits of .NET Aspire's built-in features. + +1. **Use the app host for orchestration**: For development scenarios, use the [.NET Aspire app host](../fundamentals/app-host-overview.md) to manage dependencies and configuration. + +## 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/configuration-extensions.cs b/docs/troubleshooting/snippets/hosting-startup-not-supported/configuration-extensions.cs new file mode 100644 index 0000000000..fb92e7046e --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/configuration-extensions.cs @@ -0,0 +1,25 @@ +// DatabaseConfiguration.cs +public static class DatabaseConfiguration +{ + public static IHostApplicationBuilder AddDatabaseServices( + this IHostApplicationBuilder builder) + { + // Configure your database based on environment or configuration + var connectionName = builder.Configuration["DatabaseProvider"] switch + { + "PostgreSQL" => "postgres", + "SqlServer" => "sqlserver", + _ => throw new InvalidOperationException("Unsupported database provider") + }; + + builder.AddNpgsqlDbContext(connectionName); + + return builder; + } +} + +// Program.cs +var builder = WebApplication.CreateBuilder(args); +builder.AddServiceDefaults(); +builder.AddDatabaseServices(); // Your modular configuration +var app = builder.Build(); \ No newline at end of file diff --git a/docs/troubleshooting/snippets/hosting-startup-not-supported/feature-flags-configuration.cs b/docs/troubleshooting/snippets/hosting-startup-not-supported/feature-flags-configuration.cs new file mode 100644 index 0000000000..c046e653ac --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/feature-flags-configuration.cs @@ -0,0 +1,30 @@ +// Program.cs +var builder = WebApplication.CreateBuilder(args); +builder.AddServiceDefaults(); + +// Conditional service registration based on configuration +var databaseProvider = builder.Configuration["DatabaseProvider"]; +switch (databaseProvider) +{ + case "PostgreSQL": + builder.AddNpgsqlDbContext("postgres"); + break; + case "SqlServer": + builder.AddSqlServerDbContext("sqlserver"); + break; + default: + throw new InvalidOperationException($"Unsupported database provider: {databaseProvider}"); +} + +var telemetryProvider = builder.Configuration["TelemetryProvider"]; +switch (telemetryProvider) +{ + case "ApplicationInsights": + builder.Services.AddApplicationInsightsTelemetry(); + break; + case "OpenTelemetry": + // OpenTelemetry is included with service defaults + break; +} + +var app = builder.Build(); \ 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..d6dec79583 --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/host-application-builder-after.cs @@ -0,0 +1,13 @@ +// Program.cs +var builder = WebApplication.CreateBuilder(args); + +// 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..5c85700157 --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-before.cs @@ -0,0 +1,13 @@ +// 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(connectionString)); + }); + } +} \ 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..2d4f5b89cd --- /dev/null +++ b/docs/troubleshooting/snippets/hosting-startup-not-supported/hosting-startup-not-supported.csproj @@ -0,0 +1,9 @@ + + + + net9.0 + enable + enable + + + \ No newline at end of file