From 38fe57227d0f2bc43aa47d34468c42744c7783b8 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Fri, 18 Jun 2021 09:36:27 -0700 Subject: [PATCH 01/12] Recommend setting PublishTrimmed in project file --- docs/core/deploying/trim-self-contained.md | 4 +++- docs/core/deploying/trimming-options.md | 6 +++++- docs/core/tools/dotnet-publish.md | 4 ++-- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index 80ef67d064905..391ce8604062d 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -74,7 +74,9 @@ If we're using .Net 5.0, we can update our project file to include the following Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: - Publish as a self-contained app for a specific runtime: `-r win-x64` -- Enable trimming: `/p:PublishTrimmed=true` +- Enable trimming: `true` + +`PublishTrimmed` should be set in the project file so that trim-incompatible features are also disabled during `dotnet build`. The following example publishes an app for Windows as self-contained and trims the output. diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 7b376bd139fe0..74d4334a764ea 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -16,10 +16,14 @@ 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. + +Place this in the project file to ensure that the setting applies during `dotnet build`, not just `dotnet publish`. 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. +Starting in .NET 6, this setting also enables the trim compatibility [Roslyn analyzer](#roslyn-analyzer), and disables [features](#trimming-framework-libraryfeatures) which are incompatible with 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. diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 252fec2c74a82..6ac11972ff214 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -153,13 +153,13 @@ For more information, see the following resources: 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). + We recommend that you specify this option in the project file rather than on the command line. Setting it in the project file enables a Roslyn analyzer that provides single-file compatibility warnings during `dotnet build`. 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). + We recommend that you specify this option in the project file rather than on the command line. Setting it in the project file enables a Roslyn analyzer that provides trim analysis warnings during `dotnet build`. For more information, see [MSBuild](#msbuild). - **`--self-contained [true|false]`** From 23e79b078d381b5e0801bcd8dedfc477a8bf0f79 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Fri, 18 Jun 2021 09:57:16 -0700 Subject: [PATCH 02/12] More fixes for single-file and publishing steps --- docs/core/deploying/single-file.md | 22 ++++++++++++++++------ docs/core/deploying/trim-self-contained.md | 2 ++ 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/core/deploying/single-file.md b/docs/core/deploying/single-file.md index ba1cd8701081b..0c739f4ad7e83 100644 --- a/docs/core/deploying/single-file.md +++ b/docs/core/deploying/single-file.md @@ -123,7 +123,7 @@ 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. * `PublishTrimmed` - Enables use of [assembly trimming](trim-self-contained.md), which is only supported for self-contained apps. @@ -139,18 +139,26 @@ These properties have the following functions: Publish a single file application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: - Publish for a specific runtime: `-r win-x64` -- Publish as a single-file: `-p:PublishSingleFile=true` +- Publish as a single-file: `true` The following example publishes an app for Windows as a self-contained single file application. -```dotnetcli -dotnet publish -r win-x64 -p:PublishSingleFile=true --self-contained true +```xml + + win-x64 + true + true + ``` The following example publishes an app for Linux as a framework dependent single file application. -```dotnetcli -dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained false +```xml + + win-x64 + true + false + ``` For more information, see [Publish .NET Core apps with .NET Core CLI](deploy-with-cli.md). @@ -159,6 +167,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 391ce8604062d..f8af57b2f2312 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -104,6 +104,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/trim-self-contained/visual-studio-solution-explorer.png" alt-text="Solution Explorer with a right-click menu highlighting the Publish option."::: From 0282c3ab83195a8ecacd1f6c9fc130dbb0e8ad81 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Fri, 18 Jun 2021 10:02:58 -0700 Subject: [PATCH 03/12] Fix typo in ilnk --- docs/core/deploying/trimming-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 74d4334a764ea..64a09f38ca2fd 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -22,7 +22,7 @@ Place this in the project file to ensure that the setting applies during `dotnet 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. -Starting in .NET 6, this setting also enables the trim compatibility [Roslyn analyzer](#roslyn-analyzer), and disables [features](#trimming-framework-libraryfeatures) which are incompatible with trimming. +Starting in .NET 6, this setting also enables the trim compatibility [Roslyn analyzer](#roslyn-analyzer), and disables [features](#trimming-framework-library-features) which are incompatible with trimming. ## Trimming granularity From c8c721a613c417cee0e334a6c67462fe85a8bc66 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Mon, 28 Jun 2021 10:44:30 -0700 Subject: [PATCH 04/12] Apply suggestions from code review Co-authored-by: Tom Dykstra --- docs/core/deploying/trimming-options.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 64a09f38ca2fd..a13b91eb8c52f 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -20,13 +20,13 @@ Trimming with `PublishTrimmed` was introduced in .NET Core 3.0. The other option Place this in the project file to ensure that the setting applies during `dotnet build`, not just `dotnet publish`. -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. +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](#trimming-framework-library-features) which are incompatible with 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` From 93d47873d6475aefa7d61ce6f782444a93150224 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 10:16:59 -0700 Subject: [PATCH 05/12] Document features disabled when trimming Also document UseNativeHttpHandler, AutoreleasePoolSupport, and MetadataUpdaterSupport --- docs/core/deploying/trimming-options.md | 41 ++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index a13b91eb8c52f..5e5111e2ae57c 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -22,7 +22,7 @@ Place this in the project file to ensure that the setting applies during `dotnet 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](#trimming-framework-library-features) which are incompatible with trimming. +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 @@ -177,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#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). @@ -201,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 dissabeld. + +- `` + + 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). From 185d88ac211403b70d08b37ef705a086ed362d55 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 17:24:10 +0000 Subject: [PATCH 06/12] Remove publish properties from dotnet-publish docs --- docs/core/tools/dotnet-publish.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 6ac11972ff214..33be209684fa5 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 ] @@ -139,28 +138,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 the project file rather than on the command line. Setting it in the project file enables a Roslyn analyzer that provides single-file compatibility warnings during `dotnet build`. 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 the project file rather than on the command line. Setting it in the project file enables a Roslyn analyzer that provides trim analysis warnings during `dotnet build`. 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). From bb7ab021982e7b8c946cd76cacf7f9e3da76665b Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 17:43:07 +0000 Subject: [PATCH 07/12] PR feedback - Remove unnecessary SelfContained - Mention project properties and command-line arguments --- docs/core/deploying/single-file.md | 15 ++++++++++----- docs/core/deploying/trim-self-contained.md | 8 +++++--- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/core/deploying/single-file.md b/docs/core/deploying/single-file.md index 0c739f4ad7e83..675937dbfdf4e 100644 --- a/docs/core/deploying/single-file.md +++ b/docs/core/deploying/single-file.md @@ -125,7 +125,7 @@ These properties have the following functions: * `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,9 +136,9 @@ 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. Set the following properties in your project file, then publish the app using `dotnet publish`. -- Publish for a specific runtime: `-r win-x64` +- Publish for a specific runtime: `win-x64` - Publish as a single-file: `true` The following example publishes an app for Windows as a self-contained single file application. @@ -147,7 +147,6 @@ The following example publishes an app for Windows as a self-contained single fi win-x64 true - true ``` @@ -155,12 +154,18 @@ The following example publishes an app for Linux as a framework dependent single ```xml - win-x64 + linux-x64 true 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 +``` + For more information, see [Publish .NET Core apps with .NET Core CLI](deploy-with-cli.md). ## Publish a single file app - Visual Studio diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index f8af57b2f2312..18e94c25b7134 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -73,11 +73,9 @@ If we're using .Net 5.0, we can update our project file to include the following Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: -- Publish as a self-contained app for a specific runtime: `-r win-x64` +- Publish as a self-contained app for a specific runtime: `win-x64` - Enable trimming: `true` -`PublishTrimmed` should be set in the project file so that trim-incompatible features are also disabled during `dotnet build`. - The following example publishes an app for Windows as self-contained and trims the output. ```xml @@ -98,6 +96,10 @@ The following example publishes an app in the aggressive trim mode where unused ``` +`` 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 From 84077dc1b8020c61773510b101abf7493e195c5d Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 17:49:28 +0000 Subject: [PATCH 08/12] Try to fix link --- docs/core/deploying/trimming-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 5e5111e2ae57c..2944b090f6a94 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -179,7 +179,7 @@ Several feature areas of the framework libraries come with linker directives tha - `false` (default) - Remove code that creates autorelease pools on supported platforms. See [AutoreleasePool for managed threads](../run-time-config/threading#autoreleasepool-for-managed-threads). This is the default for the .NET SDK. + 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` From 39472824e65a2570e82c6e5e17d121846c67c293 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 14:20:10 -0700 Subject: [PATCH 09/12] Apply suggestions from code review Co-authored-by: Eric Erhardt --- docs/core/deploying/trim-self-contained.md | 2 +- docs/core/deploying/trimming-options.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index 18e94c25b7134..9d31d6228916a 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -71,7 +71,7 @@ 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. Set the following properties in your project file, then publish the app using `dotnet publish`. - Publish as a self-contained app for a specific runtime: `win-x64` - Enable trimming: `true` diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 2944b090f6a94..1ac6c83315ab4 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -240,7 +240,7 @@ The following features are incompatible with trimming because they require code - `` - [`DesigntimeLicenceContextSerializer`](https://docs.microsoft.com/dotnet/api/system.componentmodel.design.designtimelicensecontextserializer?view=net-5.0) use of BinaryFormatter serialization is dissabeld. + [`DesigntimeLicenceContextSerializer`](https://docs.microsoft.com/dotnet/api/system.componentmodel.design.designtimelicensecontextserializer?view=net-5.0) use of BinaryFormatter serialization is disabled. - `` From 68adcc337cb3a3681bd0af2a5bbc07ebafb77536 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 21:52:59 +0000 Subject: [PATCH 10/12] Rework trim/single-file CLI steps --- docs/core/deploying/single-file.md | 34 ++++++++++------------ docs/core/deploying/trim-self-contained.md | 29 ++++++++++-------- 2 files changed, 33 insertions(+), 30 deletions(-) diff --git a/docs/core/deploying/single-file.md b/docs/core/deploying/single-file.md index 675937dbfdf4e..019138f2047f6 100644 --- a/docs/core/deploying/single-file.md +++ b/docs/core/deploying/single-file.md @@ -136,29 +136,27 @@ 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. Set the following properties in your project file, then publish the app using `dotnet publish`. +Publish a single file application using the [dotnet publish](../tools/dotnet-publish.md) command. -- Publish for a specific runtime: `win-x64` -- Publish as a single-file: `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. -```xml - - win-x64 - true - -``` + ```xml + + true + + ``` -The following example publishes an app for Linux as a framework dependent single file application. +01. Publish the app as for a specific runtime identifier using `dotnet publish -r ` -```xml - - linux-x64 - true - false - -``` + The following example publishes the app for Windows as a self-contained 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: diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index 9d31d6228916a..b7a93b0a4d12c 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -71,25 +71,30 @@ 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. Set the following properties in your project file, then publish the app using `dotnet publish`. +Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. -- Publish as a self-contained app for a specific runtime: `win-x64` -- Enable trimming: `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 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 publishes an app in the aggressive trim mode where unused code within assemblies will be trimmed and trimmer warnings enabled. +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 From 077e4fda9e4b33c0f75a671561f075ccd19fe40f Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 22:06:42 +0000 Subject: [PATCH 11/12] Add back publish MSBuild options for dotnet-publish In a separate section that mentions MSBuild properties. --- docs/core/tools/dotnet-publish.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 33be209684fa5..7a39ba6a05b1a 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -56,6 +56,30 @@ 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`. + + We recommend that you specify this option in a publish profile rather than on the command line. + +- `PublishSingleFile` + + 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 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) From cd050c0578d0bc368381ee23e50fe753e7029605 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Fri, 2 Jul 2021 20:57:34 +0000 Subject: [PATCH 12/12] PR feedback - Remove outdated single-file description - Avoid ambiguous "this option" - Specify value for PublishReadyToRunShowWarning --- docs/core/tools/dotnet-publish.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 7a39ba6a05b1a..9efde78903b5b 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -62,15 +62,13 @@ The following MSBuild properties change the output of `dotnet publish`. 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`. + To see warnings about missing dependencies that could cause runtime failures, use `PublishReadyToRunShowWarning=true`. - We recommend that you specify this option in a publish profile rather than on the command line. + 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. 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). + 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.