Compile time discovery of SSR pages/endpoints for Blazor

[javiercn]

• We need to have a proper mechanism for discovering endpoints.
• We need:
  • A way to provide entry point for the app.
  • Support for multiple routers.
  • A way to configure which pages are part of the app (Ability to add/remove endpoints beyond our default discovery).

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[javiercn]

Initial design in the comment below.

Disclaimer alert, the explanation/design is very extensive as it goes into a lot of detail about the different set of scenarios as well as how this works in ASP.NET and why.

The actual implementation of the design is straightforward and contains examples for how it applies to different scenarios.

[javiercn]

Blazor apps discovery

Discovery is the process for which we identify what elements are part of an application so that we can configure the system appropriately.

Context

Discovery has been part of ASP.NET since the times of MVC.

In old ASP.NET, discovery was a concept that was "hidden" to the user, it was considered an implementation detail.

The frameworks used reflection during application startup to find the user defined components (controllers, pages, etc.) and create the appropriate handlers to deal with requests.

The entry point was the entry point assembly for the app and was not configurable.

Discovery in ASP.NET and Blazor

In ASP.NET Core, discovery is present inside MVC and Razor Pages through the concept of Application Parts, and extends to any concept/primitive that the user defines for the app.

In Blazor, discovery is limited to finding pages and is handled by the Router component internally, which is responsible for scanning the assemblies and searching for pages to collect the list of routes.

There are three characteristics about discovery that we have learnt over time are desirable:

• The ability to specify the root for discovery:
  • In ASP.NET Core this is done in the ApplicationPartManager
  • In Blazor this is done by defining the root assembly to scan over when passing parameters to the router.
• The ability to tweak the results from discovery:
  • In ASP.NET Core this is done in the ApplicationPartManager by adding or removing parts and/or features.
  • In Blazor this is done by defining additional assemblies to scan, besides that, no configuration/tweaking is possible.
    • In theory you can customize results at the type level by creating your own Assembly implementation and overriding some of the properties/members.
• The ability to update the results:
  • This is achieved in ASP.NET Core via EndpointDataSource suporting updates.
  • This is achieved in Blazor by passing new parameters to the router, which triggers the component to re-scan the list of assemblies.
  • The main reason this is important is to support features like:
    • "hot reload".
    • "dynamically loaded assemblies".

General discovery flow

• Define the entry point for discovery

  • Find an assembly to use as the root, like:
    • The entry point assembly
    • The caller assembly
    • An explicit assembly
  • Use a type to specify the assembly to use
    • Provided explicitly through an API call.

• Define a mechanism to walk though other parts of the app:

  • Assembly references.
  • Other mechanism.
    • Assembly level attributes that you use to find other related assemblies.

• Define a mechanism to identify the primitives that you want to get from that assembly

  • Assembly level attributes (to find pages, for example)
  • Assembly scanning to identify the types that you care about.

Sketch of the scenarios for discovery with Blazor united

Let's take a look at a rough sketch of the different scenarios with Blazor united in the picture. These scenarios are not meant to work as they are lacking some of the potential concepts needed to make them work.

Some goals to take into account:

• APIs are not exclusive to United. Existing Blazor Server and Webassembly apps can be considered a special flavor of United, so we want the APIs to enhance those experiences too.
• United apps should be hostable alongside pure webassembly apps.

For each scenario we need to ask ourselves three questions:

• What is the entry point for discovery in this case?
• How do we configure the exact set of endpoints in this case?
• How does it work with more than one than one instance defined in the process?

01 - Single Blazor united app (single project only SSR)

flowchart TD
subgraph Application
net8.0
end

Loading

app.AddRazorComponents();

app.MapRazorComponents();

02 - Single Blazor united app (single project with server components)

flowchart TD
subgraph Application
net8.0
end

Loading

app.AddRazorComponents()
    .AddServerComponents();

app.MapRazorComponents()
    .WithServerComponents();

03 - Single Blazor united app (single project with webassembly components)

flowchart TD
subgraph Application
net8.0
net8.0-browser
end

Loading

app.AddRazorComponents()
    .AddWebassemblyComponents();

app.MapRazorComponents()
    .WithWebassemblyComponents();

04 - Single Blazor united app (single project with server and webassembly components)

flowchart TD
subgraph Application
net8.0
net8.0-browser
end

Loading

app.AddRazorComponents()
    .AddServerComponents()
    .AddWebassemblyComponents();

app.MapRazorComponents()
    .WithServerComponents()
    .WithWebassemblyComponents();

05 - Single Blazor united app (from referenced project)

For the sake of conciseness this does not cover server variants as they are orthogonal.

flowchart TD
subgraph WebHost
net8.0host["net8.0"]
end
subgraph Application
net8.0app["net8.0"]
net8.0-browser
end
WebHost-->Application

Loading

app.AddRazorComponents()
    .AddWebassemblyComponents();

app.MapRazorComponents()
    .WithWebassemblyComponents();

• What is the entry point for discovery in this case?
• How do we configure what pages are part of the app?

06 - Multiple Blazor united apps (single project)

flowchart TD
subgraph Application
net8.0
net8.0-browser
end

Loading

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseRouting();

    first.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents();
    });
});

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents();
    });
});

07 - Multiple Blazor webassembly apps with prerendering

flowchart TD
subgraph WebHost
net8.0host["net8.0"]
end
subgraph FirstApp
app1net8.0["net8.0"]
app1net8.0-browser["net8.0-browser"]
end
subgraph SecondApp
app2net8.0["net8.0"]
app2net8.0-browser["net8.0-browser"]
end
WebHost-->FirstApp
WebHost-->SecondApp

Loading

Today

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseBlazorFrameworkFiles("/FirstApp");
    first.UseStaticFiles();

    first.UseRouting();
    first.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapFallbackToRazorPage("FirstApp/{*path:nonfile}", "/_Host.cshtml");
    });
});

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseBlazorFrameworkFiles("/SecondApp");
    second.UseStaticFiles();

    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapFallbackToRazorPage("SecondApp/{*path:nonfile}", "/_Host.cshtml");
    });
});

net8.0

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseStaticFiles();

    first.UseRouting();
    first.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorComponents()
          .WithWebassemblyComponents()
          .WithRazorPageHost("/Host.cshtml");
    });
});

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseStaticFiles();

    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorComponents()
          .WithWebassemblyComponents()            
          .WithRazorPageHost("/Host.cshtml");
    });
});

08 - Multiple Blazor server apps with prerendering

flowchart TD
subgraph Application
net8.0
end

Loading

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseRouting();

    first.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents()
          .WithServerComponents()
          .WithRazorPageHost("/Host1.cshtml");
    });
});


app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapComponentHub()
            .WithServerComponents()
            .WithRazorPageHost("/Host2.cshtml");;
    });
});

09 - Blazor Webassembly apps with blazor united app

flowchart TD
subgraph WebHost ["Application (United & Host)"]
net8.0host["net8.0"]
net8.0browserhost["net8.0-browser"]
end
subgraph Application ["Application (Wasm)"]
net8.0app["net8.0"]
net8.0-browser
end
WebHost-->Application

Loading

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseRouting();

    first.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents();
    });
});


app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents()
          .WithWebassemblyComponents()            
          .WithRazorPageHost("/Host.cshtml");;
    });
});

What are the missing pieces

• Ability to define the entry point.
• Ability to define the strategy for finding the components of the app.
• Ability to define the exact set of endpoints for a given registration.

What are our options

• No entry discovery (not really an option, as it would make defining the app really verbose and cumbersome)
  • Imagine manually mapping each page.
• Discovery based on the entry point assembly
  • Will be cumbersome for apps that contain more than one instance (for example multiple webasembly apps or a webassembly + united app) on the same process as by default we will incorrectly include elements of the other app into the page.
• Discovery based on a provided assembly or a type.
  • This allows narrowing the scope for each app in the most accurate way and only requires tweaks in a limited set of scenarios.
  • Providing an assembly to an API is "kind" of ugly, so a type is best in this case.

Desired characteristics for discovery on Blazor apps

• No reflection: This makes the app slower to start, bigger, and less trimmable.
• Hierarchical/Scoped: Discovery should be limited by the assembly reference hierarchy and avoid scanning the entire process.
• Configurable: Discovery should provide the "source" material to configure the system, not the final immutable configuration.

A brief interlude on how discovery works in MVC

• MVC has the concept of ApplicationPartManager.
  • When you call AddMvc, an APM is created that gets the entry point assembly and uses assembly level attributes (RelatedPartAttribute) to identify all the assemblies it needs to scan for "parts" of the application.
  • AddMvc also registers feature providers, which are responsible for interpreting parts and producing a final set of data that is used as the data input for defining specific elements of the platform, like controllers, pages, viewcomponents, etc.
• Parts are an abstraction over the raw reflection layer to enable alternative definitions and help with unit testing and similar concerns.
• Parts implement concrete interfaces to represent specific concerns, for example:
  • AssemblyPart implements IApplicationPartTypeProvider to provide a list of types.
  • CompiledRazorAssemblyPart implements IRazorCompiledItemProvider to provide a list of RazorCompiledItem that are used to find views.
• Parts make it easier to for example, remove entire assemblies from the graph that MVC considers for discovery.
• FeatureProviders allow granular control over the final input for a given feature. For example, feature providers can be used for removing a specific type from the list of controllers/pages/etc, or can be used to consider types that would originally not be considered as controllers.

To give an end to end example of how this works for controllers, the flow is as follows:

• ControllerEndpointFactory -> ControllerActionDescriptorProvider -> DefaultApplicationModelProvider -> ApplicationPartManager.GetFeature<ControllerFeature> -> ControllerFeatureProvider.
• ControllerEndpointFactory defines the final enpoints.
• DefaultControllerActionDescriptorProvider defines the list of action descriptors based on the ApplicationModel.
• DefaultApplicationModelProvider is responsibly for creating a mutable metadata layer that defines the behaviors of the app.
• ApplicationPartManager.GetFeature<ControllerFeature> is responsible for populating a Controller feature with a list of controllers.
• ControllerFeatureProvider is responsible for examining the list of application parts that implement IApplicationPartTypeProvider and selecting controller types out of them. It is the piece responsible for the definition of "what a controller is".

Discovery for components

A system like the one used for MVC provides a lot of flexibility and at the same time introduces a lot of complexity and is not devoid of its own problems.

As part of designing discovery for Blazor applications we want to keep the complexity to a minimum, while still retaining some of the good qualities that discovery in MVC offers and overcome some of the current limitations.

• We do not want discovery to be based on the assembly, as we want to avoid reflection and scanning (ideally).
• We do not want to define "what" a component is based on reflection.
• We do not want to have a split between the elements that are part of the app and what are the final inputs for features (no "part" concept, and potentially no "feature" concept either).
• We still want to have the ability to modify the results of discovery to tweak them as necessary for our app scenarios.
• We still want to have some hierarchical grouping to make it easier to, for example remove entire assemblies from the list of sources for pages.
• We do not want to have a concrete abstraction that determines at runtime what types are pages (a.k.a) no feature provider.

With this in mind, let's look at a concrete design proposal, by looking at how it will work on the different scenarios layed out above:

app.AddRazorComponents();

app.MapRazorComponents<Type>();

• Type is the entry point for discovery, and this can be a root component for your app, like the App component that Webassembly and Server apps already use.
• Nothing changes in service registration because unlike MVC, discovery happens at the point of endpoint definition, not during service registration (this was like this in MVC because we had a feature to register things like controller in DI (AddControllersAsServices)) which we don't want to replicate in Blazor.
• Type is used to identify the root of discovery.
• Type implements an interface IComponentApplicationDiscoveryRoot

  interface IComponentApplicationDiscoveryRoot
  {
    static Dictionary<string, PageGroup> GetPages();
  }
  
  public class PageGroup
  {
    public string Name { get; set; }
    public List<ComponentPage> Pages { get; set; }
  }
  
  public class ComponentPage
  {
    public string Template { get; }
    public Type PageType { get; }
  }

  • We use a type like ComponentFeatures so that we can extend it in the future if we want to include other aspects like JsonSerializationContexts or other source generated elements.
  • We group things by assembly to make it easy to remove some unwanted assemblies from consideration that might be included in an app just because it is referencing another app (dependencies brought in transitively).
  • We populate the information that we need directly into data structures to avoid having to do reflection.
  • GetComponentFeatures always produces a new "graph" that can be mutated to tweak the set of inputs to the app.
  • We can choose to expose the data structure or provide helper methods within ComponentFeatures to perform concrete tasks.
• The implementation for IComponentApplicationDiscoveryRoot is expected to be compile time generated via a source generator or the Razor Compiler. Although initially we will ship a default implementation that does reflection. For example:

  class App : ComponentBase, IComponentApplicationDiscoveryRoot
  {
    ComponentFeatures IComponentApplicationDiscoveryRoot.GetComponentFeatures(){
        return new ComponentFeatures() {
            ComponentPages = new() {
                new PageFeatureGroup(){
                    Name = "App",
                    Pages = new(){
                        new ComponentPage
                        {
                            Template = "/",
                            PageType = typeof(Index)
                        }
                    }
                },
                new PageFeatureGroup(){
                    Name = "Library",
                    Pages = new(){
                        new ComponentPage
                        {
                            Template = "/About",
                            PageType = typeof(About)
                        }
                    }
                }
            }
        }
    }
  }

Lets look at some concrete scenarios:

• Removing the pages from a library that got discovered:

  app.MapRazorComponents<App>(options => options.Pages.Remove("Library"));

• Removing the pages from a webassembly app that got discovered because its referenced for prerendering:

  app.MapRazorComponents<App>(options => options.Pages.Except<WebAssembly.App>())

Benefits

• No reflection: Since we use interfaces + static members.
• No assembly scanning: Since we code generate the data at compile time.
• No dependency graph traversal: Since it is done at compile time.
• Trimmer/linker friendly.
• Performant: Since the information is computed in a way that can be readily consumed.
• Explicit: No need to rely on entry assembly, or similar concepts that easily cause issues.
• Control over the final shape of the app.
• Extensible for future features that want to avoid reflection.
  • We add more static members to IComponentApplicationDiscoveryRoot and we provide a default implementation for the new member.
  • Different source generators can provide different implementations for features in their own files by implementing the member that produces the data.

Scenarios with the proposed implementation

01 - Single Blazor united app (single project only SSR)

flowchart TD
subgraph Application
net8.0
end

Loading

app.AddRazorComponents();

app.MapRazorComponents<App>();

02 - Single Blazor united app (single project with server components)

flowchart TD
subgraph Application
net8.0
end

Loading

app.AddRazorComponents()
    .AddServerComponents();

app.MapRazorComponents()
    .WithServerComponents<App>();

03 - Single Blazor united app (single project with webassembly components)

flowchart TD
subgraph Application
net8.0
net8.0-browser
end

Loading

app.AddRazorComponents()
    .AddWebassemblyComponents();

app.MapRazorComponents<App>()
    .WithWebassemblyComponents();

04 - Single Blazor united app (single project with server and webassembly components)

flowchart TD
subgraph Application
net8.0
net8.0-browser
end

Loading

app.AddRazorComponents()
    .AddServerComponents()
    .AddWebassemblyComponents();

app.MapRazorComponents<App>()
    .WithServerComponents()
    .WithWebassemblyComponents();

05 - Single Blazor united app (from referenced project)

For the sake of conciseness this does not cover server variants as they are orthogonal.

flowchart TD
subgraph WebHost
net8.0host["net8.0"]
end
subgraph Application
net8.0app["net8.0"]
net8.0-browser
end
WebHost-->Application

Loading

app.AddRazorComponents()
    .AddWebassemblyComponents();

app.MapRazorComponents<Library.App>()
    .WithWebassemblyComponents();

06 - Multiple Blazor united apps (single project)

flowchart TD
subgraph Application
net8.0
net8.0-browser
end

Loading

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseRouting();

    first.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents<App>(
            options => FilterPagesForFirstApp(options)
        );
    });
});

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents<App>(
            options => FilterPagesForSecondApp(options)
        );
    });
});

07 - Multiple Blazor webassembly apps with prerendering

flowchart TD
subgraph WebHost
net8.0host["net8.0"]
end
subgraph FirstApp
app1net8.0["net8.0"]
app1net8.0-browser["net8.0-browser"]
end
subgraph SecondApp
app2net8.0["net8.0"]
app2net8.0-browser["net8.0-browser"]
end
WebHost-->FirstApp
WebHost-->SecondApp

Loading

net8.0

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseStaticFiles();

    first.UseRouting();
    first.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorComponents<FirstApp.App>()
          .WithWebassemblyComponents()
          .WithRazorPageHost("/Host.cshtml");
    });
});

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseStaticFiles();

    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorComponents<SecondApp.App>
          .WithWebassemblyComponents()            
          .WithRazorPageHost("/Host.cshtml");
    });
});

08 - Multiple Blazor server apps with prerendering

flowchart TD
subgraph Application
net8.0
end

Loading

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseRouting();

    first.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents<FirstApp.App>()
          .WithServerComponents()
          .WithRazorPageHost("/Host1.cshtml");
    });
});


app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents<SecondApp.App>
            .WithServerComponents()
            .WithRazorPageHost("/Host2.cshtml");;
    });
});

09 - Blazor Webassembly apps with blazor united app

flowchart TD
subgraph WebHost ["Application (United & Host)"]
net8.0host["net8.0"]
net8.0browserhost["net8.0-browser"]
end
subgraph Application ["Application (Wasm)"]
net8.0app["net8.0"]
net8.0-browser
end
WebHost-->Application

Loading

app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/FirstApp"), first =>
{
    first.UseRouting();

    first.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents<App>(
            options => options.Pages.Except<SecondApp.App>())
        );
    });
});


app.MapWhen(ctx => ctx.Request.Path.StartsWithSegments("/SecondApp"), second =>
{
    second.UseRouting();
    second.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorComponents<SecondApp.App>()
          .WithWebassemblyComponents()            
          .WithRazorPageHost("/Host.cshtml");;
    });
});

Appendix A

• Integration with the Blazor Router
  • We do not have to dramatically change the router to take advantage of discovery done in this way.
  • We can scan the provided assembly for a type that implements IComponentApplicationDiscoveryRoot, get the data from there and filter that against the list of assemblies we are given.
  • Ideally we want to update the Blazor router to use the exact same mechanism for defining the set of routes as on the server case.

Appendix B

• Automatic registration for WebAssembly and Server endpoints.
• IComponentApplicationDiscoveryRoot can contain another method or set of properties that indicates whether the app needs to use webassembly or blazor server (if there are components that requested running on wasm or server).
  • Given that, we can automatically configure the endpoints without requiring additional WithWebassemblyComponents or WithServerComponents.

Appendix C

All the examples use a root component, but in reality IComponentApplicationDiscoveryRoot can be implemented by any type, so this design does not force us into having a root component, we could use instead MainLayout if we choose to do so.

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.