The following MSBuild properties and items influence the behavior of trimmed self-contained deployments. Some of the options mention
ILLink, which is the name of the underlying tool that implements trimming. For more information about the underlying tool, see the Trimmer documentation.
PublishTrimmed was introduced in .NET Core 3.0. The other options are available only in .NET 5 and later versions.
Enable trimming during publish. This also turns off trim-incompatible features and enables trim analysis during build.
If you specify trimming as enabled from the command line, your debugging experience will differ and you may encounter additional bugs in the final product.
Place this setting in the project file to ensure that the setting applies during
dotnet build, not just
This setting enables trimming and will trim all assemblies by default. In .NET 6, only assemblies that opted-in
to trimming via
[AssemblyMetadata("IsTrimmable", "True")] would be trimmed by default. You can return to the
previous behavior by using
This setting trims any assemblies that have been configured for trimming. With
Microsoft.NET.Sdk in .NET 6, this includes any assemblies with
[AssemblyMetadata("IsTrimmable", "True")], which is the case for the .NET runtime assemblies. In .NET 5, assemblies from the netcoreapp runtime pack are configured for trimming via
<IsTrimmable> MSBuild metadata. Other SDKs may define different defaults.
TrimMode property to set the trimming granularity to either
full. The default setting for console apps (and, starting in .NET 8, Web SDK apps) is
To only trim assemblies that have opted-in to trimming, set the property to
If you change the trim mode to
partial, you can opt-in individual assemblies to trimming by using a
<TrimmableAssembly> MSBuild item.
<ItemGroup> <TrimmableAssembly Include="MyAssembly" /> </ItemGroup>
This is equivalent to setting
[AssemblyMetadata("IsTrimmable", "True")] when building the assembly.
The following granularity settings control how aggressively unused IL is discarded. This can be set as a property affecting all trimmer input assemblies, or as metadata on an individual assembly, which overrides the property setting.
Enable member-level trimming, which removes unused members from types. This is the default in .NET 6+.
Enable assembly-level trimming, which keeps an entire assembly if any part of it is used (in a statically understood way).
<IsTrimmable>true</IsTrimmable> metadata but no explicit
TrimMode will use the global
TrimMode. The default
link in .NET 6+, and
copyused in previous versions.
Trim additional assemblies
In .NET 6+,
PublishTrimmed trims assemblies with the following assembly-level attribute:
The framework libraries have this attribute. In .NET 6+, you can also opt in to trimming for a library without this attribute, specifying the assembly by name (without the
Trimming settings for individual assemblies
When publishing a trimmed app, the SDK computes an
ManagedAssemblyToLink that represents the set of files to be processed for trimming.
ManagedAssemblyToLink may have metadata that controls the trimming behavior per assembly. To set this metadata, create a target that runs before the built-in
PrepareForILLink target. The following example shows how to enable trimming of
<Target Name="ConfigureTrimming" BeforeTargets="PrepareForILLink"> <ItemGroup> <ManagedAssemblyToLink Condition="'%(Filename)' == 'MyAssembly'"> <IsTrimmable>true</IsTrimmable> </ManagedAssemblyToLink> </ItemGroup> </Target>
You can also use this to override the trimming behavior specified by the library author, by setting
<IsTrimmable>false</IsTrimmable> for an assembly with
Do not add or remove items to/from
ManagedAssemblyToLink, because the SDK computes this set during publish and expects it not to change. The supported metadata is:
Control whether the given assembly is trimmed.
Control the trimming granularity of this assembly. This takes precedence over the global
TrimModeon an assembly implies
Control whether to show single warnings for this assembly.
If an assembly is not trimmed it is considered "rooted", which means that it and all of its statically understood dependencies will be kept. Additional assemblies may be "rooted" by name (without the
<ItemGroup> <TrimmerRootAssembly Include="MyAssembly" /> </ItemGroup>
Another way to specify roots for analysis is using an XML file that uses the trimmer descriptor format. This lets you root specific members instead of a whole assembly.
<ItemGroup> <TrimmerRootDescriptor Include="MyRoots.xml" /> </ItemGroup>
MyRoots.xml might root a specific method that is dynamically accessed by the application:
<linker> <assembly fullname="MyAssembly"> <type fullname="MyAssembly.MyClass"> <method name="DynamicallyAccessedMethod" /> </type> </assembly> </linker>
Enable trim analysis warnings.
Trimming removes IL that is not statically reachable. Apps that use reflection or other patterns that create dynamic dependencies may be broken by trimming. To warn about such patterns, set
false. This will include warnings about the entire app, including your own code, library code, and framework code.
PublishTrimmed in .NET 6+ also enables a Roslyn analyzer that shows a limited set of analysis warnings. You can also enable or disable the analyzer independently of
Enable a Roslyn analyzer for a subset of trim analysis warnings.
You can suppress individual warning codes using the usual MSBuild properties respected by the toolchain, including
TreatWarningsAsErrors. There is an additional option that controls the ILLink warn-as-error behavior independently:
Don't treat ILLink warnings as errors. This may be useful to avoid turning trim analysis warnings into errors when treating compiler warnings as errors globally.
Show detailed warnings
In .NET 6+, trim analysis produces at most one warning for each assembly that comes from a
PackageReference, indicating that the assembly's internals are not compatible with trimming. You can also show individual warnings for all assemblies:
Show all detailed warnings, instead of collapsing them to a single warning per assembly.
Symbols are usually trimmed to match the trimmed assemblies. You can also remove all symbols:
Remove symbols from the trimmed application, including embedded PDBs and separate PDB files. This applies to both the application code and any dependencies that come with symbols.
The SDK also makes it possible to disable debugger support using the property
DebuggerSupport. When debugger support is disabled, trimming will remove symbols automatically (
TrimmerRemoveSymbols will default to true).
Trimming framework library features
Several feature areas of the framework libraries come with trimmer directives that make it possible to remove the code for disabled features.
Remove code that creates autorelease pools on supported platforms. See AutoreleasePool for managed threads. This is the default for the .NET SDK.
Remove code that enables better debugging experiences. This setting also removes symbols.
Remove BinaryFormatter serialization support. For more information, see BinaryFormatter serialization methods are obsolete.
Remove insecure UTF-7 encoding code. For more information, see UTF-7 code paths are obsolete.
Remove EventSource related code or logic.
Remove code related to diagnostics support for System.Net.Http.
Remove globalization-specific code and data. For more information, see Invariant mode.
Remove metadata update-specific logic related to hot reload.
Remove support for generating stack traces (for example, Environment.StackTrace, or Exception.ToString) by the runtime. The amount of information that will be removed from stack trace strings may depend on other deployment options. This option does not affect stack traces generated by debuggers.
Use the default platform implementation of HttpMessageHandler for Android/iOS and remove the managed implementation.
Strip exception messages for
System.*assemblies. When an exception is thrown from a
System.*assembly, the message will be a simplified resource ID instead of the full message.
These properties cause the related code to be trimmed and also disable features via the runtimeconfig file. For more information about these properties, including the corresponding runtimeconfig options, see feature switches. Some SDKs may have default values for these properties.
Framework features disabled when trimming
The following features are incompatible with trimming because they require code that is not statically referenced. These are disabled by default in trimmed apps.
Enable these features at your own risk. They are likely to break trimmed apps without extra work to preserve the dynamically referenced code.
Built-in COM support is disabled.
Use of custom resource types is not supported. ResourceManager code paths that use reflection for custom resource types is trimmed.
C++/CLI host activation is disabled.
DesigntimeLicenseContextSerializer use of
BinaryFormatterserialization is disabled.
Running code before
DOTNET_STARTUP_HOOKSis not supported. For more information, see host startup hook.