From dd761093833289c6fa34633528591c6f08b7e8bf Mon Sep 17 00:00:00 2001 From: Jan Kotas Date: Tue, 5 Sep 2023 10:41:43 -0700 Subject: [PATCH] Add list of recommended replacements for popular reflection-based (#36769) serializers Better instructions for disabling singlewarn --- docs/core/deploying/trimming/incompatibilities.md | 12 +++++++++--- docs/core/deploying/trimming/trim-warnings/il2104.md | 2 +- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/core/deploying/trimming/incompatibilities.md b/docs/core/deploying/trimming/incompatibilities.md index 47545880d3d77..7a23f3d928a1a 100644 --- a/docs/core/deploying/trimming/incompatibilities.md +++ b/docs/core/deploying/trimming/incompatibilities.md @@ -17,18 +17,24 @@ Automatic [COM marshalling](../../../standard/native-interop/cominterop.md) has ## WPF -The Windows Presentation Foundation (WPF) framework makes substantial use of reflection and some features are heavily reliant on run-time code inspection. In .NET 6, it's not possible for trimming analysis to preserve all necessary code for WPF applications. Unfortunately, almost no WPF apps are runnable after trimming, so trimming support for WPF has been disabled in the .NET 6 SDK. +The Windows Presentation Foundation (WPF) framework makes substantial use of reflection and some features are heavily reliant on run-time code inspection. In .NET 6, it's not possible for trimming analysis to preserve all necessary code for WPF applications. Unfortunately, almost no WPF apps are runnable after trimming, so trimming support for WPF is currently disabled in the .NET SDK. See [WPF is not trim-compatible](https://github.com/dotnet/wpf/issues/3811) issue for progress on enabling trimming for WPF. ## Windows Forms -The Windows Forms framework makes minimal use of reflection, but is heavily reliant on built-in COM marshalling. In .NET 6, it has not yet been converted to use ComWrappers. Unfortunately, almost no Windows Forms apps are runnable without built-in COM marshalling, so trimming support for Windows Forms apps has been disabled in the .NET 6 SDK. +The Windows Forms framework makes minimal use of reflection, but is heavily reliant on built-in COM marshalling. Unfortunately, almost no Windows Forms apps are runnable without built-in COM marshalling, so trimming support for Windows Forms apps is disabled in the .NET SDK currently. See [Make WinForms trim compatible](https://github.com/dotnet/winforms/issues/4649) issue for progress on enabling trimming for Windows Forms. ## Reflection-based serializers -Alternative: Reflection-free serializers, like source-generated [System.Text.Json](../../../standard/serialization/system-text-json/source-generation.md). +Alternative: Reflection-free serializers. Many uses of reflection can be made trimming-compatible, as described in [Introduction to trim warnings](fixing-warnings.md). However, serializers tend to have very complex uses of reflection. Many of these uses cannot be made analyzable at build time. Unfortunately, the best option is often to rewrite the system to use source generation instead. +Popular reflection-based serializers and their recommended alternatives: + +- **Newtonsoft.Json**. Recommended alternative: [source generated System.Text.Json](../../../standard/serialization/system-text-json/source-generation.md) +- **System.Configuration.ConfigurationManager**. Recommended alternative: [source generated Microsoft.Extensions.Configuration](https://github.com/dotnet/runtime/issues/44493) +- **System.Runtime.Serialization.Formatters.Binary.BinaryFormatter** Recommended alternative: [Migrate away from BinaryFormatter serialization due to its security and reliability flaws.](../../compatibility/serialization/7.0/binaryformatter-apis-produce-errors.md#recommended-action) + ## Dynamic assembly loading and execution Trimming and dynamic assembly loading is a common problem for systems that support plugins or extensions, usually through APIs like . Trimming relies on seeing all assemblies at build time, so it knows which code is used and cannot be trimmed away. Most plugin systems load third-party code dynamically, so it's not possible for the trimmer to identify what code is needed. diff --git a/docs/core/deploying/trimming/trim-warnings/il2104.md b/docs/core/deploying/trimming/trim-warnings/il2104.md index 43af22c1d5702..dac919edda6a0 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2104.md +++ b/docs/core/deploying/trimming/trim-warnings/il2104.md @@ -11,4 +11,4 @@ f1_keywords: ## Cause -The assembly 'assembly' produced trim analysis warnings in the context of the app. This means the assembly has not been fully annotated for trimming. Consider contacting the library author to request they add trim annotations to the library. To see detailed warnings for this assembly, turn off grouped warnings by passing either `--singlewarn-` ILLink command line option to show detailed warnings for all assemblies, or `--singlewarn- "assembly"` to show detailed warnings for that assembly. For more information on annotating libraries for trimming, see [Prepare .NET libraries for trimming](../prepare-libraries-for-trimming.md). +The assembly 'assembly' produced trim analysis warnings in the context of the app. This means the assembly has not been fully annotated for trimming. Consider contacting the library author to request they add trim annotations to the library. To see detailed warnings, turn off grouped warnings by setting [`false`](../trimming-options.md#show-detailed-warnings) property in your project file. For more information on annotating libraries for trimming, see [Prepare .NET libraries for trimming](../prepare-libraries-for-trimming.md).