Blazor RC1 coverage #36053
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,7 +5,7 @@ description: Learn how to control the Intermediate Language (IL) Trimmer when bu | |
| monikerRange: '>= aspnetcore-5.0' | ||
| ms.author: wpickett | ||
| ms.custom: mvc | ||
| ms.date: 09/08/2025 | ||
| uid: blazor/host-and-deploy/configure-trimmer | ||
| --- | ||
| # Configure the Trimmer for ASP.NET Core Blazor | ||
|
|
@@ -42,73 +42,123 @@ For more information, see [Trimming options (.NET documentation)](/dotnet/core/d | |
|
|
||
| ## Failure to preserve types used by a published app | ||
|
There was a problem hiding this comment. @javiercn Can you review the recommendations made in this section for dealing with type preservation for JS interop related scenarios? |
||
|
|
||
| Trimming may have detrimental effects for a published app leading to runtime errors, even in spite of setting the [`<PublishTrimmed>` property](#configuration) to `false` in the project file. In apps that use [reflection](/dotnet/csharp/advanced-topics/reflection-and-attributes/), the IL Trimmer often can't determine the required types for runtime reflection and trims them away or trims away parameter names from methods. This can happen with complex framework types used for JS interop, JSON serialization/deserialization, and other operations. | ||
|
There was a problem hiding this comment.
This doesn't sound right. Setting There was a problem hiding this comment. I'll double check this in the morning and report back. There was a problem hiding this comment. There was a problem hiding this comment. @gaurdrex Can you create an issue for this in the dotnet/aspnetcore repo and share your project with us? There was a problem hiding this comment. @danroth27 ... Isn't this the same as (or at least has the elements of) dotnet/aspnetcore#52947? It's just not There was a problem hiding this comment. ... and @danroth27 ... are we holding this PR past the RC1 release if @javiercn doesn't respond by then? There was a problem hiding this comment.
Right, that's why I thought @javiercn might want to review this content.
Nope, no need to block on this. The content looks fine to me. There was a problem hiding this comment. I just asked because you were calling for his review. I'll react with a patch PR later if he has any changes. ... and I thought Javier would just re-open the existing PU issue on that subject, but I'm still 👂 if you/he want a new issue on There was a problem hiding this comment. We did KeyValuePair because people use that. If get reports for other types, we might choose to add those too. The cost of preserving a type is small compared to the benefit of not having to force people into doing this type of stuff if enough people use the type. |
||
|
|
||
| The IL Trimmer is also unable to react to an app's dynamic behavior at runtime. To ensure the trimmed app works correctly once deployed, test published output frequently while developing. | ||
|
|
||
| Consider the following example that performs JSON deserialization into a <xref:System.Tuple%602> collection (`List<Tuple<string, string>>`). | ||
|
|
||
| `TrimExample.razor`: | ||
|
|
||
| ```razor | ||
| @page "/trim-example" | ||
| @using System.Diagnostics.CodeAnalysis | ||
| @using System.Text.Json | ||
|
|
||
| <h1>Trim Example</h1> | ||
|
|
||
| <ul> | ||
| @foreach (var item in @items) | ||
| { | ||
| <li>@item.Item1, @item.Item2</li> | ||
| } | ||
| </ul> | ||
|
|
||
| @code { | ||
| private List<Tuple<string, string>> items = []; | ||
|
|
||
| [StringSyntax(StringSyntaxAttribute.Json)] | ||
| private const string data = | ||
| """[{"item1":"1:T1","item2":"1:T2"},{"item1":"2:T1","item2":"2:T2"}]"""; | ||
|
|
||
| protected override void OnInitialized() | ||
| { | ||
| JsonSerializerOptions options = new() { PropertyNameCaseInsensitive = true }; | ||
|
|
||
| items = JsonSerializer | ||
| .Deserialize<List<Tuple<string, string>>>(data, options)!; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The preceding component executes normally when the app is run locally and produces the following rendered list: | ||
|
|
||
| > • 1:T1, 1:T2 | ||
| > • 2:T2, 2:T2 | ||
|
|
||
| When the app is published, <xref:System.Tuple%602> is trimmed from the app, even in spite of setting the `<PublishTrimmed>` property to `false` in the project file. Accessing the component throws the following exception: | ||
|
|
||
| > :::no-loc text="crit: Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100]"::: | ||
| > :::no-loc text="Unhandled exception rendering component: ConstructorContainsNullParameterNames, System.Tuple`2[System.String,System.String]"::: | ||
| > :::no-loc text="System.NotSupportedException: ConstructorContainsNullParameterNames, System.Tuple`2[System.String,System.String]"::: | ||
|
|
||
| To address lost types, consider adopting one of the following approaches. | ||
|
|
||
| ### Custom types | ||
|
|
||
| Custom types aren't trimmed by Blazor when an app is published, so we recommend using custom types for JS interop, JSON serialization/deserialization, and other operations that rely on reflection. | ||
|
|
||
| The following modifications create a `StringTuple` type for use by the component. | ||
|
|
||
| `StringTuple.cs`: | ||
|
|
||
| ```csharp | ||
| [method: SetsRequiredMembers] | ||
| public sealed class StringTuple(string item1, string item2) | ||
| { | ||
| public required string Item1 { get; init; } = item1; | ||
| public required string Item2 { get; init; } = item2; | ||
| } | ||
| ``` | ||
|
|
||
| The component is modified to use the `StringTuple` type: | ||
|
|
||
| ```diff | ||
| - private List<Tuple<string, string>> items = []; | ||
| + private List<StringTuple> items = []; | ||
| ``` | ||
|
|
||
| ```diff | ||
| - items = JsonSerializer.Deserialize<List<Tuple<string, string>>>(data, options)!; | ||
| + items = JsonSerializer.Deserialize<List<StringTuple>>(data, options)!; | ||
| ``` | ||
|
|
||
| Because custom types are never trimmed by Blazor when an app is published, the component works as designed after the app is published. | ||
|
|
||
| :::moniker range=">= aspnetcore-10.0" | ||
|
|
||
| If you prefer to use framework types in spite of our recommendation, use either of the following approaches: | ||
|
|
||
| * [Preserve the type as a dynamic dependency](#preserve-the-type-as-a-dynamic-dependency) | ||
| * [Use a Root Descriptor](#use-a-root-descriptor) | ||
|
|
||
| :::moniker-end | ||
|
|
||
| :::moniker range="< aspnetcore-10.0" | ||
|
|
||
| If you prefer to use framework types in spite of our recommendation, [preserve the type as a dynamic dependency](#preserve-the-type-as-a-dynamic-dependency). | ||
|
|
||
| :::moniker-end | ||
|
|
||
| ### Preserve the type as a dynamic dependency | ||
|
|
||
| Create a dynamic dependency to preserve the type with the [`[DynamicDependency]` attribute](xref:System.Diagnostics.CodeAnalysis.DynamicDependencyAttribute). | ||
|
|
||
| If not already present, add an `@using` directive for <xref:System.Diagnostics.CodeAnalysis?displayProperty=fullName>: | ||
|
|
||
| ```razor | ||
| @using System.Diagnostics.CodeAnalysis | ||
| ``` | ||
|
|
||
| Add a [`[DynamicDependency]` attribute](xref:System.Diagnostics.CodeAnalysis.DynamicDependencyAttribute) to preserve the <xref:System.Tuple%602>: | ||
|
|
||
| ```diff | ||
| + [DynamicDependency(DynamicallyAccessedMemberTypes.PublicConstructors, | ||
| + typeof(Tuple<string, string>))] | ||
| private List<Tuple<string, string>> items = []; | ||
| ``` | ||
|
|
||
| :::moniker range=">= aspnetcore-10.0" | ||
|
|
||
| ### Use a Root Descriptor | ||
|
|
||
|
|
@@ -118,10 +168,8 @@ Add an `ILLink.Descriptors.xml` file to the root of the app† with the typ | |
|
|
||
| ```xml | ||
| <linker> | ||
| <assembly fullname="System.Private.CoreLib"> | ||
| <type fullname="System.Tuple`2" preserve="all" /> | ||
| </assembly> | ||
| </linker> | ||
| ``` | ||
|
|
@@ -138,42 +186,21 @@ Add a `TrimmerRootDescriptor` item to the app's project file‡ referencing | |
|
|
||
| ‡The project file is either the project file of the Blazor WebAssembly app or the project file of the `.Client` project of a Blazor Web App (.NET 8 or later). | ||
|
|
||
| :::moniker-end | ||
|
|
||
| :::moniker range="= aspnetcore-8.0" | ||
|
|
||
| ### Workaround in .NET 8 | ||
|
|
||
| As a workaround in .NET 8, you can add the `_ExtraTrimmerArgs` MSBuild property set to `--keep-metadata parametername` in the app's project file to preserve parameter names during trimming: | ||
|
|
||
| ```xml | ||
| <PropertyGroup> | ||
| <_ExtraTrimmerArgs>--keep-metadata parametername</_ExtraTrimmerArgs> | ||
| </PropertyGroup> | ||
| ``` | ||
|
|
||
| :::moniker-end | ||
|
|
||
| ## Additional resources | ||
|
|
||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.