diff --git a/docs/core/deploying/native-aot/index.md b/docs/core/deploying/native-aot/index.md index bb07bd14be2d8..5f7afd500e8e9 100644 --- a/docs/core/deploying/native-aot/index.md +++ b/docs/core/deploying/native-aot/index.md @@ -107,6 +107,29 @@ 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 annotated for AOT compatibility by setting the `VerifyReferenceAotCompatibility` property to `true`: + +```xml + + true + true + +``` + +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 annotated for Native AOT compatibility. 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. + +> [!NOTE] +> The `IsAotCompatible` assembly metadata was introduced in .NET 10. Libraries that were published targeting earlier versions of .NET won't have this attribute, even if they were built with `true`. + +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: diff --git a/docs/core/deploying/native-aot/warnings/il3058.md b/docs/core/deploying/native-aot/warnings/il3058.md new file mode 100644 index 0000000000000..fee3a1005a9b5 --- /dev/null +++ b/docs/core/deploying/native-aot/warnings/il3058.md @@ -0,0 +1,60 @@ +--- +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 +ai-usage: ai-assisted +f1_keywords: + - "IL3058" +--- +# IL3058: Referenced assembly is not annotated for AOT compatibility + +## Cause + +A project has `true` 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 `true` or mark your project as AOT-compatible with `true`, 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. + +To enable this verification, set the `VerifyReferenceAotCompatibility` property to `true` in your project file: + +```xml + + true + true + +``` + +When this property is enabled, the analyzer checks that all referenced assemblies have been built with `true`, which adds the assembly-level attribute `[assembly: AssemblyMetadata("IsAotCompatible", "True")]` to the assembly. + +## Example + +```csharp +// Assembly reference: MyLibrary.dll (built without true) + +public class Program +{ + public static void Main() + { + var obj = new MyLibrary.SomeClass(); + } +} +``` + +``` +warning IL3058: Referenced assembly 'MyLibrary' is not built with `true` and may not be compatible with AOT. +``` + +## How to fix violations + +You have several options to fix this warning: + +1. **Update the referenced library** to be built with `true`. 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 `false` in your project file if you're confident that the library works correctly with Native AOT even without the attribute. + +## 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) diff --git a/docs/core/deploying/trimming/prepare-libraries-for-trimming.md b/docs/core/deploying/trimming/prepare-libraries-for-trimming.md index 8185473604f72..2966ad978ad41 100644 --- a/docs/core/deploying/trimming/prepare-libraries-for-trimming.md +++ b/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 `true` rather than `true`. +#### 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 annotated for trim compatibility by setting the `VerifyReferenceTrimCompatibility` property to `true`: + +```xml + + true + true + +``` + +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 annotated for trim compatibility. 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. diff --git a/docs/core/deploying/trimming/trim-warnings/il2125.md b/docs/core/deploying/trimming/trim-warnings/il2125.md new file mode 100644 index 0000000000000..5c0ea1fa71f58 --- /dev/null +++ b/docs/core/deploying/trimming/trim-warnings/il2125.md @@ -0,0 +1,60 @@ +--- +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 +ai-usage: ai-assisted +f1_keywords: + - "IL2125" +--- +# IL2125: Referenced assembly is not annotated for trim compatibility + +## Cause + +A project has `true` 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 `true` or mark your project as trimmable with `true`, 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. + +To enable this verification, set the `VerifyReferenceTrimCompatibility` property to `true` in your project file: + +```xml + + true + true + +``` + +When this property is enabled, the analyzer checks that all referenced assemblies have been built with `true`, which adds the assembly-level attribute `[assembly: AssemblyMetadata("IsTrimmable", "True")]` to the assembly. + +## Example + +```csharp +// Assembly reference: MyLibrary.dll (built without true) + +public class Program +{ + public static void Main() + { + var obj = new MyLibrary.SomeClass(); + } +} +``` + +``` +warning IL2125: Referenced assembly 'MyLibrary' is not built with `true` and may not be compatible with trimming. +``` + +## How to fix violations + +You have several options to fix this warning: + +1. **Update the referenced library** to be built with `true`. 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 `false` in your project file if you're confident that the library works correctly with trimming even without the attribute. + +## 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)