Blazor: Public-Schreibgeschützte Felder von RenderTreeFrame wurden zu Eigenschaften geändert

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 Aufrufe) verwendet, um ihre Komponenten zu definieren, würde diesen Typ nicht direkt referenzieren.
• Der RenderTreeFrame Typ selbst wird als Implementierungsdetail betrachtet 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.
• Auch wenn Sie direkt darauf verweisen RenderTreeFrame , ist diese Änderung binärbrechend, aber nicht quellbrechend. Das heißt, Ihr vorhandener Quellcode wird kompiliert und verhält sich ordnungsgemäß. Es tritt nur ein Problem auf, wenn Sie gegen ein .NET Core 3.x-Framework kompilieren und diese Binärdateien dann unter einem .NET 5- oder einem neueren Framework ausführen.

Für die Diskussion siehe GitHub-Issue dotnet/aspnetcore#25727.

Eingeführt in Version

5.0 RC1

Altes Verhalten

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

Neues Verhalten

Öffentliche Mitglieder von RenderTreeFrame sind als Eigenschaften definiert, die dieselben Namen wie zuvor haben. 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.

Empfohlene Aktion

Die meisten Blazor Entwickler sind von dieser Änderung nicht betroffen. Die Änderung wirkt sich wahrscheinlicher auf Bibliotheks- und Paketautoren aus, aber nur in seltenen Fällen. Insbesondere, wenn Sie gerade entwickeln:

• Wenn Sie eine App mit ASP.NET Core 3.x verwenden oder auf 5.0 RC1 oder höher aktualisieren, müssen Sie Ihren eigenen 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.
• Eine Bibliothek, die nur ASP.NET Core 5.0 RC1 oder höher unterstützt, erfordert keine Aktion. Stellen Sie einfach sicher, dass die Projektdatei einen <TargetFramework> Wert von net5.0 oder einer späteren Version deklariert.
• Eine Bibliothek, die sowohl ASP.NET Core 3.x als auch 5.0 unterstützen soll, um zu bestimmen, ob Ihr Code Mitglieder liest RenderTreeFrame . Zum Beispiel, Auswertung von someRenderTreeFrame.FrameType.
  • Die meisten Bibliotheken lesen keine RenderTreeFrame-Elemente, einschließlich solcher Bibliotheken, die .razor-Komponenten enthalten. In diesem Fall ist keine Aktion erforderlich.
  • Wenn Ihre Bibliothek dies jedoch tut, müssen Sie mehrere Zielplattformen 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 in diesem diff showing how @jsakamoto already upgraded the Toolbelt.Blazor.HeadElement library.

Betroffene APIs

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame