docs icon indicating copy to clipboard operation
docs copied to clipboard
verified publisher icon dotnet

Add multi-targeting sections to trimming and AOT documentation

Open Copilot opened this issue 3 months ago • 2 comments

Adding multi-targeting sections to trimming and AOT documentation

  • [x] Explore repository structure and understand the issue
  • [x] Review current documentation in prepare-libraries-for-trimming.md
  • [x] Review related breaking change document
  • [x] Add new H2 section "Multi-targeting for trimming" after "Enable library trim warnings"
  • [x] Include recommendations for multi-targeting scenarios
  • [x] Add example showing conditional IsTrimmable usage
  • [x] Explain common multi-targeting scenarios (netstandard2.0, net472, net6.0+)
  • [x] Link to breaking change document
  • [x] Verify markdown linting passes
  • [x] Update document metadata date
  • [x] Address review feedback - simplify section to brief statement + example
  • [x] Clarify multi-targeting recommendation to avoid TFM gaps
  • [x] Move IsAotCompatible multi-targeting guidance to AOT docs
  • [x] Update AOT docs to use net8.0 (earliest version with AOT compat analysis)
  • [x] Update SDK error messages to specify net6.0 for trimming, net8.0 for AOT
  • [x] Add recommendation to include latest .NET version for latest analyzer
  • [x] Update examples to use net10.0 as latest version
  • [x] Add Oxford commas to framework lists per writing style guidelines
  • [x] Break up long sentences for better readability
  • [x] Final review and validation

Summary

Per @sbomer's feedback:

  • Broke up long sentences in both trimming and AOT documentation sections for better readability
  • Changed structure to imperative mood: "if your library targets..., multi-target to..."
  • Split explanation into shorter, clearer sentences
  • Changed "Additionally, consider including" to "Also, include"
  • Changed "to ensure your library is analyzed" to "so your library is analyzed"
Original prompt

This section details on the original issue you should resolve

<issue_title>Prepare .NET libraries for trimming: Add multi-targeting H2 with our recommendations</issue_title> <issue_description> See this comment copied below

Finally, recently we've learned that multi-targeting is not only very common, but basically a must have when enabling trimming. (This is based on experience trying to make some NuGets trim compatible). I think the document should have a section about the multi-targeting and our recommendations around it. But the core point is that very few libraries will only target latest TFM. By far the most common case is either library targets netstandard2.0 or it multi-targets net472, netstandard2.0 and net6.0 (or some combination of these).

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

Comments on the Issue (you are @copilot in this section)

@sbomer Leaving a note here to mention the new behavior in the `true` part of https://learn.microsoft.com/dotnet/core/deploying/trimming/prepare-libraries-for-trimming. @sbomer I'm adding a breaking change notice that mentions multi-targeting: https://github.com/dotnet/docs/pull/36775. We still need a dedicated section in the general trimming docs though. When that's added, we should also link to it from the breaking change notice.
  • Fixes dotnet/docs#36730

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Internal previews

📄 File 🔗 Preview link
docs/core/deploying/native-aot/index.md Native AOT deployment
docs/core/deploying/trimming/prepare-libraries-for-trimming.md Prepare .NET libraries for trimming
docs/core/tools/sdk-errors/index.md .NET SDK error list

Copilot avatar Nov 20 '25 22:11 Copilot

@copilot Add a similar note for IsAotCompatible (alongside the existing docs for that option).

Added in 78f6612. The note directs users to apply the same multi-targeting guidance when using IsAotCompatible in multi-targeted projects, with a link to the "Multi-targeting for trimming" section.

Copilot avatar Dec 02 '25 21:12 Copilot

@copilot also adjust the warning text from the documentation for ".NET SDK error list" - the trimming one should mention 'net6.0' and the AOT one should mention 'net8.0'.

Updated in e033ba5. NETSDK1212 (trimming) now shows net6.0 and NETSDK1210 (AOT) now shows net8.0 in the example code.

Copilot avatar Dec 02 '25 22:12 Copilot