AGENT SKILL

aot-trimming

Turn on PublishAot/PublishTrimmed in any .NET app; write or review trim/AOT-safe code and its IL warnings. Not for existing-library adoption or project-wide IL-warning migration: user-invoked dotnet-aot-compat.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 1
Forks
0

01 前言 Front Matter

name
aot-trimming
description
Turn on PublishAot/PublishTrimmed in any .NET app; write or review trim/AOT-safe code and its IL warnings. Not for existing-library adoption or project-wide IL-warning migration: user-invoked dotnet-aot-compat.
user-invocable
false

02 资源文件 2

03 SKILL.md 正文

.NET Trimming and Native AOT

This skill assumes trim/AOT analysis is already in effect for the code in scope, or that you are turning on PublishAot or PublishTrimmed in an app. To adopt IsTrimmable or IsAotCompatible in an existing library, or for a systematic migration of a project-wide IL-warning list, ask the user to invoke /deniz-dotnet-general:dotnet-aot-compat; do not perform that work through this skill.

When to Use

  • Turning on PublishAot or PublishTrimmed in an app, new or existing
  • Resolving the IL2xxx (trimming) and IL3xxx (AOT/single-file) warnings raised by the code you are writing or changing
  • 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

  1. Unseen reflection (trimming): the linker removes a member or type you load by name, or reach through typeof(T) in a generic method.
  2. Dynamic code generation (AOT): the JIT is gone, so Reflection.Emit is unsupported and constructing unknown generic instantiations is not guaranteed.

Both are solved the same way: make the required members statically visible to the analyzer, or remove the need for reflection entirely.

Reflection is not the enemy

Reflection is a legitimate technique and is completely fine in ordinary JIT applications — you need none of this there. The trimming attributes exist to allow reflection under trimming/AOT, not to forbid it: annotate what reflection needs, and the linker keeps it. Reach for source generators, [UnsafeAccessor], or capability gating only when you want a specific reflective surface removed or contained (for example, a public registration API you do not want to ship with [RequiresUnreferencedCode]).

Project Configuration

Declare the library properties only on a new library you are creating; adopting them in an existing library is the job of the manual ceremony named above. An app may turn on PublishTrimmed or PublishAot whether it is new or existing. When its publish raises a project-wide warning list rather than warnings in the code you are changing, migrating that list is the manual ceremony's job. For existing code, confirm what the project already declares before applying this guidance.

For a new library, declare compatibility so the analyzers surface warnings and consumers know:

<PropertyGroup>
  <!-- Trim-compatible: enables trim warnings. -->
  <IsTrimmable>true</IsTrimmable>

  <!-- AOT-compatible: implies IsTrimmable + EnableTrimAnalyzer + EnableSingleFileAnalyzer + EnableAotAnalyzer. -->
  <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">true</IsAotCompatible>
</PropertyGroup>

For an application, new or existing, publish trimmed or AOT:

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
  <!-- or -->
  <PublishAot>true</PublishAot>
</PropertyGroup>

Verify by actually publishing — a trimmed/AOT app must produce zero warnings:

dotnet publish -c Release -r <rid> -p:PublishTrimmed=true
dotnet publish -c Release -r <rid> -p:PublishAot=true

A test app that roots the library is the standard way to validate a library:

<PropertyGroup>
  <PublishTrimmed>true</PublishTrimmed>
</PropertyGroup>
<ItemGroup>
  <ProjectReference Include="..\MyLibrary\MyLibrary.csproj" />
  <TrimmerRootAssembly Include="MyLibrary" />
</ItemGroup>

See aot-trimming-playbook-reference.md for the full property table and feature switches.

The Attribute Model

These live in System.Diagnostics.CodeAnalysis. See trimming-attributes-reference.md for the full catalog with exact signatures, warning codes, and rules.

  • [RequiresUnreferencedCode(message)] — marks code that needs members the linker cannot see. Suppresses warnings inside; emits IL2026 at every call site.
  • [RequiresDynamicCode(message)] — marks code that needs a JIT (emitting, dynamic). Emits IL3050 at call sites.
  • [DynamicallyAccessedMembers(memberTypes)] — declares which members of a Type/string must be preserved. Flows backward from the reflection site to the Type source. Scope it (and the other attributes) to a single accessor by placing the attribute directly on the accessor, or with the [method:], [field:], or [return:] targets.
  • [UnconditionalSuppressMessage(category, checkId, Justification = "...")] — last-resort, IL-persisted suppression; must carry a justification and a real invariant.
  • [DynamicDependency("Member", typeof(T))] — keeps named members but does not silence warnings.

Choose the narrowest DynamicallyAccessedMemberTypes for the reflection you actually perform:

Reflection Member type
Activator.CreateInstance<T>(), new T(), Activator.CreateInstance(type) PublicParameterlessConstructor
DI activation (ActivatorUtilities.CreateFactory<T>) PublicConstructors
Explicit non-public activation NonPublicConstructors
type.GetInterfaces() Interfaces
type.GetMethods() PublicMethods (add NonPublicMethods when needed)
type.GetProperties() PublicProperties
type.GetFields() PublicFields
type.GetNestedTypes() PublicNestedTypes

The Pattern Playbook (selection)

First decide whether the code must be trimming/AOT safe at all. A plain JIT app or library needs none of this — reflection is fine there. Only when you or a consumer publish trimmed/AOT does reflection need to become visible to the linker.

The goal is never "remove all reflection"; it is make the reflection statically visible so the linker keeps what it needs. Choose per call site:

  • Keep the reflection and annotate it — the common case. Put [DynamicallyAccessedMembers(...)] on the Type/string source and propagate it through the chain; mark entry points [RequiresUnreferencedCode]/[RequiresDynamicCode]. The attributes exist precisely to let reflection work under trimming. See trimming-attributes-reference.md.

  • Replace the reflection with a compile-time alternative — when you want a reflective surface gone (for example, a public registration API you do not want to ship with [RequiresUnreferencedCode]). A source generator emits direct type references (marker attribute → generated registration); [UnsafeAccessor] replaces FieldInfo/MethodInfo/ConstructorInfo. See aot-trimming-playbook-reference.md and aot-trimming-playbook-reference.md.

  • Isolate a whole dynamic path — when a path is inherently dynamic (emitting proxies, loading plugins by name), move it behind a boundary and provide a trimming-safe alternative selected by RuntimeFeature.IsDynamicCodeSupported. See aot-trimming-playbook-reference.md.

  • Suppress only as a last resort — a single [UnconditionalSuppressMessage(...)] at an invariant-proven leaf, with a Justification. Never #pragma (not persisted in IL).

Inside the /deniz-dotnet-general:dotnet-aot-compat ceremony, its no-suppression rule governs. Outside it, a justified leaf [UnconditionalSuppressMessage] with a proven invariant and a Justification is allowed.

See aot-trimming-playbook-reference.md for the full playbook, including object-overload → generic-overload redirects, generated-interception suppressors, intentional scanning boundaries, migration analyzers, and strict-mode precedence.

Reference Files

  • trimming-attributes-reference.md: The complete attribute catalog — RequiresUnreferencedCode, RequiresDynamicCode, DynamicallyAccessedMembers (full DynamicallyAccessedMemberTypes list), UnconditionalSuppressMessage, DynamicDependency — each with intent, exact signature, and rules, plus the IL2xxx/IL3xxx warning-code table.
  • aot-trimming-playbook-reference.md: The full pattern playbook — source generators vs reflection, trimming-safe islands and capability guards, separating safe/unsafe code, System.Text.Json source generation, object-overload → generic-overload redirects with [OverloadResolutionPriority] and opt-in analyzers, migration analyzers, known gotchas, and the full generation checklist.

Generation Checklist (Summary)

  1. Project — trim/AOT analysis is already in effect for the code in scope, or you are creating a new library that declares IsTrimmable/IsAotCompatible, or turning on PublishTrimmed/PublishAot in an app; otherwise route the user to the manual ceremony. Zero warnings on publish.
  2. Make reflection visible (or replace it) — annotate the reflection you keep (DynamicallyAccessedMembers/RequiresUnreferencedCode/RequiresDynamicCode); replace it with source generators, generic (typeof(T)) APIs, or [UnsafeAccessor] only where you want the reflective surface gone.
  3. Annotate — narrowest DynamicallyAccessedMembers on every Type/string source; propagate through the chain; [RequiresUnreferencedCode]/[RequiresDynamicCode] on unsafe entry points.
  4. Isolate — keep unsafe reflective/emit code behind a boundary; gate dynamic-code paths with RuntimeFeature.IsDynamicCodeSupported, and separate trimming paths with #if or annotations.
  5. Suppress — only with [UnconditionalSuppressMessage] + justification at invariant-proven leaves; never #pragma/SuppressMessage.
  6. Verify — publish trimmed and AOT, run analyzers, and confirm zero warnings.

References

04 同仓库更多 Skills

Blind-Striker
Blind-Striker/agent-skills-and-plugins

writing-tunit-tests

Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

dotnet-walls

Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

csharp-15

Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

verified-waves

Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

harness

The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

delegating-to-worker-models

Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.

★ 1