Document IL2125 and IL3058 transitive reference compatibility warnings #50266

Copilot · 2025-12-02T19:06:09Z

Summary

Documents new analyzer warnings IL2125 and IL3058 introduced in dotnet/runtime#118180 for verifying transitive dependency compatibility with trimming and Native AOT.

New warning documentation:

IL2125: Referenced assembly is not annotated for trim compatibility - emitted when VerifyReferenceTrimCompatibility=true and a referenced assembly lacks IsTrimmable metadata
IL3058: Referenced assembly is not annotated for AOT compatibility - emitted when VerifyReferenceAotCompatibility=true and a referenced assembly lacks IsAotCompatible metadata

Updated conceptual documentation:

Added VerifyReferenceTrimCompatibility property to trim preparation guide
Added VerifyReferenceAotCompatibility property to Native AOT overview
Added note that IsAotCompatible metadata was introduced in .NET 10

Documentation approach:

Uses consistent terminology: "annotated for trim/AOT compatibility" throughout
Provides two options to fix violations: update the library or disable verification
Does not suggest warning suppression (these warnings cannot be suppressed at source location)
Includes ai-usage: ai-assisted disclosure in frontmatter per .NET documentation guidelines
Displays warning messages in separate blocks rather than inline comments, since these are compilation-level warnings that don't point to specific source lines

Both properties are opt-in, allowing library authors to enforce that all dependencies explicitly declare trim/AOT compatibility:

<PropertyGroup>
  <IsTrimmable>true</IsTrimmable>
  <VerifyReferenceTrimCompatibility>true</VerifyReferenceTrimCompatibility>
</PropertyGroup>

Original prompt

Clone dotnet/runtime#118180 and inspect the changes. Then write documentation for the new feature.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

docs/core/deploying/trimming/prepare-libraries-for-trimming.md

docs/core/deploying/native-aot/index.md

docs/core/deploying/native-aot/warnings/il3058.md

docs/core/deploying/trimming/trim-warnings/il2125.md

docs/core/deploying/native-aot/warnings/il3058.md

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

Copilot

Pull request overview

This PR documents two new analyzer warnings (IL2125 and IL3058) that verify transitive dependency compatibility with trimming and Native AOT. These warnings are emitted when verification properties are enabled and referenced assemblies lack the appropriate compatibility metadata attributes.

Key changes:

Adds IL2125 warning documentation for trim compatibility verification
Adds IL3058 warning documentation for AOT compatibility verification
Updates conceptual guides with new verification properties and usage guidance

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
`docs/core/deploying/trimming/trim-warnings/il2125.md`	New warning documentation for IL2125, explaining when it's emitted and how to fix it
`docs/core/deploying/native-aot/warnings/il3058.md`	New warning documentation for IL3058, explaining AOT compatibility verification
`docs/core/deploying/trimming/prepare-libraries-for-trimming.md`	Adds section on `VerifyReferenceTrimCompatibility` property with usage guidance
`docs/core/deploying/native-aot/index.md`	Adds section on `VerifyReferenceAotCompatibility` property, including note about .NET 10 introduction

docs/core/deploying/trimming/prepare-libraries-for-trimming.md

docs/core/deploying/native-aot/index.md

docs/core/deploying/trimming/trim-warnings/il2125.md

docs/core/deploying/native-aot/warnings/il3058.md

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

docs/core/deploying/native-aot/warnings/il3058.md

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

gewarren · 2025-12-05T00:38:50Z

docs/core/deploying/trimming/trim-warnings/il2125.md

+---
+title: "IL2125: Referenced assembly is not annotated for trim compatibility"
+description: "Learn about trim warning IL2125: Referenced assembly is not annotated for trim compatibility"
+ms.date: 12/02/2024


Suggested change

ms.date: 12/02/2024

ms.date: 12/02/2025

gewarren · 2025-12-05T00:40:30Z

docs/core/deploying/trimming/trim-warnings/il2125.md

+1. **Update the referenced library** to be built with `<IsTrimmable>true</IsTrimmable>`. This is the preferred approach if you control the library source code. See [Prepare .NET libraries for trimming](../prepare-libraries-for-trimming.md) for guidance on making libraries trim-compatible.
+
+2. **Disable the verification** by setting `<VerifyReferenceTrimCompatibility>false</VerifyReferenceTrimCompatibility>` in your project file if you're confident that the library works correctly with trimming even without the attribute.


Suggested change

1. **Update the referenced library** to be built with `<IsTrimmable>true</IsTrimmable>`. This is the preferred approach if you control the library source code. See [Prepare .NET libraries for trimming](../prepare-libraries-for-trimming.md) for guidance on making libraries trim-compatible.

2. **Disable the verification** by setting `<VerifyReferenceTrimCompatibility>false</VerifyReferenceTrimCompatibility>` in your project file if you're confident that the library works correctly with trimming even without the attribute.

- **Update the referenced library** to be built with `<IsTrimmable>true</IsTrimmable>`. This is the preferred approach if you control the library source code. For guidance on making libraries trim-compatible, see [Prepare .NET libraries for trimming](../prepare-libraries-for-trimming.md).

- **Disable the verification** by setting `<VerifyReferenceTrimCompatibility>false</VerifyReferenceTrimCompatibility>` in your project file if you're confident that the library works correctly with trimming even without the attribute.

gewarren · 2025-12-05T00:40:52Z

docs/core/deploying/native-aot/warnings/il3058.md

+---
+title: "IL3058: Referenced assembly is not annotated for AOT compatibility"
+description: "Learn about warning IL3058: Referenced assembly is not annotated for AOT compatibility"
+ms.date: 12/02/2024


Suggested change

ms.date: 12/02/2024

ms.date: 12/02/2025

gewarren · 2025-12-05T00:42:01Z

docs/core/deploying/native-aot/warnings/il3058.md

+1. **Update the referenced library** to be built with `<IsAotCompatible>true</IsAotCompatible>`. This is the preferred approach if you control the library source code. The `IsAotCompatible` property marks the assembly as compatible with Native AOT and enables AOT-specific analysis.
+
+2. **Disable the verification** by setting `<VerifyReferenceAotCompatibility>false</VerifyReferenceAotCompatibility>` in your project file if you're confident that the library works correctly with Native AOT even without the attribute.


Suggested change

1. **Update the referenced library** to be built with `<IsAotCompatible>true</IsAotCompatible>`. This is the preferred approach if you control the library source code. The `IsAotCompatible` property marks the assembly as compatible with Native AOT and enables AOT-specific analysis.

2. **Disable the verification** by setting `<VerifyReferenceAotCompatibility>false</VerifyReferenceAotCompatibility>` in your project file if you're confident that the library works correctly with Native AOT even without the attribute.

- **Update the referenced library** to be built with `<IsAotCompatible>true</IsAotCompatible>`. This is the preferred approach if you control the library source code. The `IsAotCompatible` property marks the assembly as compatible with Native AOT and enables AOT-specific analysis.

- **Disable the verification** by setting `<VerifyReferenceAotCompatibility>false</VerifyReferenceAotCompatibility>` in your project file if you're confident that the library works correctly with Native AOT even without the attribute.

jtschuster · 2025-12-06T01:37:30Z

docs/core/deploying/native-aot/warnings/il3058.md

+
+## Rule description
+
+When you enable AOT analysis with `<EnableAotAnalyzer>true</EnableAotAnalyzer>` or mark your project as AOT-compatible with `<IsAotCompatible>true</IsAotCompatible>`, you can optionally enable verification that all referenced assemblies are also annotated for AOT compatibility. This helps ensure that all dependencies in your project are annotated for AOT compatibility.


nit: also when <PublishAOT>true</PublishAOT> is set?

jtschuster · 2025-12-06T01:38:57Z

docs/core/deploying/trimming/trim-warnings/il2125.md

+
+## Rule description
+
+When you enable trim analysis with `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` or mark your project as trimmable with `<IsTrimmable>true</IsTrimmable>`, you can optionally enable verification that all referenced assemblies are also annotated for trim compatibility. This helps ensure that all dependencies in your project are annotated for trim compatibility.


nit: here too, trim analysis is enabled with PublishTrimmed=true

Initial plan

3ec08d1

Copilot AI assigned Copilot and sbomer Dec 2, 2025

Copilot started work on behalf of sbomer December 2, 2025 19:06 View session

Add documentation for IL2125 and IL3058 transitive reference warnings

07c49f1

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

dotnet-policy-service bot added the dotnet-fundamentals/svc label Dec 2, 2025

Copilot AI changed the title ~~[WIP] Add documentation for new feature~~ Document IL2125 and IL3058 transitive reference compatibility warnings Dec 2, 2025

Copilot AI requested a review from sbomer December 2, 2025 19:20

Copilot finished work on behalf of sbomer December 2, 2025 19:20

sbomer reviewed Dec 2, 2025

View reviewed changes

Copilot started work on behalf of sbomer December 2, 2025 19:34 View session

Copilot AI and others added 4 commits December 2, 2025 19:37

Address PR feedback: Update terminology and remove suppression guidance

5a84e99

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

Update frontmatter titles to match heading terminology

d7b36c9

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

Fix hyphenation for consistency in terminology

af0c6e5

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

Ensure consistent terminology throughout all documentation

b7f9860

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

Copilot AI requested a review from sbomer December 2, 2025 19:43

Copilot finished work on behalf of sbomer December 2, 2025 19:43

sbomer approved these changes Dec 4, 2025

View reviewed changes

sbomer requested a review from a team December 4, 2025 23:14

sbomer marked this pull request as ready for review December 4, 2025 23:14

sbomer requested review from a team and adegeo as code owners December 4, 2025 23:14

Copilot AI review requested due to automatic review settings December 4, 2025 23:14

Copilot started reviewing on behalf of sbomer December 4, 2025 23:14 View session

Copilot finished reviewing on behalf of sbomer December 4, 2025 23:16

Copilot AI reviewed Dec 4, 2025

View reviewed changes

Copilot started work on behalf of sbomer December 4, 2025 23:47 View session

Add ai-usage disclosure to frontmatter

dd89415

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

Copilot AI requested a review from sbomer December 4, 2025 23:52

Copilot finished work on behalf of sbomer December 4, 2025 23:52

Copilot started work on behalf of sbomer December 4, 2025 23:52 View session

sbomer approved these changes Dec 4, 2025

View reviewed changes

sbomer reviewed Dec 4, 2025

View reviewed changes

docs/core/deploying/native-aot/warnings/il3058.md Outdated Show resolved Hide resolved

Copilot AI requested a review from sbomer December 4, 2025 23:55

Copilot finished work on behalf of sbomer December 4, 2025 23:55

Copilot started work on behalf of sbomer December 4, 2025 23:55 View session

Show warnings in separate blocks instead of inline comments

ddfdc9a

Co-authored-by: sbomer <787361+sbomer@users.noreply.github.com>

Copilot finished work on behalf of sbomer December 4, 2025 23:59

sbomer approved these changes Dec 5, 2025

View reviewed changes

sbomer requested a review from a team December 5, 2025 00:03

gewarren approved these changes Dec 5, 2025

View reviewed changes

jtschuster approved these changes Dec 6, 2025

View reviewed changes

		1. Update the referenced library to be built with `<IsTrimmable>true</IsTrimmable>`. This is the preferred approach if you control the library source code. See [Prepare .NET libraries for trimming](../prepare-libraries-for-trimming.md) for guidance on making libraries trim-compatible.

		2. Disable the verification by setting `<VerifyReferenceTrimCompatibility>false</VerifyReferenceTrimCompatibility>` in your project file if you're confident that the library works correctly with trimming even without the attribute.


		## Rule description

		When you enable AOT analysis with `<EnableAotAnalyzer>true</EnableAotAnalyzer>` or mark your project as AOT-compatible with `<IsAotCompatible>true</IsAotCompatible>`, you can optionally enable verification that all referenced assemblies are also annotated for AOT compatibility. This helps ensure that all dependencies in your project are annotated for AOT compatibility.


		## Rule description

		When you enable trim analysis with `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` or mark your project as trimmable with `<IsTrimmable>true</IsTrimmable>`, you can optionally enable verification that all referenced assemblies are also annotated for trim compatibility. This helps ensure that all dependencies in your project are annotated for trim compatibility.

Document IL2125 and IL3058 transitive reference compatibility warnings #50266

Are you sure you want to change the base?

Document IL2125 and IL3058 transitive reference compatibility warnings #50266

Conversation

Copilot AI commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gewarren Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

gewarren Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

gewarren Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

gewarren Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

jtschuster Dec 6, 2025

Choose a reason for hiding this comment

Uh oh!

jtschuster Dec 6, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Dec 2, 2025 •

edited

Loading