Blazor: I campi pubblici di sola lettura RenderTreeFrame sono diventati proprietà

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

Questa modifica non influisce su molti sviluppatori perché:

• Qualsiasi app o libreria che semplicemente usa file .razor (o anche chiamate manuali RenderTreeBuilder) per definire i propri componenti non farebbe riferimento direttamente a tale tipo.
• Il RenderTreeFrame tipo 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 facendo riferimento diretto a RenderTreeFrame, questa modifica causa un'interruzione binaria ma non un'interruzione del codice sorgente. Ovvero, il codice sorgente esistente compilerà e si comporterà correttamente. Si verificherà un problema solo se si compila per un framework .NET Core 3.x e quindi si eseguono quei file binari su .NET 5 o un framework successivo.

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

Versione introdotta

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 è stata necessaria per implementare miglioramenti delle prestazioni ad alto impatto nel Razor rendering dei componenti in ASP.NET Core 5.0. Vengono mantenuti gli stessi livelli di sicurezza e incapsulamento.

Azione consigliata

La maggior parte Blazor degli sviluppatori 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 sviluppi:

• Se si utilizza un'app con ASP.NET Core 3.x o si esegue un aggiornamento alla versione 5.0 RC1 o successiva, non è necessario apportare modifiche al 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 vuole supportare solo ASP.NET Core 5.0 RC1 o versione successiva, non è necessaria alcuna azione. Assicurati che il file di progetto dichiari un valore di <TargetFramework> pari a net5.0 o una versione successiva.
• Una libreria e vuole supportare sia ASP.NET Core 3.x che 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 componenti .razor. In questo caso, non è necessaria alcuna azione.
  • Tuttavia, se la tua libreria esegue questa operazione, sarà necessario utilizzare il multi-targeting 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>.

    • Usate un riferimento al pacchetto condizionale Microsoft.AspNetCore.Components per tenere conto di entrambe le versioni che desiderate supportare. Per 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.

Le API interessate

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame