Blazor : les champs publics en lecture seule RenderTreeFrame sont devenus des propriétés

Dans ASP.NET Core 3.0 et 3.1, la structure RenderTreeFrame a exposé différents champs readonly public, notamment FrameType, Sequence et d’autres. Dans ASP.NET Core 5.0 RC1 et versions ultérieures, tous les champs readonly public sont passés aux propriétés readonly public.

Ce changement n’affectera pas beaucoup de développeurs, car :

• Toute application ou bibliothèque qui utilise simplement des fichiers .razor (ou même des appels manuels RenderTreeBuilder) pour définir ses composants ne référencerait pas ce type directement.
• Le type RenderTreeFrame lui-même est considéré comme un détail d’implémentation, qui n’est pas destiné à être utilisé en dehors de l’infrastructure. ASP.NET Core 3.0 et versions ultérieures inclut un analyseur qui émet des avertissements du compilateur si le type est utilisé directement.
• Même si vous référencez RenderTreeFrame directement, ce changement est binaire, mais pas cassant la source. Autrement dit, votre code source existant sera compilé et se comportera correctement. Vous ne rencontrerez un problème que si vous effectuez une compilation sur un framework .NET Core 3.x, puis si vous exécutez ces fichiers binaires sur .NET 5 ou une infrastructure ultérieure.

Pour plus d’informations, consultez le problème GitHub dotnet/aspnetcore#25727.

Version introduite

5.0 RC1

Ancien comportement

Les membres publics sur RenderTreeFrame sont définis en tant que champs. Par exemple : renderTreeFrame.Sequence et renderTreeFrame.ElementName.

Nouveau comportement

Les membres publics sur RenderTreeFrame sont définis en tant que propriétés portant les mêmes noms qu’auparavant. Par exemple : renderTreeFrame.Sequence et renderTreeFrame.ElementName.

Si le code précompilé plus ancien n’a pas été recompilé depuis ce changement, il peut lever une exception similaire à MissingFieldException : Champ introuvable : « Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.FrameType ».

Raison du changement

Ce changement était nécessaire pour implémenter des améliorations du niveau de performance à impact élevé dans le rendu des composants Razor dans ASP.NET Core 5.0. Les mêmes niveaux de sécurité et d’encapsulation sont maintenus.

Action recommandée

La plupart des développeurs Blazor ne sont pas affectés par ce changement. Le changement est plus susceptible d’affecter les auteurs de bibliothèque et de package, mais seulement dans de rares cas. Plus précisément, si vous développez :

• Une application et l’utilisation de ASP.NET Core 3.x ou la mise à niveau vers la version 5.0 RC1 ou ultérieure, vous n’avez pas besoin de modifier votre propre code. Toutefois, si vous dépendez d’une bibliothèque qui a été mise à niveau pour tenir compte de ce changement, vous devez effectuer une mise à jour vers une version plus récente de cette bibliothèque.
• Une bibliothèque et ne souhaitent prendre en charge que ASP.NET Core 5.0 RC1 ou version ultérieure, aucune action n’est nécessaire. Assurez-vous simplement que votre fichier projet déclare une valeur <TargetFramework> de net5.0 ou une version ultérieure.
• Une bibliothèque et souhaitez prendre en charge les ASP.NET Core 3.x et 5.0, déterminez si votre code lit des membres RenderTreeFrame. Par exemple, l’évaluation de someRenderTreeFrame.FrameType.
  • La plupart des bibliothèques ne lisent pas les membres RenderTreeFrame, y compris les bibliothèques qui contiennent des composants .razor. Dans ce cas, aucune action n'est nécessaire.
  • Toutefois, si votre bibliothèque effectue cette opération, vous devez effectuer plusieurs ciblages pour prendre en charge à la fois netstandard2.1 et net5.0. Appliquez les changements suivants à votre projet :

    • Remplacez l’élément <TargetFramework> existant par <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks>.

    • Utilisez une référence de package conditionnel Microsoft.AspNetCore.Components pour prendre en compte les deux versions que vous souhaitez prendre en charge. Par exemple :

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

Pour plus d’informations, consultez ce diff showing how @jsakamoto already upgraded the Toolbelt.Blazor.HeadElement library.

API affectées

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame