Add API to System.Web adapters to enable explicitly mapping Blazor pages

[twsouthwick]

Background and Motivation

We created a set of adapters and guidance (https://github.com/dotnet/systemweb-adapters) to simplify the migration process from ASP.NET to ASP.NET Core. As part of this, we have recommended people set up a ASP.NET Core application that will attempt to serve requests and fallback to the original ASP.NET framework application via YARP. This works well for many things, but it fails when trying to use Blazor. This is because currently both Blazor and YARP are fallback endpoints and this conflicts with each other.

See #42003 for an existing issue on dotnet/aspnetcore that is tracking the need for this.

Proposed API

For the dotnet/systemweb-adapters, I have implemented an extension method that will accomplish this need. However, as this is a feature planned for .NET 8, I want to ensure we have identified a few things:

1. The API in the web adapters should be useable for .NET 6 and .NET 7, but provide a way to migrate to the official .NET 8 API
2. We don't want to conflict with the API design for .NET 8

Here is the public API for this that we are currently exposing on the Microsoft.AspNetCore.SystemWebAdapters package:

namespace Microsoft.AspNetCore.Builder;

public static class BlazorEndpointRouteBuilderExtensions
{
+    public static IEndpointConventionBuilder MapBlazorPages(this IEndpointRouteBuilder endpoints, string page);
+    public static IEndpointConventionBuilder MapBlazorPages(this IEndpointRouteBuilder endpoints, string page, params Assembly[] assemblies)
}

Usage Examples

An example usage would be:

app.MapBlazorHub();

// This is the default way to set up Blazor pages
//app.MapFallbackToPage("/_Host");

// Proposed API
app.MapBlazorPages("/_Host");

app.MapReverseProxy();

Risks

• How do we prevent this API from conflicting with an API for .NET 8 that will accomplish a similar thing but still available for down level?

[twsouthwick]

/cc @Tratcher @danroth27 @adityamandaleeka @javiercn

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[Tratcher]

• How do we prevent this API from conflicting with an API for .NET 8 that will accomplish a similar thing but still available for down level?

A) match the name and parameters of the .NET 8 API and then exclude the SystemWeb version for the .NET 8 TFM. This allows a silent swap. Too much magic?
B) Intentionally give it a different name in SystemWeb and then obsolete it for the .NET 8 TFM.

[davidfowl]

These APIs shouldn't be added to the System.Web adapters repository. We can ship docs that users can use for now and add these in .NET 8 in the right place.

[danroth27]

These APIs shouldn't be added to the System.Web adapters repository. We can ship docs that users can use for now and add these in .NET 8 in the right place.

@davidfowl Delivering this support in .NET 8 is certainly the plan. But .NET 8 won't ship for almost a year. To enable incremental migration to Blazor sooner we'd like to deliver this API as part of the System.Web Adapters and then transition users to the .NET 8 API once it is released.

[davidfowl]

Then it would need to be exposed as a flag instead of an API within the System.Web adapters instead of an API

[twsouthwick]

We've decided to just add docs for migration that will include a working snippet instead and point people to the .NET 8 API when available.

@davidfowl out of curiosity what do you mean by "exposed as a flag"?

[davidfowl]

I was just saying that if we wanted to expose this feature in the System.Web.Adapters that we woud not expose it as a top level API call, instead that would be internal and there would be a top level flag that could enable or disable the mapping blazor pages. That would allow us to keep the flag and change the underlying implementation without exposing these APIs from the wrong place.

[mkArtakMSFT]

@davidfowl, @twsouthwick it's not clear whether there is still any work you need from Blazor as part of this issue or not? If not, can you please close this? Thanks!