Document IL2125 and IL3058 transitive reference compatibility warnings

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

@@ -107,6 +107,26 @@ The preceding configuration assigns a default of `true` to the following propert
 
 These analyzers help to ensure that a library is compatible with Native AOT.
 
+### Verify referenced assemblies are AOT-compatible
+
+When you enable AOT analysis for a library, you can optionally enable verification that all referenced assemblies are also marked as AOT-compatible by setting the `VerifyReferenceAotCompatibility` property to `true`:
+
+```xml
+<PropertyGroup>
+  <IsAotCompatible>true</IsAotCompatible>
+  <VerifyReferenceAotCompatibility>true</VerifyReferenceAotCompatibility>
+</PropertyGroup>
+```
+
+When this property is enabled, the analyzer warns about any referenced assemblies that don't have the `IsAotCompatible` metadata. This helps ensure that all dependencies in your project are compatible with Native AOT. The warning that's emitted is [IL3058](warnings/il3058.md).
+
+This verification is opt-in because:
+
+- Not all AOT-compatible libraries have been updated to include the `IsAotCompatible` metadata.
+- The warning can be noisy if you have many dependencies that work correctly with Native AOT but aren't explicitly marked as such.
+
+Consider enabling this verification when you want to ensure that all your dependencies are explicitly marked as AOT-compatible by their authors.
+
 ## Native debug information
 
 By default, Native AOT publishing produces debug information in a separate file:

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

@@ -0,0 +1,69 @@
+---
+title: "IL3058: Referenced assembly is not marked as AOT-compatible"
+description: "Learn about warning IL3058: Referenced assembly is not marked as AOT-compatible"
+ms.date: 12/02/2024
+f1_keywords:
+  - "IL3058"
+---
+# IL3058: Referenced assembly is not marked as AOT-compatible
+
+## Cause
+
+A project has `<VerifyReferenceAotCompatibility>true</VerifyReferenceAotCompatibility>` set, and one or more referenced assemblies don't have the `IsAotCompatible` assembly metadata attribute set to `true`.
+
+## 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 marked as AOT-compatible. This helps ensure that all dependencies in your project are compatible with Native AOT compilation.
+
+To enable this verification, set the `VerifyReferenceAotCompatibility` property to `true` in your project file:
+
+```xml
+<PropertyGroup>
+  <EnableAotAnalyzer>true</EnableAotAnalyzer>
+  <VerifyReferenceAotCompatibility>true</VerifyReferenceAotCompatibility>
+</PropertyGroup>
+```
+
+When this property is enabled, the analyzer checks that all referenced assemblies have been built with `<IsAotCompatible>true</IsAotCompatible>`, which adds the assembly-level attribute `[assembly: AssemblyMetadata("IsAotCompatible", "True")]` to the assembly.
+
+## Example
+
+```csharp
+// Assembly reference: MyLibrary.dll (built without <IsAotCompatible>true</IsAotCompatible>)
+
+public class Program
+{
+    public static void Main()
+    {
+        // IL3058: Referenced assembly 'MyLibrary' is not built with `<IsAotCompatible>true</IsAotCompatible>`
+        // and may not be compatible with AOT.
+        var obj = new MyLibrary.SomeClass();
+    }
+}
+```
+
+## How to fix violations
+
+You have several options to fix this warning:
+
+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.
+
+3. **Suppress the warning** for specific assemblies using `#pragma warning disable IL3058` or the `UnconditionalSuppressMessageAttribute` if you've verified that the specific library is safe to use with Native AOT.
+
+## When to suppress warnings
+
+It's safe to suppress this warning if:
+
+- You've tested the referenced library with Native AOT and verified it works correctly.
+- The referenced library doesn't use reflection, dynamic code generation, or other features that are incompatible with Native AOT.
+- You're using a legacy library that works with Native AOT but wasn't built with the `IsAotCompatible` property.
+
+However, be aware that suppressing this warning means the library hasn't been explicitly marked as AOT-compatible by its author, so there's a risk of runtime failures if the library uses features that require runtime code generation or other capabilities not available in Native AOT.
+
+## See also
+
+- [Native AOT deployment](../index.md)
+- [Introduction to AOT warnings](../fixing-warnings.md)
+- [Prepare .NET libraries for trimming](../../trimming/prepare-libraries-for-trimming.md)

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

@@ -41,6 +41,26 @@ The `IsTrimmable` property defaults to `true` when configuring a project as AOT-
 
 To generate trim warnings without marking the project as trim-compatible, use `<EnableTrimAnalyzer>true</EnableTrimAnalyzer>` rather than `<IsTrimmable>true</IsTrimmable>`.
 
+#### Verify referenced assemblies are trim-compatible
+
+When you enable trim analysis for a library, you can optionally enable verification that all referenced assemblies are also marked as trim-compatible by setting the `VerifyReferenceTrimCompatibility` property to `true`:
+
+```xml
+<PropertyGroup>
+  <IsTrimmable>true</IsTrimmable>
+  <VerifyReferenceTrimCompatibility>true</VerifyReferenceTrimCompatibility>
+</PropertyGroup>
+```
+
+When this property is enabled, the analyzer warns about any referenced assemblies that don't have the `IsTrimmable` metadata. This helps ensure that all dependencies in your project are compatible with trimming. The warning that's emitted is [IL2125](trim-warnings/il2125.md).
+
+This verification is opt-in because:
+
+- Not all trim-compatible libraries have been updated to include the `IsTrimmable` metadata.
+- The warning can be noisy if you have many dependencies that work correctly with trimming but aren't explicitly marked as such.
+
+Consider enabling this verification when you want to ensure that all your dependencies are explicitly marked as trim-compatible by their authors.
+
 ### Show all warnings with test app
 
 To show all analysis warnings for a library, the trimmer must analyze the implementation of the library and of all dependencies the library uses.

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

@@ -0,0 +1,69 @@
+---
+title: "IL2125: Referenced assembly is not marked as trimmable"
+description: "Learn about trim warning IL2125: Referenced assembly is not marked as trimmable"
+ms.date: 12/02/2024
+f1_keywords:
+  - "IL2125"
+---
+# IL2125: Referenced assembly is not marked as trimmable
+
+## Cause
+
+A project has `<VerifyReferenceTrimCompatibility>true</VerifyReferenceTrimCompatibility>` set, and one or more referenced assemblies don't have the `IsTrimmable` assembly metadata attribute set to `true`.
+
+## 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 marked as trimmable. This helps ensure that all dependencies in your project are compatible with trimming.
+
+To enable this verification, set the `VerifyReferenceTrimCompatibility` property to `true` in your project file:
+
+```xml
+<PropertyGroup>
+  <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
+  <VerifyReferenceTrimCompatibility>true</VerifyReferenceTrimCompatibility>
+</PropertyGroup>
+```
+
+When this property is enabled, the analyzer checks that all referenced assemblies have been built with `<IsTrimmable>true</IsTrimmable>`, which adds the assembly-level attribute `[assembly: AssemblyMetadata("IsTrimmable", "True")]` to the assembly.
+
+## Example
+
+```csharp
+// Assembly reference: MyLibrary.dll (built without <IsTrimmable>true</IsTrimmable>)
+
+public class Program
+{
+    public static void Main()
+    {
+        // IL2125: Referenced assembly 'MyLibrary' is not built with `<IsTrimmable>true</IsTrimmable>`
+        // and may not be compatible with trimming.
+        var obj = new MyLibrary.SomeClass();
+    }
+}
+```
+
+## How to fix violations
+
+You have several options to fix this warning:
+
+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.
+
+3. **Suppress the warning** for specific assemblies using `#pragma warning disable IL2125` or the `UnconditionalSuppressMessageAttribute` if you've verified that the specific library is safe to use with trimming.
+
+## When to suppress warnings
+
+It's safe to suppress this warning if:
+
+- You've tested the referenced library with trimming enabled and verified it works correctly.
+- The referenced library doesn't use reflection or other dynamic features that could be affected by trimming.
+- You're using a legacy library that works with trimming but wasn't built with the `IsTrimmable` property.
+
+However, be aware that suppressing this warning means the library hasn't been explicitly marked as trim-compatible by its author, so there's a risk of runtime failures if the library uses features that are incompatible with trimming.
+
+## See also
+
+- [Prepare .NET libraries for trimming](../prepare-libraries-for-trimming.md)
+- [Introduction to trim warnings](../fixing-warnings.md)
+- [Trim self-contained deployments and executables](../trim-self-contained.md)