Blazor: RenderTreeFrame readonly public 欄位已變成屬性

發行項
02/27/2024

在 ASP.NET Core 3.0 和 3.1 中，RenderTreeFrame 結構會公開各種 readonly public 欄位，包括 FrameType、Sequence 和其他欄位。在 ASP.NET Core 5.0 RC1 和更新版本中，所有 readonly public 欄位都會變更為 readonly public 屬性。

這項變更不會影響許多開發人員，因為：

任何只使用 .razor 檔案 (或甚至手動 RenderTreeBuilder 呼叫) 來定義其元件的應用程式或程式庫，都不會直接參考此型別。
RenderTreeFrame 型別本身視為是實作詳細資料，不適用於架構外部。 ASP.NET Core 3.0 和更新版本包含分析器，會在直接使用型別時發出編譯器警告。
即使您直接參考 RenderTreeFrame，這項變更是二進位中斷，但不是來源中斷。也就是說，您現有的原始程式碼會編譯並正常運作。只有在針對 .NET Core 3.x 架構進行編譯，然後針對 .NET 5 或更新版本的架構執行這些二進位時，您才會遇到問題。

如需討論，請參閱 GitHub 問題 dotnet/aspnetcore#25727 (英文)。

導入的版本

5.0 RC1

舊的行為

RenderTreeFrame 上的公用成員會定義為欄位。例如，renderTreeFrame.Sequence 與 renderTreeFrame.ElementName。

新的行為

RenderTreeFrame 上的公用成員會定義為屬性，其名稱與之前相同。例如，renderTreeFrame.Sequence 與 renderTreeFrame.ElementName。

如果較舊的先行編譯程式碼自此變更後尚未重新編譯，它可能會擲回類似 MissingFieldException: Field not found: 'Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame.FrameType' 的例外狀況。

變更原因

這項變更為必要，才能在 ASP.NET Core 5.0 中實作 Razor 元件轉譯的高影響效能改善。保持相同的安全和封裝等級。

建議的動作

大部分 Blazor 開發人員不受這項變更影響。這項變更更有可能影響程式庫和封裝作者，但僅限於罕見情況。具體來說，如果您正在開發：

應用程式，且使用 ASP.NET Core 3.x 或升級至 5.0 RC1 或更新版本，您不需變更自己的程式碼。不過，如果您依賴升級的程式庫來說明這項變更，則必須更新為較新版本的程式庫。
程式庫，且只想支援 ASP.NET Core 5.0 RC1 或更新版本，不需要採取任何動作。請確定您的專案檔宣告 net5.0 的 <TargetFramework> 值或更新版本。
程式庫，且想同時支援 ASP.NET Core 3.x 及 5.0，決定您的程式碼是否讀取任何 RenderTreeFrame 成員。例如，評估 someRenderTreeFrame.FrameType。
- 大部分程式庫都不會讀取 RenderTreeFrame 成員，包括包含 .razor 元件的程式庫。在這種情況下，不需要採取任何動作。
- 不過，如果您的程式庫讀取該成員，您會需要多重鎖定來支援 netstandard2.1 和 net5.0。在您的專案檔中套用下列變更：
  - 以 <TargetFrameworks>netstandard2.0;net5.0</TargetFrameworks> 取代現有 <TargetFramework> 元素。
  - 使用有條件的 Microsoft.AspNetCore.Components 套件參考，說明您想要支援這兩個版本。例如：
```
<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'" />
```

如需進一步釐清，請參閱此 diff showing how @jsakamoto already upgraded the Toolbelt.Blazor.HeadElement library (英文)。

受影響的 API

Microsoft.AspNetCore.Components.RenderTree.RenderTreeFrame

Share via