Blazor: RenderTreeFrame readonly publika fält har blivit egenskaper

I ASP.NET Core 3.0 och 3.1 exponerade structen RenderTreeFrame olika readonly public fält, inklusive FrameType, Sequenceoch andra. I ASP.NET Core 5.0 RC1 och senare versioner ändrades alla readonly public-fält till readonly public-egenskaper.

Den här ändringen påverkar inte många utvecklare eftersom:

• Appar eller bibliotek som helt enkelt använder .razor filer (eller till och med manuella RenderTreeBuilder anrop) för att definiera dess komponenter refererar inte direkt till den här typen.
• Själva RenderTreeFrame typen betraktas som en implementeringsinformation som inte är avsedd att användas utanför ramverket. ASP.NET Core 3.0 och senare innehåller en analysator som utfärdar kompilatorvarningar om typen används direkt.
• Även om du refererar RenderTreeFrame direkt är den här ändringen binärbrytande men inte källbrytande. Den befintliga källkoden kompileras och fungerar som den ska. Du får bara problem om du kompilerar mot ett .NET Core 3.x-ramverk och sedan kör dessa binärfiler mot .NET 5 eller ett senare ramverk.

För diskussion, se GitHub-ärende dotnet/aspnetcore#25727.

Version lanserad

5.0 RC1

Gammalt beteende

Offentliga medlemmar i RenderTreeFrame definieras som fält. Till exempel renderTreeFrame.Sequence och renderTreeFrame.ElementName.

Nytt beteende

Offentliga medlemmar på RenderTreeFrame definieras som egenskaper med samma namn som tidigare. Till exempel renderTreeFrame.Sequence och renderTreeFrame.ElementName.

Om äldre förkompilerad kod inte har omkompilerats sedan den här ändringen kan det utlösa ett undantag som liknar MissingFieldException: Fältet hittades inte: "Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.FrameType".

Orsak till ändring

Den här ändringen var nödvändig för att implementera prestandaförbättringar med hög effekt i Razor-komponentrendering i ASP.NET Core 5.0. Samma säkerhets- och inkapslingsnivåer bibehålls.

Rekommenderad åtgärd

De flesta Blazor-utvecklare påverkas inte av den här ändringen. Ändringen är mer sannolikt att påverka biblioteks- och paketförfattare, men bara i sällsynta fall. Mer specifikt om du utvecklar:

• En app och med ASP.NET Core 3.x eller uppgradering till 5.0 RC1 eller senare behöver du inte ändra din egen kod. Men om du är beroende av ett bibliotek som har uppgraderats för att ta hänsyn till den här ändringen måste du uppdatera till en nyare version av biblioteket.
• Ett bibliotek och vill endast stödja ASP.NET Core 5.0 RC1 eller senare krävs ingen åtgärd. Se bara till att projektfilen deklarerar ett <TargetFramework> värde för net5.0 eller en senare version.
• Om du har ett bibliotek och vill stödja både ASP.NET Core 3.x och 5.0, avgör om din kod läser några RenderTreeFrame medlemmar. Du kan till exempel utvärdera someRenderTreeFrame.FrameType.
  • De flesta bibliotek kommer inte att läsa RenderTreeFrame medlemmar, inklusive bibliotek som innehåller .razor komponenter. I det här fallet krävs ingen åtgärd.
  • Men om biblioteket gör det måste du ha flera mål för att stödja både netstandard2.1 och net5.0. Tillämpa följande ändringar i projektfilen:

    • Ersätt det befintliga <TargetFramework> elementet med <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks>.

    • Använd en referens för villkorsstyrda Microsoft.AspNetCore.Components paket för att ta hänsyn till båda versionerna som du vill stödja. Till exempel:

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

Mer information finns i den här diff showing how @jsakamoto already upgraded the Toolbelt.Blazor.HeadElement library.

Berörda API:er

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame