Fields on RenderTreeFrame have become properties

[SteveSandersonMS]

Please use dotnet/aspnetcore#25727 to discuss this change

Fields on RenderTreeFrame have become properties

In ASP.NET Core 3.0 and 3.1, the RenderTreeFrame struct exposed various readonly public fields, including FrameType, Sequence, and others. Starting from ASP.NET Core 5.0 RC1, all of those readonly public fields have changed to readonly public properties.

We don't expect this change to affect many developers because:

• Any application or library that simply uses .razor files (or even manual RenderTreeBuilder calls) to define its components would not be referencing this type directly
• The RenderTreeFrame type itself is regarded as an implementation detail, not intended for use outside the framework. ASP.NET Core 3.0 and later includes an analyzer that issues compiler warnings if the type is being used directly.
• Even if you do reference RenderTreeFrame directly, this change is binary-breaking but not source-breaking. That is, your existing source code will still compile and behave properly. You will only encounter an issue if compiling against the 3.x framework and then running those binaries against the 5.0 RC1 and later framework.

Version introduced

ASP.NET Core 5.0 RC1

Old behavior

Public members on RenderTreeFrame were defined as fields, for example renderTreeFrame.Sequence and renderTreeFrame.ElementName.

New behavior

Public members on RenderTreeFrame are defined as properties with the same names as before, for example renderTreeFrame.Sequence and renderTreeFrame.ElementName.

If older precompiled code has not been recompiled since this change, it may throw an exception similar to MissingFieldException: Field not found: 'Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.FrameType'.

Reason for change

This change was necessary in order to implement some high-impact performance improvements in Blazor component rendering on ASP.NET Core 5.0 while retaining the same level of safety and encapsulation as before.

Recommended action

The vast majority of Blazor developers will not be affected and do not need to take action. This is most likely to affect library/package authors, but still only rarely. Specifically:

• If you are developing an application, and either staying on ASP.NET Core 3.x or upgrading to 5.0 RC1 or later, you don't need to make any changes to your own code.
  • However if you depend on a library that needs to upgrade to account for this change, then you would need to update to a newer version of that library.
• If you are developing a library, and intend to support only ASP.NET Core 5.0 RC1 or later, you don't need to take any action. Just ensure that your csproj declares the TargetFramework value net5.0.
• If you are developing a library, and intend to support both ASP.NET Core 3.x and 5.0, then check whether or not your code attempts to read any of the members of RenderTreeFrame (for example, evaluating someRenderTreeFrame.FrameType).
  • Most libraries will not do that. This includes libraries that contain .razor components. In this case you don't need to take any action.
  • However, if your library does do that, then you will need to use multitargeting to support both netstandard2.1 and net5.0. First, in your csproj, replace the existing <TargetFramework> with <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks>. Then instead of referencing Microsoft.AspNetCore.Components with a fixed version number such as 3.0.0, use a conditional reference to account for both versions you wish to support. For example:

<PackageReference Include="Microsoft.AspNetCore.Components" Version="3.0.0" Condition="'$(TargetFramework)' == 'netstandard2.0'" />
<PackageReference Include="Microsoft.AspNetCore.Components" Version="5.0.0-rc.1.*" Condition="'$(TargetFramework)' != 'netstandard2.0'" />

For further clarification, see this diff showing how @jsakamoto already upgraded his Toolbelt.Blazor.HeadElement library in this way.

Category

ASP.NET

Affected APIs

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame