Blazor: Los campos públicos RenderTreeFrame de solo lectura se han convertido en propiedades

En ASP.NET Core 3.0 y 3.1, la RenderTreeFrame estructura expone varios readonly public campos, incluidos FrameType, Sequencey otros. En ASP.NET Core 5.0 RC1 y versiones posteriores, todos los readonly public campos cambiaron a readonly public propiedades.

Este cambio no afectará a muchos desarrolladores porque:

• Cualquier aplicación o biblioteca que simplemente use .razor archivos (o incluso llamadas manuales RenderTreeBuilder ) para definir sus componentes no haría referencia directamente a este tipo.
• El RenderTreeFrame propio tipo se considera un detalle de implementación, no pensado para su uso fuera del marco. ASP.NET Core 3.0 y versiones posteriores incluye un analizador que emite advertencias del compilador si el tipo se usa directamente.
• Incluso si hace referencia a RenderTreeFrame directamente, este cambio es una ruptura binaria, pero no una ruptura de origen. Es decir, el código fuente existente se compilará y se comportará correctamente. Solo encontrará un problema si se compila en un marco de .NET Core 3.x y, a continuación, ejecuta esos archivos binarios en .NET 5 o en un marco posterior.

Para discusión, consulte el problema de GitHub dotnet/aspnetcore#25727.

Versión introducida

5.0 RC1

Comportamiento anterior

Los miembros públicos en RenderTreeFrame se definen como campos. Por ejemplo, renderTreeFrame.Sequence y renderTreeFrame.ElementName.

Nuevo comportamiento

Los miembros públicos en RenderTreeFrame se definen como propiedades con los mismos nombres que antes. Por ejemplo, renderTreeFrame.Sequence y renderTreeFrame.ElementName.

Si el código precompilado anterior no se ha vuelto a compilar desde este cambio, puede producir una excepción similar a MissingFieldException: Field not found: 'Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.FrameType'.

Motivo del cambio

Este cambio era necesario para implementar mejoras de rendimiento de alto impacto en la representación de componentes de Razor en ASP.NET Core 5.0. Se mantienen los mismos niveles de seguridad y encapsulación.

Acción recomendada

La mayoría de los desarrolladores de Blazor no se ven afectados por este cambio. Es más probable que el cambio afecte a los creadores de bibliotecas y paquetes, pero solo en determinadas ocasiones. En concreto, si se desarrolla:

• Una aplicación y se usa ASP.NET Core 3.x o se actualiza a 5.0 RC1 o una versión posterior, no es necesario cambiar el código propio. Sin embargo, si depende de una biblioteca actualizada para tener en cuenta este cambio, debe actualizar a una versión más reciente de esa biblioteca.
• Una biblioteca y desea admitir solo ASP.NET Core 5.0 RC1 o posterior, no se necesita ninguna acción. Solo tiene que asegurarse de que el archivo del proyecto declara un valor <TargetFramework> de net5.0 o una versión posterior.
• Una biblioteca y quiere admitir ASP.NET Core 3.x y 5.0, determine si el código lee miembros de RenderTreeFrame. Por ejemplo, la evaluación de someRenderTreeFrame.FrameType.
  • La mayoría de las bibliotecas no leerán miembros RenderTreeFrame, incluidas las que contienen componentes de .razor. En este caso, no se necesita ninguna acción.
  • Pero si la biblioteca lo hace, necesitará varios destinos para admitir netstandard2.1 y net5.0. Aplique los siguientes cambios en el archivo del proyecto:

    • Reemplace el elemento existente <TargetFramework> por <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks>.

    • Use una referencia de paquete condicional Microsoft.AspNetCore.Components para tener en cuenta ambas versiones que desee admitir. Por ejemplo:

      <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'" />
      

Para obtener más aclaración, vea este diff showing how @jsakamoto already upgraded the Toolbelt.Blazor.HeadElement library.

Las APIs afectadas

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame