Recommend setting publish options in project file #24740
Conversation
sbomer
changed the title
|
|
||
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Should we update the features list to include the new ones like BuiltInComInteropSupport, EnableCppCLIHostActivation etc.?
There was a problem hiding this comment.
I don't think we should document the ones that are already disabled by default when linking - we don't want to encourage people to enable the unsupported ones.
But it looks like UseNativeHttpHandler is missing from the list. @eerhardt do you think we should document that one? It looks to me like UseNativeHttpHandler=true will prevent some (but not all) references to HttpClientHandler - I'm not sure whether this feature was designed for trimming in particular.
There was a problem hiding this comment.
I do find it a bit confusing that we are explicitly saying disables features [link] which are incompatible with trimming, but then the link doesn't list any features which are incompatible with trimming.
Maybe we should have 2 sections? Features that can be toggled when trimming, and features that are not compatible with trimming?
But it looks like UseNativeHttpHandler is missing from the list.
@EgorBo @akoeplinger @steveisok @marek-safar - should we be documenting UseNativeHttpHandler here? I believe it is only valid for Android and iOS apps.
There was a problem hiding this comment.
| 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](#trimming-framework-library-features). |
There was a problem hiding this comment.
I added a section for the trim-incompatible features, and also added a few more switches to the optional features section, including UseNativeHttpHandler.
docs/core/tools/dotnet-publish.md
Outdated
| @@ -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`** | |||
There was a problem hiding this comment.
| - **`-p:PublishTrimmed=true`** | |
| - **`<PublishTrimmed>true</PublishTrimmed>`** |
There was a problem hiding this comment.
Same for PublishSingleFile above
There was a problem hiding this comment.
Unfortunately this document is talking about command-line options for the dotnet publish command. Should we maybe just remove these sections from this file? It's strange that they're documented as publish options when really they're just passed to MSBuild. And these same docs then recommend not using the command-line arg version.
There was a problem hiding this comment.
Removing them seems best, although the unfortunate benefit is that if you specific PublishTrimmed on the command line then it applies to all projects, and would turn on the analyzer for all of them. I suppose we also need to recommend adding EnableTrimmingAnalyzer in every project.
There was a problem hiding this comment.
I removed PublishTrimmed, PublishSingleFile, and PublishReadyToRun. @tdykstra does this seem ok to you?
|
|
||
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
I do find it a bit confusing that we are explicitly saying disables features [link] which are incompatible with trimming, but then the link doesn't list any features which are incompatible with trimming.
Maybe we should have 2 sections? Features that can be toggled when trimming, and features that are not compatible with trimming?
But it looks like UseNativeHttpHandler is missing from the list.
@EgorBo @akoeplinger @steveisok @marek-safar - should we be documenting UseNativeHttpHandler here? I believe it is only valid for Android and iOS apps.
|
|
||
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
| 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](#trimming-framework-library-features). |
Co-authored-by: Tom Dykstra <[email protected]>
Also document UseNativeHttpHandler, AutoreleasePoolSupport, and MetadataUpdaterSupport
- Remove unnecessary SelfContained - Mention project properties and command-line arguments
Co-authored-by: Eric Erhardt <[email protected]>
In a separate section that mentions MSBuild properties.
- Remove outdated single-file description - Avoid ambiguous "this option" - Specify value for PublishReadyToRunShowWarning
The
PublishTrimmedoption also disables trim-incompatible features, and turns on a Roslyn analyzer for trim compatibility, so it should be set in the project file to ensure these settings apply during adotnet build.Similarly,
PublishSingleFileenables a single-file analyzer so it should also be set in the project file.Addresses part of dotnet/linker#2085.