Freigeben über

Blazor: Schreibgeschützte öffentliche RenderTreeFrame-Felder sind jetzt Eigenschaften

In ASP.NET Core 3.0 und 3.1 hat die RenderTreeFrame Struktur verschiedene readonly public Felder verfügbar gemacht, darunter FrameType, Sequenceund andere. In ASP.NET Core 5.0 RC1 und höheren Versionen wurden alle readonly public Felder in readonly public Eigenschaften geändert.

Diese Änderung wirkt sich nicht auf viele Entwickler aus, da:

  • Jede App oder Bibliothek, die einfach .razor Dateien (oder sogar manuelle RenderTreeBuilder Aufrufe) zum Definieren ihrer Komponenten verwendet, würde nicht direkt auf diesen Typ verweisen.
  • Der RenderTreeFrame-Typ selbst gilt als Implementierungsdetail und ist nicht für die Verwendung außerhalb des Frameworks vorgesehen. ASP.NET Core 3.0 und höher enthält einen Analyzer, der Compilerwarnungen ausgibt, wenn der Typ direkt verwendet wird.
  • Selbst wenn Sie direkt auf RenderTreeFrame verweisen, ist diese Änderung ein binärer Breaking Change, aber kein Breaking Change im Quellcode. Das heißt, Ihr vorhandener Quellcode wird kompiliert und verhält sich ordnungsgemäß. Ein Problem tritt nur auf, wenn Sie gegen ein .NET Core 3.x-Framework kompilieren und dann diese Binärdateien unter .NET 5 oder einer späteren Version ausführen.

Weitere Diskussionen finden Sie im GitHub-Issue dotnet/aspnetcore#25727.

Eingeführte Version

5.0 RC1

Altes Verhalten

Öffentliche Member in RenderTreeFrame werden als Felder definiert. Beispiel: renderTreeFrame.Sequence und renderTreeFrame.ElementName.

Neues Verhalten

Die öffentlichen Mitglieder von RenderTreeFrame werden als Eigenschaften mit denselben Namen wie zuvor definiert. Beispiel: renderTreeFrame.Sequence und renderTreeFrame.ElementName.

Wenn der ältere vorkompilierte Code seit dieser Änderung nicht neu kompiliert wurde, wird möglicherweise eine Ausnahme wie MissingFieldException ausgelöst: Feld nicht gefunden: "Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.FrameType".

Grund für Änderung

Diese Änderung war erforderlich, um Leistungsverbesserungen beim Rendern von Razor-Komponenten in ASP.NET Core 5.0 zu implementieren. Die gleichen Sicherheits- und Kapselungsstufen werden beibehalten.

Die meisten Blazor-Entwickler sind von dieser Änderung nicht betroffen. Es ist wahrscheinlicher, dass die Veränderung Bibliotheks- und Paketautoren betrifft, jedoch nur in seltenen Fällen. Das gibt insbesondere, wenn Sie Folgendes entwickeln:

  • Bei einer App, die ASP.NET Core 3.x verwendet oder auf 5.0 RC1 oder höher aktualisiert wird, müssen Sie Ihren Code nicht ändern. Wenn Sie jedoch von einer Bibliothek abhängen, die für diese Änderung aktualisiert wurde, müssen Sie auf eine neuere Version dieser Bibliothek aktualisieren.
  • Wenn eine Bibliothek nur ASP.NET Core 5.0 RC1 oder höher unterstützen soll, wird keine Aktion benötigt. Stellen Sie einfach sicher, dass Ihre Projektdatei den <TargetFramework>-Wert net5.0 oder eine spätere Version deklariert.
  • Eine Bibliothek und Sie sowohl ASP.NET Core 3.x und 5.0 unterstützen möchten. Dann müssen Sie bestimmen, ob Ihr Code RenderTreeFrame-Member liest. Beispielsweise beim Auswerten von someRenderTreeFrame.FrameType.
    • Die meisten Bibliotheken lesen keine RenderTreeFrame-Member, einschließlich Bibliotheken mit .razor-Komponenten. In diesem Fall ist keine Aktion erforderlich.
    • Wenn Ihre Bibliothek dies jedoch tut, müssen Sie Multi-Targeting verwenden, um sowohl netstandard2.1 als auch net5.0 zu unterstützen. Wenden Sie die folgenden Änderungen in der Projektdatei an:

      • Ersetzen Sie das vorhandene <TargetFramework> Element durch <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks>.

      • Verwenden Sie einen bedingten Microsoft.AspNetCore.Components Paketverweis, um beide Versionen zu berücksichtigen, die Sie unterstützen möchten. Beispiel:

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

Weitere Erläuterungen finden Sie unter diff showing how @jsakamoto already upgraded the Toolbelt.Blazor.HeadElement library.

Betroffene APIs

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame