Recommend setting publish options in project file (#24740)

sbomer · web-flow · commit 7814398e1e1b · 2021-07-04T17:15:17.000-07:00
diff --git 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 `<SelfContained>true</SelfContained>` 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 `<PublishSingleFile>true</PublishSingleFile>` 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
+    <PropertyGroup>
+        <PublishSingleFile>true</PublishSingleFile>
+    </PropertyGroup>
+    ```
+
+01. Publish the app as for a specific runtime identifier using `dotnet publish -r <RID>`
+
+    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`
+
+`<PublishSingleFile>` 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 `<PublishSingleFile>true</PublishSingleFile>` 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
@@ -38,37 +38,48 @@ When the code is indirectly referencing an assembly through reflection, you can
 
 ## 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 `<PublishTrimmed>true</PublishTrimmed>` 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
-<PropertyGroup>
-    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
-    <PublishTrimmed>true</PublishTrimmed>
-</PropertyGroup>
-```
+    ```xml
+    <PropertyGroup>
+        <PublishTrimmed>true</PublishTrimmed>
+    </PropertyGroup>
+    ```
+
+01. Publish a self-contained app for a specific runtime identifier using `dotnet publish -r <RID>`
 
-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
 <PropertyGroup>
-    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
     <PublishTrimmed>true</PublishTrimmed>
     <TrimMode>link</TrimMode>
     <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>
 </PropertyGroup>
 ```
 
+`<PublishTrimmed>` 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 `<PublishTrimmed>true</PublishTrimmed>` 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
@@ -16,13 +16,17 @@ Trimming with `PublishTrimmed` was introduced in .NET Core 3.0. The other option
 
 - `<PublishTrimmed>true</PublishTrimmed>`
 
-   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 `<IsTrimmable>` 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 `<IsTrimmable>` 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.
 
 - `<TrimMode>link</TrimMode>`
 
@@ -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.
 
+- `<AutoreleasePoolSupport>false</AutoreleasePoolSupport>` (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.
+
 - `<DebuggerSupport>false</DebuggerSupport>`
 
     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).
 
+- `<MetadataUpdaterSupport>false</MetadataUpdaterSupport>`
+
+    Remove metadata update specific logic related to hot reload.
+
+- `<UseNativeHttpHandler>true</UseNativeHttpHandler>`
+
+    Use the default platform implementation of HttpMessageHandler for Android/iOS and remove the managed implementation.
+
 - `<UseSystemResourceKeys>true</UseSystemResourceKeys>`
 
     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.
+
+- `<BuiltInComInteropSupport>`
+
+   Built-in COM support is disabled.
+
+- `<CustomResourceTypesSupport>`
+
+   Use of custom resource types is not supported. ResourceManager code paths that use reflection for custom resource types is trimmed.
+
+- `<EnableCppCLIHostActivation>`
+
+    C++/CLI host activation is disabled.
+
+- `<EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>`
+
+   [`DesigntimeLicenceContextSerializer`](https://docs.microsoft.com/dotnet/api/system.componentmodel.design.designtimelicensecontextserializer?view=net-5.0) use of BinaryFormatter serialization is disabled.
+
+- `<StartupHookSupport>`
+
+   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
@@ -18,7 +18,6 @@ dotnet publish [<PROJECT>|<SOLUTION>] [-c|--configuration <CONFIGURATION>]
     [-f|--framework <FRAMEWORK>] [--force] [--interactive]
     [--manifest <PATH_TO_MANIFEST_FILE>] [--no-build] [--no-dependencies]
     [--no-restore] [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
-    [-p:PublishReadyToRun=true] [-p:PublishSingleFile=true] [-p:PublishTrimmed=true]
     [-r|--runtime <RUNTIME_IDENTIFIER>] [--self-contained [true|false]]
     [--no-self-contained] [-v|--verbosity <LEVEL>]
     [--version-suffix <VERSION_SUFFIX>]
@@ -57,6 +56,28 @@ dotnet publish -p:PublishProfile=FolderProfile
 
 The preceding example uses the *FolderProfile.pubxml* file that is found in the *\<project_folder>/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).
