dotnet-aot-compat

When to Use This Skill

• "Make this project AOT-compatible"
• "Fix trimming warnings" or "fix IL warnings"
• "Resolve IL2070 / IL2067 / IL2072 / IL2026 / IL3050 warnings"
• "Add DynamicallyAccessedMembers annotations"
• "Enable IsAotCompatible in my .csproj"
• "My project has trim analyzer warnings after upgrading to net8.0"
• "Annotate reflection code for the trimmer"

When Not to Use This Skill

Prerequisites

Background: What AOT Compatibility Means

Critical Rules

❌ Never suppress warnings incorrectly

• NEVER use #pragma warning disable for IL warnings. It hides warnings from the Roslyn analyzer at build time, but the IL linker and AOT compiler still see the issue. The code will fail at trim/publish time.
• NEVER use [UnconditionalSuppressMessage]. It tells both the analyzer AND the linker to ignore the warning, meaning the trimmer cannot verify safety. Raising an error at build time is always preferable to hiding the issue and having it silently break at runtime.

💡 Preferred approaches

• Prefer [DynamicallyAccessedMembers] annotations to flow type information through the call chain.
• Prefer refactoring to eliminate patterns that break annotation flow (e.g., boxing Type through object[]).
• Use [RequiresUnreferencedCode] / [RequiresDynamicCode] / [RequiresAssemblyFiles] to mark methods as fundamentally incompatible with trimming, propagating the requirement to callers. This surfaces the issue clearly rather than hiding it — callers must explicitly acknowledge the incompatibility.

Annotation flow is key

Step-by-Step Procedure

Do not explore the codebase up-front. The build warnings tell you exactly which files and lines need changes. Follow a tight loop: build → pick a warning → open that file at that line → apply the fix recipe → rebuild. Reading or analyzing source files beyond what a specific warning points you to is wasted effort and leads to timeouts. Let the compiler guide you.

❌ Do NOT run find, ls, or grep to understand the project structure before building. Do NOT read README, docs, or architecture files. Your first action should be Step 1 (enable AOT analysis), then build.

Step 1: Enable AOT analysis in the .csproj

<PropertyGroup>
  <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">true</IsAotCompatible>
</PropertyGroup>

Step 2: Build and collect warnings

dotnet build <project.csproj> -f <net8.0-or-later-tfm> --no-incremental 2>&1 | grep 'IL[0-9]\{4\}'

• IL2070: Reflection call on a Type parameter missing [DynamicallyAccessedMembers]
• IL2067: Passing an unannotated Type to a method expecting [DynamicallyAccessedMembers]
• IL2072: Return value or extracted value missing annotation (often from unboxing)
• IL2057: Type.GetType(string) with a non-constant argument
• IL2026: Calling a method marked [RequiresUnreferencedCode]
• IL2050: P/invoke method with COM marshalling parameters
• IL2075: Return value flows into reflection without annotation
• IL2091: Generic argument missing [DynamicallyAccessedMembers] required by constraint
• IL3000: Assembly.Location returns empty string in single-file/AOT apps
• IL3050: Calling a method marked [RequiresDynamicCode]

Step 3: Triage warnings by code (do NOT read every file)

Step 4: Fix warnings iteratively (innermost first)

Update these files to use source-generated JSON: src/Models/Resource.Serialization.cs, src/Models/Identity.Serialization.cs, src/Models/Plan.Serialization.cs. In each file, replace JsonSerializer.Serialize(writer, value) with JsonSerializer.Serialize(writer, value, MyProjectJsonContext.Default.TypeName) and JsonSerializer.Deserialize<T>(ref reader) with JsonSerializer.Deserialize(ref reader, MyProjectJsonContext.Default.TypeName). Only edit the JsonSerializer call sites.

Strategy A: Add [DynamicallyAccessedMembers] (preferred)

using System.Diagnostics.CodeAnalysis;

// Before (warns IL2070):
void Process(Type t) {
    var method = t.GetMethod("Foo");  // trimmer can't verify
}

// After (clean):
void Process([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)] Type t) {
    var method = t.GetMethod("Foo");  // trimmer preserves public methods
}

Strategy B: Refactor to preserve annotation flow

// BROKEN: Type boxed into object[], annotation lost
void Process(object[] args) {
    Type t = (Type)args[0];  // IL2072: annotation lost through boxing
    Evaluate(t, ...);
}

// FIXED: Pass Type as a separate, annotated parameter
void Process(
    object[] args,
    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)] Type calleeType,
    ...) {
    Evaluate(calleeType, ...);  // annotation flows cleanly
}

• object[] parameter bags: Extract the Type into a dedicated annotated parameter
• Dictionary/List storage: Use a typed field with annotation instead
• Interface indirection: Add annotation to the interface method's parameter
• Property with boxing getter: Annotate the property's return type

Strategy C: Source-generated JSON serialization (batch fix)

1. Collect affected types — grep for all JsonSerializer.Serialize and JsonSerializer.Deserialize call sites. Extract the type being serialized (the <T> in Deserialize<T>, or the runtime type of the object in Serialize).
2. Create one JsonSerializerContext with [JsonSerializable] for every type found. Skip types from external packages (e.g., ResponseError from Azure.Core) — they won't source-generate for types you don't own. Handle external types separately via Gotcha #1 below.

[JsonSerializerContext]
[JsonSerializable(typeof(ManagedServiceIdentity))]
[JsonSerializable(typeof(SystemData))]
// ... one attribute per type YOU OWN
// Do NOT add types from external packages (e.g., ResponseError)
internal partial class MyProjectJsonContext : JsonSerializerContext { }

1. Batch-update all call sites — do not read each file individually. Apply the pattern mechanically:
   • JsonSerializer.Serialize(obj) → JsonSerializer.Serialize(obj, MyProjectJsonContext.Default.TypeName)
   • JsonSerializer.Deserialize<T>(json) → JsonSerializer.Deserialize(json, MyProjectJsonContext.Default.TypeName)
   Find and update all call sites in one pass:
   bashCopy

   # Find all files with JsonSerializer calls
   grep -rl 'JsonSerializer\.\(Serialize\|Deserialize\)' src/ --include='*.cs'

   Then use sequential edit calls to apply the same transformation to every matching file. Do not use sed for C# code — generics like Deserialize<T>() have angle brackets and nested parentheses that sed will mangle.
2. Build once to verify. Remaining warnings will be non-serialization issues — handle those with Strategies A–B or D.

Strategy D: [RequiresUnreferencedCode] (last resort)

[RequiresUnreferencedCode("Loads plugins by name using Assembly.Load")]
public void LoadPlugin(string assemblyName) {
    var asm = Assembly.Load(assemblyName);
    // ...
}

Step 5: Rebuild and repeat

Step 6: Validate all TFMs

• 0 IL warnings on net8.0+ TFMs
• No NETSDK1210 warnings (the IsAotCompatible condition handles this)
• Clean builds on older TFMs (netstandard2.0, net472, etc.)

dotnet build <project.csproj>  # builds all TFMs

Stop Signals

• Do not analyze more than 2-3 representative files per warning pattern. After identifying the fix for a pattern, apply it to all matching files without reading each one first.
• Start fixing after one build. Do not do a second analysis pass — begin implementing fixes for the most common warning pattern immediately after Step 3 triage.
• Stop after achieving 0 IL warnings for net8.0+ TFMs. Don't optimize or refactor already-clean annotations.
• If a warning requires architectural refactoring beyond annotation flow fixes (e.g., replacing an entire serialization layer), document it and stop — don't rewrite large subsystems.
• Limit to 3 build-fix iterations per warning. If annotation flow doesn't resolve it after 3 attempts, escalate to [RequiresUnreferencedCode].
• Don't chase warnings in third-party dependencies you can't modify. Note them and move on.
• If the user asked a scoped question (e.g., "fix warnings in this file"), don't expand to the entire project.

Polyfills for Older TFMs

Common Gotchas

1. External types without AOT-safe serialization: When a type comes from a dependency you can't modify (e.g., ResponseError from Azure.Core) and it lacks a source-generated serializer, Options.GetConverter<T>() is reflection-based and will produce IL warnings. First check if the type implements IJsonModel<T> (common in Azure SDK) — if so, bypass JsonSerializer entirely:

// Before (IL2026 — JsonSerializer uses reflection):
JsonSerializer.Serialize(writer, errorValue);

// After (AOT-safe — uses IJsonModel directly):
((IJsonModel<ResponseError>)errorValue).Write(writer, ModelReaderWriterOptions.Json);

// For deserialization:
var error = ((IJsonModel<ResponseError>)new ResponseError()).Create(ref reader, ModelReaderWriterOptions.Json);

1. Serialization libraries: Most reflection-based serializers (e.g., Newtonsoft.Json, XmlSerializer) are not AOT-compatible. Migrate to a source-generation-based serializer such as System.Text.Json with a JsonSerializerContext. If migration is not feasible, mark the serialization call site with [RequiresUnreferencedCode].
2. Shared projects / projitems: When source is shared between multiple projects via <Import>, annotations added to shared code affect ALL consuming projects. Verify that all consumers still build cleanly.

References

Checklist

• Added <IsAotCompatible> with TFM condition to .csproj
• Built with AOT analyzers enabled (net8.0+ TFM)
• Fixed all IL warnings via annotations or refactoring
• No #pragma warning disable or [UnconditionalSuppressMessage] used for any IL warning
• Polyfills present for older TFMs if needed
• All target frameworks build with 0 warnings
• Verified shared/linked source doesn't break sibling projects