# Aot Trimming

Guidelines for making .NET libraries and applications trimming-safe and Native AOT...

- Repository: https://github.com/Aaronontheweb/dotnet-skills (1244 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Aaronontheweb/dotnet-skills --skill aot-trimming -g -a claude-code -y`
Codex: `npx skills add Aaronontheweb/dotnet-skills --skill aot-trimming -g -a codex -y`
Cursor: `npx skills add Aaronontheweb/dotnet-skills --skill aot-trimming -g -a cursor -y`
Gemini CLI: `npx skills add Aaronontheweb/dotnet-skills --skill aot-trimming -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Aaronontheweb/dotnet-skills`

## Description

Guidelines for making .NET libraries and applications trimming-safe and Native AOT compatible. Covers the trimming/AOT model, the MSBuild properties that enable analysis (IsTrimmable, IsAotCompatible, PublishTrimmed, PublishAot), the trimming attributes (RequiresUnreferencedCode, RequiresDynamicCode, DynamicallyAccessedMembers, UnconditionalSuppressMessage), IL2xxx/IL3xxx warning codes, and a pattern playbook: source generators and UnsafeAccessor, generated-interception diagnostic suppressors, intentional runtime scanning boundaries, trimming-safe islands and feature switches, migration analyzers, and temporary warning-approval baselines. Use when introducing trimming/AOT support, resolving IL2xxx/IL3xxx warnings, or making reflection-heavy code trimming-safe in C# / .NET codebases. For System.Text.Json AOT scenarios, see also the serialization skill.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# .NET Trimming and Native AOT

## When to Use

- Adding trimming (`PublishTrimmed`) or Native AOT (`PublishAot`) support to a library or application
- Resolving `IL2xxx` (trimming) and `IL3xxx` (AOT/single-file) warnings
- Making reflection-heavy code trimming-safe
- Replacing runtime reflection, assembly scanning, or `Reflection.Emit` with compile-time alternatives
- Reviewing a codebase or PR for trimming/AOT compatibility, including generated interceptors and analyzer suppressors
- Designing public APIs that must carry trimming annotations

## Core Goals

- Produce code that survives the linker's reachability analysis and runs under Native AOT (no JIT).
- Express what the compiler cannot see, which members reflection needs, using the trimming attributes.
- Keep trimming-safe and trimming-unsafe code separated so unsafe paths are explicit and contained.

## Core Model

### Trimming vs Native AOT

- **Trimming** (`PublishTrimmed`) runs ILLink reachability analysis: only statically reachable code is kept. Reflection the analyzer cannot see is trimmed away and produces warnings.
- **Native AOT** (`PublishAot`) makes trimming mandatory and removes the JIT. `Reflection.Emit` is unsupported, constructing *unknown* generic instantiations at runtime is not guaranteed, `Expression.Compile()` may fall back to interpretation, and reflection works only over members the linker preserved.
- Both run the same static analysis:
  - `IL2xxx`, trimming warnings: `RequiresUnreferencedCode` propagation + `DynamicallyAccessedMembers` dataflow.
  - `IL3xxx`, AOT and single-file warnings: `RequiresDynamicCode` / `RequiresAssemblyFiles`.

A library can be trimmable but **not** AOT-compatible (it uses `Reflection.Emit`, which trimming tolerates but AOT does not).

### The two problems to solve

The rest: https://github.com/Aaronontheweb/dotnet-skills/blob/HEAD/skills/aot-trimming/SKILL.md