Add 'RenderTreeBuilder.AddComponentParameter()'

[MackinnonBuck]

Background and Motivation

The RenderTreeBuilder class currently has a method AddAttribute(), which is used to add attributes to the current element frame or parameters to the current component frame. There are multiple overloads of the method accepting different attribute values for well-known types (string, int, bool, EventCallback, etc.), as well as a catch-all overload accepting an object. It should be noted that when the relevant frame is a component, the implementation for each overload does the same thing - box the parameter value and add it to a new render tree frame.

This works well for most component parameter types, but consider if a component had a parameter of the following type:

public class Foo
{
    public string Value { get; set; } = string.Empty;
    public static implicit operator string(Foo foo) => foo.Value;
}

We want the AddAttribute(int sequence, string name, object? value) overload to be resolved, but since Foo defines an implicit conversion to string, the AddAttribute(int sequence, string name, string value) overload gets resolved instead. As a result, the framework later tries to set the component parameter of type Foo to a value of type string, and an InvalidCastException is thrown.

Since each AddAttribute() implementation is identical when acting on a component frame, we could introduce an AddComponentParameter(int sequence, string name, object? value) method for component parameters. There is now no ambiguity with which overload to resolve. Also, since the AddAttribute() implementation would end up boxing the provided value anyway, we aren't losing anything by performing the boxing earlier.

Proposed API

namespace Microsoft.AspNetCore.Components.Rendering;

public sealed class RenderTreeBuilder : IDisposable
{
+    public void AddComponentParameter(int sequence, string name, object? value);
}

Usage Examples

This method is primarily intended to be used in code generated by the Razor compiler, but it will still be available to developers if they wish to construct a render tree without Razor.

// 'builder' is a RenderTreeBuilder here
builder.OpenComponent<SurveyPrompt>(0);
builder.AddComponentParameter(1, "Title", "How is Blazor working for you?");
builder.CloseComponent();

Alternative Designs

Alternatively, we could require the Razor compiler to put an (object) cast in front of every component parameter value passed to AddAttribute(). However, this would eliminate the possibility of adding a generic AddComponentParameter<T>() overload in the future that avoids boxing for parameter types.

Risks

No known risks. This is not a breaking change, since AddAttribute() will maintain its existing behavior for component parameter types.

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.

[halter73]

My initial thought is that maybe we should do the (object?) cast in the razor compiler for now, and then add new public API if and when AddComponentParameter<T>() is ready since that could plausibly affect the design of the non-generic API. Would we even need a non-generic version at all then?

It's also seems odd to me that AddComponentParameter and AddAttribute are synonymous, but maybe I just don't understand the blazor lingo well enough.

If we have two APIs that do the exact same thing, but the new one is just a better version of it, it is tempting to obsolete the old one. We haven't done that with our webhosts though, so I understand not wanting to break people, but this is mostly called by compiler-generated code and would be fixed by simply recompiling, right?

[halter73]

API Review Notes:

• Should we do the (object?) cast instead? We could put the (object?) in the compiler, but it's ugly, and eventually we probably want to make the object a T generic parameter anyway. This allows us to not make additional changes to the compiler when we update the runtime to include generic overloads to AddComponentParameter.
• What about the AddComponentParameter name? Is it obvious this is the same as AddAttribute? There seems to be no pushback on the name, and no one has suggested a better alternative.
• What about obsoleting AddAttribute? There was some discussion in the PR about this. The consensus seems to be that it could add unnecessary friction to developers who are calling the existing API today without issue. We can always obsolete later if there's a need.

namespace Microsoft.AspNetCore.Components.Rendering;

public sealed class RenderTreeBuilder : IDisposable
{
+    public void AddComponentParameter(int sequence, string name, object? value);
}

API Approved!