diff --git a/docs/core/deploying/single-file.md b/docs/core/deploying/single-file.md index ba1cd8701081b..019138f2047f6 100644 --- a/docs/core/deploying/single-file.md +++ b/docs/core/deploying/single-file.md @@ -123,9 +123,9 @@ Here's a sample project file that specifies single-file publishing: These properties have the following functions: -* `PublishSingleFile` - Enables single-file publishing. +* `PublishSingleFile` - Enables single-file publishing. Also enables single-file warnings during `dotnet build`. * `SelfContained` - Determines whether the app will be self-contained or framework-dependent. -* `RuntimeIdentifier` - Specifies the [OS and CPU type](../rid-catalog.md) you are targeting. +* `RuntimeIdentifier` - Specifies the [OS and CPU type](../rid-catalog.md) you are targeting. Also sets `true` by default. * `PublishTrimmed` - Enables use of [assembly trimming](trim-self-contained.md), which is only supported for self-contained apps. * `PublishReadyToRun` - Enables [ahead-of-time (AOT) compilation](ready-to-run.md). @@ -136,18 +136,29 @@ These properties have the following functions: ## Publish a single file app - CLI -Publish a single file application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: +Publish a single file application using the [dotnet publish](../tools/dotnet-publish.md) command. -- Publish for a specific runtime: `-r win-x64` -- Publish as a single-file: `-p:PublishSingleFile=true` +01. Add `true` to your project file. -The following example publishes an app for Windows as a self-contained single file application. + This will produce a single-file app on self-contained publish. It also shows single-file compatibility warnings during build. -```dotnetcli -dotnet publish -r win-x64 -p:PublishSingleFile=true --self-contained true -``` + ```xml + + true + + ``` + +01. Publish the app as for a specific runtime identifier using `dotnet publish -r ` + + The following example publishes the app for Windows as a self-contained single file application. -The following example publishes an app for Linux as a framework dependent single file application. + `dotnet publish -r win-x64` + + The following example publishes the app for Linux as a framework dependent single file application. + + `dotnet publish -r linux-x64 --self-contained false` + +`` should be set in the project file to enable single-file analysis during build, but it is also possible to pass these options as `dotnet publish` arguments: ```dotnetcli dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained false @@ -159,6 +170,8 @@ For more information, see [Publish .NET Core apps with .NET Core CLI](deploy-wit Visual Studio creates reusable publishing profiles that control how your application is published. +01. Add `true` to your project file. + 01. On the **Solution Explorer** pane, right-click on the project you want to publish. Select **Publish**. :::image type="content" source="media/single-file/visual-studio-solution-explorer.png" alt-text="Solution Explorer with a right-click menu highlighting the Publish option."::: diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index 80ef67d064905..b7a93b0a4d12c 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -71,37 +71,48 @@ If we're using .Net 5.0, we can update our project file to include the following ## Trim your app - CLI -Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: +Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. -- Publish as a self-contained app for a specific runtime: `-r win-x64` -- Enable trimming: `/p:PublishTrimmed=true` +01. Add `true` to your project file. -The following example publishes an app for Windows as self-contained and trims the output. + This will produce a trimmed app on self-contained publish. It also turns off trim-incompatible features and shows trim compatibility warnings during build. -```xml - - win-x64 - true - -``` + ```xml + + true + + ``` + +01. Publish a self-contained app for a specific runtime identifier using `dotnet publish -r ` -The following example publishes an app in the aggressive trim mode where unused code within assemblies will be trimmed and trimmer warnings enabled. + The following example publishes the app for Windows as trimmed self-contained application. + + `dotnet publish -r win-x64` + + Note that trimming is only supported for self-contained apps. + +The following example configures an app in the aggressive trim mode where unused code within assemblies will be trimmed and trimmer warnings enabled. ```xml - win-x64 true link false ``` +`` should be set in the project file so that trim-incompatible features are disabled during `dotnet build`, but it is also possible to pass these options as `dotnet publish` arguments: + +`dotnet publish -r win-x64 -p:PublishTrimmed=true` + For more information, see [Publish .NET Core apps with .NET Core CLI](deploy-with-cli.md). ## Trim your app - Visual Studio Visual Studio creates reusable publishing profiles that control how your application is published. +01. Add `true` to your project file. + 01. On the **Solution Explorer** pane, right-click on the project you want to publish. Select **Publish...**. :::image type="content" source="media/trim-self-contained/visual-studio-solution-explorer.png" alt-text="Solution Explorer with a right-click menu highlighting the Publish option."::: diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 7b376bd139fe0..1ac6c83315ab4 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -16,13 +16,17 @@ Trimming with `PublishTrimmed` was introduced in .NET Core 3.0. The other option - `true` - Enable trimming during publish, with the default settings defined by the SDK. + Enable trimming during publish. This also turns off trim-incompatible features and enables [trim analysis](#roslyn-analyzer) during build. -This will trim any assemblies which have been configured for trimming. With `Microsoft.NET.Sdk` in .NET 6, this includes the any assemblies with `[AssemblyMetadata("IsTrimmable", "True")]`, which is the case for framework assemblies. In .NET 5, framework assemblies from the netcoreapp runtime pack are configured for trimming via `` MSBuild metadata. Other SDKs may define different defaults. +Place this in the project file to ensure that the setting applies during `dotnet build`, not just `dotnet publish`. + +This will trim any assemblies that have been configured for trimming. With `Microsoft.NET.Sdk` in .NET 6, this includes the any assemblies with `[AssemblyMetadata("IsTrimmable", "True")]`, which is the case for framework assemblies. In .NET 5, framework assemblies from the netcoreapp runtime pack are configured for trimming via `` MSBuild metadata. Other SDKs may define different defaults. + +Starting in .NET 6, this setting also enables the trim compatibility [Roslyn analyzer](#roslyn-analyzer), and disables [features that are incompatible with trimming](#framework-features-disabled-when-trimming). ## Trimming granularity -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](#trimmed-assemblies) which overrides the property setting. +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](#trimmed-assemblies), which overrides the property setting. - `link` @@ -173,6 +177,10 @@ The SDK also makes it possible to disable debugger support using the property `D Several feature areas of the framework libraries come with linker directives that make it possible to remove the code for disabled features. +- `false` (default) + + Remove code that creates autorelease pools on supported platforms. See [AutoreleasePool for managed threads](../run-time-config/threading.md#autoreleasepool-for-managed-threads). This is the default for the .NET SDK. + - `false` Remove code that enables better debugging experiences. This will also [remove symbols](#remove-symbols). @@ -197,8 +205,43 @@ Several feature areas of the framework libraries come with linker directives tha Remove globalization specific code and data. For more information, see [Invariant mode](../run-time-config/globalization.md#invariant-mode). +- `false` + + Remove metadata update specific logic related to hot reload. + +- `true` + + Use the default platform implementation of HttpMessageHandler for Android/iOS and remove the managed implementation. + - `true` 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 will cause the related code to be trimmed and will also disable features via the [runtimeconfig](../run-time-config/index.md) file. For more information about these properties, including the corresponding runtimeconfig options, see [feature switches](https://github.com/dotnet/runtime/blob/main/docs/workflow/trimming/feature-switches.md). 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. + +> [!WARNING] +> 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. + +- `` + + [`DesigntimeLicenceContextSerializer`](https://docs.microsoft.com/dotnet/api/system.componentmodel.design.designtimelicensecontextserializer?view=net-5.0) use of BinaryFormatter serialization is disabled. + +- `` + + Running code before `Main` with `DOTNET_STARTUP_HOOKS` is not supported. For more information, see [host startup hook](https://github.com/dotnet/runtime/blob/main/docs/design/features/host-startup-hook.md). diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 252fec2c74a82..9efde78903b5b 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -18,7 +18,6 @@ dotnet publish [|] [-c|--configuration ] [-f|--framework ] [--force] [--interactive] [--manifest ] [--no-build] [--no-dependencies] [--no-restore] [--nologo] [-o|--output ] - [-p:PublishReadyToRun=true] [-p:PublishSingleFile=true] [-p:PublishTrimmed=true] [-r|--runtime ] [--self-contained [true|false]] [--no-self-contained] [-v|--verbosity ] [--version-suffix ] @@ -57,6 +56,28 @@ dotnet publish -p:PublishProfile=FolderProfile The preceding example uses the *FolderProfile.pubxml* file that is found in the *\/Properties/PublishProfiles* folder. If you specify a path and file extension when setting the `PublishProfile` property, they are ignored. MSBuild by default looks in the *Properties/PublishProfiles* folder and assumes the *pubxml* file extension. To specify the path and filename including extension, set the `PublishProfileFullPath` property instead of the `PublishProfile` property. +The following MSBuild properties change the output of `dotnet publish`. + +- `PublishReadyToRun` + + Compiles application assemblies as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation. For more information, see [ReadyToRun images](../deploying/ready-to-run.md). Available since .NET Core 3.0 SDK. + + To see warnings about missing dependencies that could cause runtime failures, use `PublishReadyToRunShowWarning=true`. + + We recommend that you specify `PublishReadyToRun` in a publish profile rather than on the command line. + +- `PublishSingleFile` + + Packages the app into a platform-specific single-file executable. For more information about single-file publishing, see the [single-file bundler design document](https://github.com/dotnet/designs/blob/main/accepted/2020/single-file/design.md). Available since .NET Core 3.0 SDK. + + We recommend that you specify this option in the project file rather than on the command line. + +- `PublishTrimmed` + + Trims unused libraries to reduce the deployment size of an app when publishing a self-contained executable. For more information, see [Trim self-contained deployments and executables](../deploying/trim-self-contained.md). Available since .NET Core 3.0 SDK as a preview feature. + + We recommend that you specify this option in the project file rather than on the command line. + For more information, see the following resources: - [MSBuild command-line reference](/visualstudio/msbuild/msbuild-command-line-reference) @@ -139,28 +160,6 @@ For more information, see the following resources: If you specify a relative path when publishing a solution, each project's output goes into a separate folder relative to the project file location. If you specify an absolute path when publishing a solution, all publish output for all projects goes into the specified folder. -- **`-p:PublishReadyToRun=true`** - - Compiles application assemblies as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation. For more information, see [ReadyToRun images](../deploying/ready-to-run.md). Available since .NET Core 3.0 SDK. - - To see warnings about missing dependencies that could cause runtime failures, use `-p:PublishReadyToRunShowWarnings=true`. - - We recommend that you specify this option in a publish profile rather than on the command line. For more information, see [MSBuild](#msbuild). - -- **`-p:PublishSingleFile=true`** - - Packages the app into a platform-specific single-file executable. The executable is self-extracting and contains all dependencies (including native) that are required to run the app. When the app is first run, the application is extracted to a directory based on the app name and build identifier. Startup is faster when the application is run again. The application doesn't need to extract itself a second time unless a new version is used. Available since .NET Core 3.0 SDK. - - For more information about single-file publishing, see the [single-file bundler design document](https://github.com/dotnet/designs/blob/main/accepted/2020/single-file/design.md). - - We recommend that you specify this option in a publish profile rather than on the command line. For more information, see [MSBuild](#msbuild). - -- **`-p:PublishTrimmed=true`** - - Trims unused libraries to reduce the deployment size of an app when publishing a self-contained executable. For more information, see [Trim self-contained deployments and executables](../deploying/trim-self-contained.md). Available since .NET Core 3.0 SDK as a preview feature. - - We recommend that you specify this option in a publish profile rather than on the command line. For more information, see [MSBuild](#msbuild). - - **`--self-contained [true|false]`** Publishes the .NET runtime with your application so the runtime doesn't need to be installed on the target machine. Default is `true` if a runtime identifier is specified and the project is an executable project (not a library project). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md).