Edit

Trim self-contained deployments and executables

  • Article

The framework-dependent deployment model has been the most successful deployment model since the inception of .NET. In this scenario, the application developer bundles only the application and third-party assemblies with the expectation that the .NET runtime and runtime libraries will be available in the client machine. This deployment model continues to be the dominant one in the latest .NET release, however, there are some scenarios where the framework-dependent model is not the best choice. The alternative is to publish a self-contained application, where the .NET runtime and runtime libraries are bundled together with the application and third-party assemblies.

The trim-self-contained deployment model is a specialized version of the self-contained deployment model that is optimized to reduce deployment size. Minimizing deployment size is a critical requirement for some client-side scenarios like Blazor applications. Depending on the complexity of the application, only a subset of the framework assemblies are referenced, and a subset of the code within each assembly is required to run the application. The unused parts of the libraries are unnecessary and can be trimmed from the packaged application.

However, there is a risk that the build-time analysis of the application can cause failures at run time, due to not being able to reliably analyze various problematic code patterns (largely centered on reflection use). To mitigate these problems, warnings are produced whenever the trimmer cannot fully analyze a code pattern. For information on what the trim warnings mean and how to resolve them, see Introduction to trim warnings.

Note

  • Trimming is fully supported in .NET 6 and later versions. In .NET Core 3.1 and .NET 5, trimming was an experimental feature.
  • Trimming is only available to applications that are published self-contained.

Components that cause trimming problems

Warning

Not all project types can be trimmed. For more information, see Known trimming incompatibilities.

Any code that causes build time analysis challenges isn't suitable for trimming. Some common coding patterns that are problematic when used by an application originate from unbounded reflection usage and external dependencies that aren't visible at build time. An example of unbounded reflection is a legacy serializer, such as XML serialization, and an example of invisible external dependencies is built-in COM. To address trim warnings in your application, see Introduction to trim warnings, and to make your library compatible with trimming, see Prepare .NET libraries for trimming.

Enable trimming

  1. Add <PublishTrimmed>true</PublishTrimmed> to your project file.

    This property will produce a trimmed app on self-contained publish. It also turns off trim-incompatible features and shows trim compatibility warnings during build.

    <PropertyGroup>
    <PublishTrimmed>true</PublishTrimmed>
</PropertyGroup>

  2. Then publish your app using either the dotnet publish command or Visual Studio.

Publish with the CLI

The following example publishes the app for Windows as a trimmed self-contained application.

dotnet publish -r win-x64

Trimming is only supported for self-contained apps.

<PublishTrimmed> should be set in the project file so that trim-incompatible features are disabled during dotnet build. However, you can also set this option as an argument to dotnet publish:

dotnet publish -r win-x64 -p:PublishTrimmed=true

For more information, see Publish .NET apps with .NET CLI.

Publish with Visual Studio

  1. In Solution Explorer, right-click on the project you want to publish and select Publish.

    Solution Explorer with a right-click menu highlighting the Publish option.

    If you don't already have a publishing profile, follow the instructions to create one and choose the Folder target-type.

  2. Choose More actions > Edit.

    Visual studio publish profile with edit button.

  3. In the Profile settings dialog, set the following options:

    • Set Deployment mode to Self-contained.
    • Set Target runtime to the platform you want to publish to.
    • Select Trim unused code.

    Choose Save to save the settings and return to the Publish dialog.

    Profile settings dialog with deployment mode, target runtime, and trim unused assemblies options highlighted.

  4. Choose Publish to publish your app trimmed.

For more information, see Publish .NET Core apps with Visual Studio.

Publish with Visual Studio for Mac

Visual Studio for Mac doesn't provide options to publish your app. You'll need to publish manually by following the instructions from the Publishing with the CLI section. For more information, see Publish .NET apps with .NET CLI.

See also