Blazor: i campi pubblici renderTreeFrame sono diventati proprietà

  • Articolo

In ASP.NET Core 3.0 e 3.1, lo struct RenderTreeFrame ha esposto vari campi readonly public, tra cui FrameType, Sequence e altri. In ASP.NET Core 5.0 RC1 e versioni successive, tutti i campi readonly public sono stati modificati in proprietà readonly public.

Questa modifica non influirà su molti sviluppatori perché:

  • Qualsiasi app o libreria che usa semplicemente file .razor (o anche chiamate manuali RenderTreeBuilder) per definire i relativi componenti non farà riferimento direttamente a questo tipo.
  • Il tipo RenderTreeFrame stesso è considerato un dettaglio di implementazione, non destinato all'uso al di fuori del framework. ASP.NET Core 3.0 e versioni successive include un analizzatore che genera avvisi del compilatore se il tipo viene usato direttamente.
  • Anche se si fa riferimento a RenderTreeFrame direttamente, questa modifica causa un'interruzione binaria ma non un'interruzione di origine. Ovvero, il codice sorgente esistente compilerà e si comporterà correttamente. Si verificherà un problema solo se la compilazione in un framework .NET Core 3.x e quindi l'esecuzione di tali file binari in .NET 5 o in un framework successivo.

Per informazioni, vedere il problema dotnet/aspnetcore#25727 di GitHub.

Versione con introduzione

5.0 RC1

Comportamento precedente

I membri pubblici in RenderTreeFrame sono definiti come campi. Ad esempio, renderTreeFrame.Sequence e renderTreeFrame.ElementName.

Nuovo comportamento

I membri pubblici in RenderTreeFrame sono definiti come proprietà con gli stessi nomi di prima. Ad esempio, renderTreeFrame.Sequence e renderTreeFrame.ElementName.

Se il codice precompilato precedente non è stato ricompilato dopo questa modifica, potrebbe generare un'eccezione simile a MissingFieldException: Campo non trovato: 'Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.FrameType'.

Motivo della modifica

Questa modifica era necessaria per implementare miglioramenti delle prestazioni ad alto impatto nel rendering dei componenti Razor in ASP.NET Core 5.0. Vengono mantenuti gli stessi livelli di sicurezza e incapsulamento.

La maggior parte degli sviluppatori Blazor non è interessata da questa modifica. È più probabile che la modifica influisca sugli autori di librerie e pacchetti, ma solo in rari casi. In particolare, se si sviluppano:

  • Un'app e l'uso di ASP.NET Core 3.x o l'aggiornamento alla versione 5.0 RC1 o successiva, non è necessario modificare il proprio codice. Tuttavia, se si dipende da una libreria che è stata aggiornata per tenere conto di questa modifica, è necessario eseguire l'aggiornamento a una versione più recente di tale libreria.
  • Una libreria e si vuole supportare solo ASP.NET Core 5.0 RC1 o versione successiva, non è necessaria alcuna azione. Assicurarsi che il file di progetto dichiari un valore <TargetFramework> pari a net5.0 o una versione successiva.
  • Una libreria e si vuole supportare sia ASP.NET Core 3.x e 5.0, determinare se il codice legge i RenderTreeFrame membri. Ad esempio, valutazione di someRenderTreeFrame.FrameType.
    • La maggior parte delle librerie non leggerà i membri RenderTreeFrame, incluse le librerie che contengono .razor componenti. In questo caso, non è necessaria alcuna azione.
    • Tuttavia, se la libreria esegue questa operazione, sarà necessario eseguire il supporto multi target per supportare sia netstandard2.1 che net5.0. Applicare le modifiche seguenti nel file di progetto:

      • Sostituire l'elemento esistente <TargetFramework> con <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks>.

      • Usare un riferimento al pacchetto Microsoft.AspNetCore.Components condizionale per tenere conto di entrambe le versioni che si desidera supportare. Ad esempio:

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

Per ulteriori chiarimenti, vedere questo diff showing how @jsakamoto already upgraded the Toolbelt.Blazor.HeadElement library.

API interessate

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame