Support extending which assemblies are trimmable

[sbomer]

The current linker defaults make it difficult to modify the linker behavior to achieve "aggressive" trimming. We should introduce an MSBuild property to turn on aggressive trimming - that is, to pass all linker inputs with the action "link" instead of "copy" or "copyused". We need to consider how this interacts with existing mechanisms to modify linker behavior on individual assemblies.

It should be possible to enable different levels of trimming on a per-assembly basis as well, especially by different SDK components. The primary use case we would like to support immediately is blazor.

[sbomer]

Background

The SDK publish targets run ILLink, which has subtargets that process ResolvedFileToPublish. This list gets filtered down to the managed assemblies with PostProcessAssemblies == true, which are passed to the linker. Those with IsTrimmable != true by default are rooted and linked with the copy action, and the rest have the action determined by _TrimmerDefaultAction, which defaults to copyused.

It is worth reiterating that there are three conditions that influence the behavior:

1. PostProcessAssemblies controls whether the linker will see the assembly at all
2. IsTrimmable controls whether the linker will tree-shake the assembly (if not, it gets rooted, and gets action copy)
3. the action (per-assembly Action metadata, or default) controls the level of tree-shaking

Blazor has their own linker targets that run during build, which filter assemblies by filename to determine the linker behavior. For .NET5, they are planning to move to the built-in linker targets that run during publish. They need a place to hook into the pipeline where they can continue filtering assemblies by name, and also a way to set the linker default behavior to aggressive trimming instead of assembly-level trimming (which is the .NET SDK default). In addition, they generate custom "type-granularity" roots for some assemblies, which will be done in the same place.

Proposal

TrimMode

To enable aggressive trimming instead of assembly-level trimming, we provide a public property TrimMode. Setting this tolink will change the default behavior from copyused to link (aggressive trimming) for assemblies that don't have per-assembly TrimMode. TrimMode can also be set as Item metadata to override the global property per-assembly.

PrepareForILLink

We will provide a new public target, PrepareForILLink that runs before ILLink target, and provides a convenient place to hook into the pipeline to modify metadata for trimming. SDK components can use this as an extension point via BeforeTargets and AfterTargets.

The global TrimMode may be set any time before PrepareForILLink runs, which will set it to a default value if not set previously.

ManagedAssemblyToLink

This target will have a dependency that creates the ItemGroup ManagedAssemblyToLink, which represents the set of assemblies that will be passed to the linker. Custom targets may modify IsTrimmable and TrimMode metadata on these assemblies before PrepareForILLink, which will set the assembly action based on this metadata, or they may modify the metadata after PrepareForILLink has run.

It will be illegal to change the items in ManagedAssemblyToLink, since this represents the set that needs to be filtered and replaced in the publish output. To change which assemblies are passed to the linker, a different extension point should be used to set PostProcessAssemblies metadata.

Examples

This shows how a developer could turn on aggressive trimming for framework assemblies (which are defined to be IsTrimmable by the SDK):

<PropertyGroup>
  <TrimMode>link</TrimMode>
</PropertyGroup>

This shows how Blazor (or a developer) could hook into the build to opt assemblies into different levels of trimming based on the filename:

<Target Name="PrepareForBlazorILLink"
        BeforeTargets="PrepareForILLink">
  <PropertyGroup>
    <!-- Set the default TrimMode for IsTrimmable assemblies -->
    <TrimMode>link</TrimMode>
  </PropertyGroup>
  <ItemGroup>
    <ManagedAssemblyToLink Condition="'$([System.String]::Copy('%(ManagedAssemblyToLink.Filename)').StartsWith('Microsoft.AspNetCore.'))">
      <!-- Trim these assemblies using the global TrimMode -->
      <IsTrimmable>true</IsTrimmable>
    </ManagedAssemblyToLink>
    <ManagedAssemblyToLink Condition="'$([System.String]::Copy('%(ManagedAssemblyToLink.Filename)').StartsWith('ThirdPartyAssembly.'))">
      <!-- Trim these assemblies with assembly-level trimming. Implies IsTrimmable. -->
      <TrimMode>copyused</TrimMode>
    </ManagedAssemblyToLink>
  </ItemGroup>
</Target>

Notes

IsTrimmable vs TrimMode

IsTrimmable exists in addition to TrimMode so that there can be a global default for assemblies without a per-assembly TrimMode. This lets the global property be used to set the mode for all IsTrimmable assemblies, and it lets individual assemblies be opted into trimming using the default mode set by the SDK for the target form factor.

Naming of TrimMode values

We have considered a few naming conventions for the TrimMode values:

• Conservative/Aggressive - avoids complex terminology and would be easy to use for app developers without requiring an understanding of the linker, and might let us change optimization levels in the future, but hides details from developers who are interested in the underlying behavior
• TrimAssembly/TrimMembers - describes what the linker is doing in each mode, but is incomplete because it doesn't mention the various optimizations that are turned on
• copyused/link - maps directly to the underlying terminology used in the linker, letting developers who understand the linker make informed decisions, but requires more understanding of the linker

For now, the proposal is to stay with the copyused/link terminology that is used by the tool itself. IsTrimmable allows opting into or out of trimming without referencing this terminology. If we add higher-level options to the linker in the future, we could expose those as new TrimMode values, or aliases for existing values.

Relation to existing options

TrimMode (global and per-assembly) will replace _TrimmerDefaultAction and the per-assembly Action metadata. PrepareForILLink and ManagedAssemblyToLink will replace the _SetILLinkDefaults target and the _ManagedAssembliesToLink ItemGroup.

Build vs Publish

The public properties and targets exposed in this design do not require modifying ResolvedFileToPublish or other MSBuild entities that are related to publish, leaving some room for us to potentially reuse targets if we ever need to run the linker during build instead of publish.

@eerhardt @pranavkm @marek-safar

[marek-safar]

/cc @akoeplinger

[eerhardt]

I think this proposal looks really good. Thanks for putting it together. I have a couple comments/questions:

1. Custom targets may modify IsTrimmable and Action metadata on these assemblies

   • What's the difference between IsTrimmable and Action? Do we need both?
2. The usage of the terms link and trim confuses me (this isn't just based on this proposal, we sort of have issues everywhere). The target is named ILLink, which respects a property named IsTrimmable. And then we have a property named TrimmerDefaultAction, which I can set to link.

[pranavkm]

Minor nit, The SDK typically names items in the singular e.g. ResolvedFileToPublish, ContentWithTargetPath etc. Consider naming the item group ManagedAssemblyToLink

[sbomer]

What's the difference between IsTrimmable and Action? Do we need both?

IsTrimmable was originally intended as a user-facing opt-in that deals less with the implementation details. Its current semantics aren't captured by Action alone since non-IsTrimmable assemblies are also rooted. (Action just represents the linker action).

The usage of the terms link and trim confuses me

Agreed. :( To explain how we got here: ILLink is used because it's the name of the tool (originally monolinker). PMs recommended to use "Trimmer" to describe the tool to the public and for the public-facing MSBuild options in 3.0. Now more of the extension points are reflecting naming conventions used by the tool - and we are even considering using the tool in an analysis mode, where the input assemblies, tentatively named ManagedAssemblyToLink in the proposal, would be analyzed without being trimmed.

If I were starting fresh, I might consider naming the project something like "IL Analyzer" or "IL Optimizer", and use "ManagedAssemblyToAnalyze", "AnalyzerAction: Trim", etc.

Consider naming the item group ManagedAssemblyToLink

Edited above, thanks!

[sbomer]

a property named TrimmerDefaultAction, which I can set to link

An alternative to TrimmerDefaultAction would be to define a different property like TrimmerGranularity (member/assembly) that maps to _TrimmerDefaultAction = link or copyused. Another idea is TrimmerBehavior (TrimMembers/TrimAssemblies), which we could extend to Analyze for a future analyze-but-don't-trim mode. Thoughts?

@vitek-karas @MichalStrehovsky

[marek-safar]

What about instead of TrimmerDefaultAction to have TrimmingMode with link, copy etc options. It could also be handy to allow the same attribute to be used on the project/assembly/packages references (can be done later).

[vitek-karas]

I don't like the term "link" - I think it has too much history which is about tools not related to our "linker" functionality (there is some overlap, but relatively small and definitely hard to explain). Not counting that when we introduce true AOT, there might actually be a true platform linker in the toolchain as well - which would create lot of confusion.

So in that sense I prefer anything else - "trim"/"trimmer" is at least unique enough. So going with that logic, I think we should name all public (and as much of internal ones as possible) properties/items with that term "trim".

The above proposal looks good with the exception of ManagedAssemblyToLink - it just doesn't fir with the rest. It's not ideal either, but ManagedAssemblyToTrim would at least fit with the rest well. Even if we later on tell the "Trimmer" to skip the assembly for example.

As for the future analyze-only scenarios... if we have to I would be OK with using "trim" there as well (after all the trim part is by far the most complex and likely heavily used). Having an action "analyze" which would apply as the default or per-assembly would make that work reasonably well.

If we could improve on that, then I would probably go with a completely separate set of properties/items - the example ManagedAssemblyToAnalyze sounds good. The tricky bit would be how to unify the two sets (trim and analyze) when both are used and we would use both to tell linker what to do.

One other thing to consider - rename the actions - specifically "link" is just bad (see the above reasons). Not only it uses terminology which is typically associated with a different action, but even in the linker it makes little sense - it actually means "trim" or "sweep" or... but not "link" (whatever that means). So ideally the values used by the msbuild properties/items would be from a different set which align the terms with the above discussion. Implementation wise we could either do the translation in the msbuild or ILLink task, or we could teach linker to accept multiple values for the same thing.

While we're at it, I think it's a good idea to design ahead and incorporate the "trim granularity" into it - so basically rename "copy" to "TrimAssembly" or similar which would then probably mean renaming "link" to "TrimMembers" - not bad. We don't have to support or even define all of those yet if we don't need to.

Nit: For actions and related settings I would not use the name of the tool, but rather the name of the action, so: TrimmerGranularity -> TrimGranularity. TrimmerDefaultAction is different as that talks about the tool - so that could stay like that.

[vitek-karas]

Adding @samsp-msft as the PM representative.

[sbomer]

Thanks for the feedback! How does the following sound?

• ManagedAssemblyToLink -> ManagedAssemblyToTrim (note that this set will include IsTrimmable != true assemblies)
• TrimmerDefaultAction (link/copyused/copy/...) -> TrimMode (TrimMembers/TrimAssembly/Keep...)

My only concern is that Keep might be read by some as "root", which isn't what it means. Can anyone suggest a better name to replace copy?

I think it would make sense to do the translation in the task as long as there is a 1-to-1 mapping of these settings to AssemblyAction.

[eerhardt]

note that this set will include IsTrimmable != true assemblies

I still don't understand why we need IsTrimmable at all. Why can't we just have TrimMode, and if TrimMode isn't set, it defaults to Keep/copy?

[sbomer]

Why can't we just have TrimMode, and if TrimMode isn't set, it defaults to Keep/copy?

We also want non-IsTrimmable assemblies to be rooted, but I don't think an empty TrimMode should have those semantics. Rooting means something different from the assembly action - which is more like a decision about what to output.

There are two ways to set the TrimMode/action at the level of illink.dll: a global setting, or per-assembly settings that take precedence over the global setting. The addition of IsTrimmable also lets you use opt an assembly into trimming without explicitly specifying the action.

That's how I think about it at least - but maybe there is a cleaner way to do it that I'm not seeing.