Clarify the names of the interactive render modes for Blazor and rationalize with the component tag helper

[danroth27]

In .NET 8 we have the following render modes for Blazor components:

• Static: Static server rendering.
• Server: Interactive server rendering using the Blazor Server hosting model. Prerendering is enabled by default but can be disabled.
• WebAssembly: Interactive client rendering using the Blazor WebAssembly hosting model. Prerendering is enabled by default but can be disabled.
• Auto: Interactive client rendering that starts with Server and switches to WebAssembly once the runtime has been downloaded. Prerendering is enabled by default but can be disabled.

We also have the existing component tag helper that defines its own RenderModes enum:

• Static: Static server rendering.
• Server: Interactive server rendering using the Blazor Server hosting model. No prerendering.
• ServerPrerendered: Interactive server rendering using the Blazor Server hosting model with prerendering.
• WebAssembly: Interactive client rendering using the Blazor WebAssembly hosting model. No prerendering.
• WebAssemblyPrerendered: Interactive client rendering using the Blazor WebAssembly hosting model with prerendering.

One problem with the current naming scheme is that "Server" is a bit ambiguous and confusing. Both the Static and Server render modes render from the server, so it's not immediately clear what the "Server" render mode means.

We could clarify this by renaming Server to something more specific, like InteractiveServer. If we do that, we presumably should to rename the other interactive render modes for consistency:

• Server -> InteractiveServer
• WebAssembly -> InteractiveWebAssembly
• Auto -> InteractiveAuto

Note that this also impacts the APIs used to configure and enable these render modes: AddServerComponents() -> AddInteractiveServerComponents(), etc.

The RenderMode enum used by the component tag helper has already shipped. If we change names of the new render modes, then they will be inconsistent with the existing enum. So, we need to decide if we care more about clarity with the new API or consistency with the existing ones. The new names are also more verbose.

[danroth27]

We will also need to evaluate the Razor compiler impact if we decide to make this change.

@chsienki FYI.

[marinasundstrom]

This is a reasonable step towards clearing up the confusion.

Blazor is no longer just about interactive components, although that is the full power of it - with Blazor Web App being server static by default. It is, with lack of a better word, a universal Web component model.

I think there is need for some great docs explaining the different hosting models and render modes from this new perspective which even I find hard to define.

[danroth27]

I think there is need for some great docs explaining the different hosting models and render modes from this new perspective which even I find hard to define.

@marinasundstrom See dotnet/AspNetCore.Docs#30279 for our initial attend to get the new Blazor render modes documented and aligned with our existing concepts. This issue was in part inspired by that doc writing effort.

[chsienki]

We will also need to evaluate the Razor compiler impact if we decide to make this change.

@chsienki FYI.

Thanks for the heads up. I don't think this should impact the compiler; we don't directly rely on the names of the enum, just the underlying interface they represent, so any changes should be transparent to the compiler.

[SteveSandersonMS]

The RenderMode enum used by the component tag helper has already shipped. If we change names of the new render modes, then they will be inconsistent with the existing enum.

True, but not a big issue in my opinion, since the older RenderMode enum is already inconsistent with the existing newer names. For example, it has no equivalent to Auto, and it does have both Server and ServerPrerendered as separate things (whereas the newer schema represents them as a single type with a flag).

Altogether the older RenderMode enum should be decreasing in importance and eventually becomes a back-compat thing. I'm fine with the new type hierarchy being optimized for the way we see things now.

[SteveSandersonMS]

The new names are also more verbose.

I agree that's a real tradeoff. It's obvious that "interactive server mode" is massively clearer than "server mode" for newcomers, so the remaining question is whether it's so verbose that it's actively annoying to more experienced devs. My sense is that it's not annoying at all.

[danroth27]

OK, it sounds like we should move forward with this then.

Altogether the older RenderMode enum should be decreasing in importance and eventually becomes a back-compat thing

I don't think the component tag helper is just for back compat. We have lots of MVC & Razor Page developers that may want to embed Blazor components in their existing apps.

For example, it has no equivalent to Auto

I was actually going to open an issue about the possibility of adding it 😄.

[victor-borges]

Hey all, just chiming in!

A lot of people commented on the naming of the RenderMode enum in the recent ASP.NET Core Community Standup (myself included) and how it feels like it has a confusing meaning.

My suggestion would be to separate interactivity from (pre)rendering, as the two concepts play together but are quite different and are mostly two independent choices that one can make. In my mind, that would imply renaming the RenderMode enum to something like InteractiveMode, with the values:

• None: meaning no interactivity at all, default if not specified, explicitly make the component static and pre-rendered;
• Client: meaning client interactivity, same as the current Blazor WebAssembly render mode;
• Server: meaning server interactivity, same as the current Blazor Server render mode;
• Auto: same as the current Auto render mode;

And then the pre-render flag would also turn into a directive or an enum, that states if the component should be pre-rendered.

Pre-rendered component with server based interactivity:

@interactivemode Server
@prerendered

<h1>My component</h1>

@code {
    // some code
}

Calling a pre-rendered component with client based interactivity:

<Counter @interactivemode="Client" @prerendered />

Component that explicitly sets no interactivity (could also serve as a workaround for enabling interactivity globally in the root component):

@interactivemode None
@* Using prerendered here would be a NOP *@

<h1>My component</h1>

But I don't know if that would be possible due to backwards compatibility or other constraints that I missed, so please take it like a very surface level suggestion.

[gragra33]

@SteveSandersonMS
@danroth27 mentioned the old enum. If you added only @interactivemode None, you could keep the old enums and have the opt-in to static-only rendering using the none. This reduces confusion with a change and would keep backward compatibility with the default behaviour of .Net 7.0 & earlier. No need for changing/depreciating the old tag halper ... just a thought.

[SteveSandersonMS]

Thanks for the suggestions. At this point coming into RC2 we need to avoid compiler-impacting changes, or other changes that would force large amounts of framework API churn, so we're really only considering direct renames of what already exists. We have enough consensus to proceed with InteractiveServer etc, so that remains the plan. But again, thanks for the feedback - at other times we might have acted on it :)

[gragra33]

Thanks for the suggestions.

Totally understand. :)