Recommend setting publish options in project file by sbomer · Pull Request #24740 · dotnet/docs

sbomer · 2021-06-18T16:59:46Z

The PublishTrimmed option 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 a dotnet build.

Similarly, PublishSingleFile enables a single-file analyzer so it should also be set in the project file.

Addresses part of dotnet/linker#2085.

LakshanF · 2021-06-18T17:19:32Z

docs/core/deploying/trimming-options.md


 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.


Should we update the features list to include the new ones like BuiltInComInteropSupport, EnableCppCLIHostActivation etc.?

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.

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.

Suggested change

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).

I added a section for the trim-incompatible features, and also added a few more switches to the optional features section, including UseNativeHttpHandler.

agocke · 2021-06-18T18:56:53Z

docs/core/tools/dotnet-publish.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`**


Suggested change

- **`-p:PublishTrimmed=true`**

- **`<PublishTrimmed>true</PublishTrimmed>`**

Same for PublishSingleFile above

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.

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.

I removed PublishTrimmed, PublishSingleFile, and PublishReadyToRun. @tdykstra does this seem ok to you?

docs/core/deploying/single-file.md

eerhardt · 2021-06-21T15:54:05Z

docs/core/deploying/trimming-options.md


 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.


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.

tdykstra

LGTM, a couple suggestions

tdykstra · 2021-06-21T15:59:02Z

docs/core/deploying/trimming-options.md


 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.


Suggested change

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).

docs/core/deploying/trimming-options.md

Co-authored-by: Tom Dykstra <tdykstra@microsoft.com>

Also document UseNativeHttpHandler, AutoreleasePoolSupport, and MetadataUpdaterSupport

- Remove unnecessary SelfContained - Mention project properties and command-line arguments

docs/core/deploying/trim-self-contained.md

docs/core/tools/dotnet-publish.md

docs/core/deploying/trimming-options.md

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

In a separate section that mentions MSBuild properties.

docs/core/tools/dotnet-publish.md

eerhardt

Looks great. Thanks for making these changes, @sbomer!

- Remove outdated single-file description - Avoid ambiguous "this option" - Specify value for PublishReadyToRunShowWarning

sbomer added 2 commits June 18, 2021 09:36

Recommend setting PublishTrimmed in project file

38fe572

More fixes for single-file and publishing steps

23e79b0

sbomer requested review from adegeo and tdykstra as code owners June 18, 2021 16:59

dotnet-bot added this to the June 2021 milestone Jun 18, 2021

dotnet-bot added cli/subsvc dotnet-fundamentals/svc labels Jun 18, 2021

sbomer changed the title ~~Publish trimmed project~~ Recommend setting publish options in project file Jun 18, 2021

sbomer requested review from LakshanF, MichalStrehovsky, agocke and samsp-msft June 18, 2021 17:01

Fix typo in ilnk

0282c3a

LakshanF approved these changes Jun 18, 2021

View reviewed changes

agocke reviewed Jun 18, 2021

View reviewed changes

eerhardt reviewed Jun 21, 2021

View reviewed changes

tdykstra approved these changes Jun 21, 2021

View reviewed changes

Apply suggestions from code review

c8c721a

Co-authored-by: Tom Dykstra <tdykstra@microsoft.com>

BillWagner modified the milestones: June 2021, July 2021 Jul 1, 2021

sbomer added 4 commits July 1, 2021 10:17

Document features disabled when trimming

93d4787

Also document UseNativeHttpHandler, AutoreleasePoolSupport, and MetadataUpdaterSupport

Remove publish properties from dotnet-publish docs

185d88a

PR feedback

bb7ab02

- Remove unnecessary SelfContained - Mention project properties and command-line arguments

Try to fix link

84077dc

sbomer requested review from agocke and eerhardt July 1, 2021 17:51

eerhardt reviewed Jul 1, 2021

View reviewed changes

sbomer and others added 3 commits July 1, 2021 14:20

Apply suggestions from code review

3947282

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

Rework trim/single-file CLI steps

68adcc3

Add back publish MSBuild options for dotnet-publish

077e4fd

In a separate section that mentions MSBuild properties.

eerhardt reviewed Jul 2, 2021

View reviewed changes

docs/core/tools/dotnet-publish.md Outdated Show resolved Hide resolved

eerhardt reviewed Jul 2, 2021

View reviewed changes

docs/core/tools/dotnet-publish.md Outdated Show resolved Hide resolved

eerhardt reviewed Jul 2, 2021

View reviewed changes

docs/core/tools/dotnet-publish.md Outdated Show resolved Hide resolved

eerhardt approved these changes Jul 2, 2021

View reviewed changes

PR feedback

cd050c0

- Remove outdated single-file description - Avoid ambiguous "this option" - Specify value for PublishReadyToRunShowWarning

tdykstra merged commit 7814398 into dotnet:main Jul 5, 2021

Youssef1313 pushed a commit to Youssef1313/docs that referenced this pull request Jul 5, 2021

Recommend setting publish options in project file (dotnet#24740)

6673974


		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.

	- `-p:PublishTrimmed=true`
	- `<PublishTrimmed>true</PublishTrimmed>`

Conversation

sbomer commented Jun 18, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbomer Jun 18, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdykstra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eerhardt left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

sbomer Jun 18, 2021 •

edited

Loading