.NET MAUI 中如何为全裁剪（TrimMode=full）应用配置 Feature Switches？

.NET MAUI 中如何为全裁剪（TrimMode=full）应用配置 Feature Switches？

【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui

当你把 .NET MAUI 应用切换到全裁剪（TrimMode=full）或 NativeAOT（PublishAot=true）构建时，MAUI 会在构建阶段自动调整一批"功能开关"（Feature Switches）：一些依赖反射或动态代码的特性被默认关闭，另一些则被强制开启。如果你的应用用到了HybridWebView、[QueryProperty]、SearchHandler.DisplayMemberName或隐式类型转换运算符，就需要在 csproj 中显式声明对应的 MSBuild 属性，并同步调整代码。本文基于 MAUI 仓库中的设计文档 FeatureSwitches.md 和构建目标 Microsoft.Maui.Controls.targets，给出全裁剪应用下 Feature Switches 的配置路径。

配置入口：把 MSBuild 属性写进应用的 csproj

Feature Switches 的控制方式是：把对应的 MSBuild 属性放进应用的项目文件（csproj）中。每个 MSBuild 属性映射到一个AppContext开关（Microsoft.Maui.RuntimeFeature.*），构建时通过RuntimeHostConfigurationOption项写入运行时配置，运行时由 RuntimeFeature.cs 中的属性读取。

docs/design/FeatureSwitches.md中列出的开关与映射关系如下（节选与裁剪相关的条目）：

各 MSBuild 属性到开关的默认值映射定义在Microsoft.Maui.Sdk.Before.targets中（RuntimeFeature.cs 注释中的说明），而TrimMode=full/PublishAot=true下的覆盖逻辑在构建目标_MauiPrepareForILLink中实现。

TrimMode=full 时 MAUI 自动做了什么

在_MauiPrepareForILLink目标里（条件为'$(PublishAot)' == 'true' or '$(TrimMode)' == 'full'），当对应属性未被显式设置时，构建会强制采用以下默认值：

<PropertyGroup Condition="'$(PublishAot)' == 'true' or '$(TrimMode)' == 'full'"> <MauiShellSearchResultsRendererDisplayMemberNameSupported>false</MauiShellSearchResultsRendererDisplayMemberNameSupported> <MauiQueryPropertyAttributeSupport>false</MauiQueryPropertyAttributeSupport> <MauiImplicitCastOperatorsUsageViaReflectionSupport>false</MauiImplicitCastOperatorsUsageViaReflectionSupport> <MauiEnableXamlCBindingWithSourceCompilation>true</MauiEnableXamlCBindingWithSourceCompilation> <MauiHybridWebViewSupported>false</MauiHybridWebViewSupported> ... </PropertyGroup>

也就是说，全裁剪应用默认会关闭：Shell 搜索结果DisplayMemberName、[QueryProperty]、隐式转换运算符反射查找、HybridWebView；强制开启XamlC 对Source绑定的编译。此外：

• MauiEnableIVisualAssemblyScanning的构建默认值为false，自定义/第三方的IVisual类型不会被自动发现注册；
• _EnableMauiAspire在优化构建（Optimize=true）下自动置为false，非优化构建（Debug）下自动置为true；
• _MauiBindingInterceptorsSupport运行时默认就是true，文档明确：全裁剪和 NativeAOT 应用中，必须使用它代替字符串绑定。

在 csproj 中显式配置开关

要覆盖上述默认行为，直接在应用 csproj 中写 MSBuild 属性即可，例如保留 Aspire 集成（文档给出的示例，并标注了风险）：

<PropertyGroup> <_EnableMauiAspire>true</_EnableMauiAspire> </PropertyGroup>

各开关按你的实际功能取舍配置。结合文档说明的典型场景：

• 要用到HybridWebView：设置<MauiHybridWebViewSupported>true</MauiHybridWebViewSupported>。注意它依赖动态 System.Text.Json 序列化，这正是全裁剪下默认关闭的原因。
• 依赖[QueryProperty(...)]接收导航参数：设置<MauiQueryPropertyAttributeSupport>true</MauiQueryPropertyAttributeSupport>；更推荐的做法是改为实现IQueryAttributable接口，保持开关关闭。
• 依赖SearchHandler.DisplayMemberName：设置<MauiShellSearchResultsRendererDisplayMemberNameSupported>true</MauiShellSearchResultsRendererDisplayMemberNameSupported>；替代方案是始终为SearchHandler设置自定义ItemTemplate来定义搜索结果外观。
• 类型转换依赖隐式转换运算符：设置<MauiImplicitCastOperatorsUsageViaReflectionSupport>true</MauiImplicitCastOperatorsUsageViaReflectionSupport>；文档建议优先改为定义自定义TypeConverter并用[TypeConverter(typeof(MyTypeConverter))]挂到类型上，因为TypeConverterAttribute有助于裁剪器在某些场景下获得更好的二进制体积。
• 自定义IVisual类型需要自动注册：设置<MauiEnableIVisualAssemblyScanning>true</MauiEnableIVisualAssemblyScanning>，否则需要自行注册这些类型。

代码适配：关闭反射特性后必须改的写法

_MauiBindingInterceptorsSupport启用时，源码生成器会识别编译形式的SetBinding调用并生成优化绑定。全裁剪应用中要用这种绑定替代字符串绑定：

字符串绑定（全裁剪下应避免）：

label.BindingContext = new PageViewModel { Customer = new CustomerViewModel { Name = "John" } }; label.SetBinding(Label.TextProperty, "Customer.Name");

编译绑定（文档给出的写法）：

label.SetBinding<PageViewModel, string>(Label.TextProperty, static vm => vm.Customer.Name); // or with type inference: label.SetBinding(Label.TextProperty, static (PageViewModel vm) => vm.Customer.Name);

XAML 中的编译绑定：

<Label Text="{Binding Customer.Name}" x:DataType="local:PageViewModel" />

验证与边界

全裁剪配置的验证主要发生在构建期：

1. XamlC Source 编译。MauiEnableXamlCBindingWithSourceCompilation在全裁剪下默认开启后，之前被 XamlC 跳过的、带Source的绑定现在会参与编译——文档提示"部分绑定可能会开始产生构建错误，或开始运行期失败"。成功条件是构建通过，且所有需要编译的绑定都带正确的x:DataType。对不应编译的绑定，按文档写法显式清除数据类型：

   {Binding MyProperty, Source={x:Reference MyTarget}, x:DataType={x:Null}}

2. Aspire 属性的构建警告。在优化构建（Optimize=true）中手动设置_EnableMauiAspire会触发构建警告MA002，提示该属性不应手动设置、且在 Debug 之外使用 Aspire 可能带来生产环境的性能与安全风险。如果你构建时看到 MA002，说明你正在覆盖构建系统的自动配置。

3. 裁剪生效范围。文档说明_EnableMauiAspire=false且启用裁剪时，.NET trimmer 可以消除 MAUI Aspire 相关代码路径，从而减小最终应用体积——这是关闭非必要开关、配合TrimMode=full减小应用体积的目标。

两点边界需要留意：MauiNamescopesSupported在 .NET 10 起默认true以保持完全兼容，关闭它会同时影响FindByName和依赖IReferenceProvider的 MarkupExtension；EnableMauiDiagnostics未显式设置时跟随EnableDiagnostics（默认false），生产构建不需要额外打开诊断。

配置完成后，应用按TrimMode=full发布即可：构建系统会把你在 csproj 中设置的每个 MSBuild 属性写进运行时开关，未被你覆盖的特性则保持上表中的裁剪默认值。开关清单及各特性的禁用后果，参见 FeatureSwitches.md 全文。

【免费下载链接】maui.NET MAUI is the .NET Multi-platform App UI, a framework for building native device applications spanning mobile, tablet, and desktop.项目地址: https://gitcode.com/GitHub_Trending/ma/maui