Blazor Sections API Proposal

[surayya-MS]

Background and Motivation

Related to #28182.
There is a need for a feature that will allow customers to change a part of main layout depending on which page they are on. A solution to achieve that exists and was described in #28182 (comment). Similar solution was implemented as part of #10450. https://github.com/dotnet/aspnetcore/tree/main/src/Components/Components/src/Sections these classes are internal.
We want to make them a part of public API (and change a few things for other potential use cases).

Proposed API

SectionOutlet component that renders content provided by SectionContent with the same SectionId

public sealed class SectionOutlet : IComponent, IDisposable
{
    [Parameter, EditorRequired] public object SectionId { get; set; }
}

public sealed class SectionContent : IComponent, IDisposable
{
    [Parameter, EditorRequired] public object SectionId { get; set; }
    [Parameter] public RenderFragment? ChildContent { get; set; }
{

Usage Examples

Common use case would be to use SectionOutlet component in MainLayout.razor and provide the desired content via SectionContent component in other pages.
This is not the only case. You could use SectionOutlet SectionContent to modify a part of parent component depending on which child components are rendered.

Example:

• Add this code into the default template's MainLayout.razor:

@code{
    internal static object TopbarSection = new();
}

• Add SectionOutlet into the default template's MainLayout.razor:

<div class="top-row px-4">
    <SectionOutlet SectionId="TopbarSection" />
    <a href="https://docs.microsoft.com/aspnet/" target="_blank">About</a>
</div>

• Add SectionContent into Counter.razor:

<SectionContent SectionId="MainLayout.TopbarSection">
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</SectionContent>

You'll get this:

If you don't want to use a static field inMainlayout.razor you could also use a string as SectionId:

<SectionOutlet SectionId="@("topbar")" />

In Counter.razor:

<SectionContent SectionId="@("topbar")">
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</SectionContent>

Alternative Designs

The original design with string Name as an identifier instead of object SectionId.

public sealed class SectionOutlet : IComponent, IDisposable
{
    [Parameter, EditorRequired] public string Name { get; set; }
}

public sealed class SectionContent : IComponent, IDisposable
{
    [Parameter, EditorRequired] public string Name { get; set; }
    [Parameter] public RenderFragment? ChildContent { get; set; }
{

With this design you cannot hide your SectionOutlet. This is useful when you are developing a library and you don't want any accidental content in the user's app to be rendered in library's component.

Risks

Case when SectionId is IEquatable<T> and Equals(object), GetHashCode() not overriden.

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.

[BrennanConroy]

API Review Notes:

• How easy is it to pass objects around in Blazor?
  • You can have a parameter in a child component or inject via a service/using static or Cascading Value
• What's wrong with string Name?
  • Easy to conflict with someone else, e.g. I use "head" and another library uses "head", we'll step on eachother.
  • Can't avoid conflicts with an error since it's not necessarily the users fault and wouldn't be fixable if multiple libraries conflicted. Plus you might want multiple SectionOutlets with the same "name" in a single app
• Namespace? Is .Sections fine instead of the "main" Components namespace?
  • Yes, we think it'll be less commonly used than the "core" components, and other components do use custom namespaces as well, .Web, .Authorization, e.g.

API approved!

namespace Microsoft.AspNetCore.Components.Sections;

+ public sealed class SectionOutlet : IComponent, IDisposable
+ {
+     [Parameter, EditorRequired] public object SectionId { get; set; }

+     // <inheritdoc/>
+     void Attach(RenderHandle renderHandle);

+     // <inheritdoc/>
+     Task SetParametersAsync(ParameterView parameters);

+     // <inheritdoc/>
+     public void Dispose();
+ }

+ public sealed class SectionContent : IComponent, IDisposable
+ {
+     [Parameter, EditorRequired] public object SectionId { get; set; }
+     [Parameter] public RenderFragment? ChildContent { get; set; }

+     // <inheritdoc/>
+     void Attach(RenderHandle renderHandle);

+     // <inheritdoc/>
+     Task SetParametersAsync(ParameterView parameters);

+     // <inheritdoc/>
+     public void Dispose();
+ }

[mkArtakMSFT]

@guardrex can you add docs for this feature based on the description from @surayya-MS ?

[guardrex]

Yes. I'll ping on the (upcoming) docs issue if I get stuck.