`PublishAot=true` fails because ILC still scans base Dapper.dll — proposal: AOT-annotated stubs

Problem

When using Dapper.AOT with PublishAot=true, native compilation fails because ILC scans Dapper.dll and finds AOT-incompatible code:

error IL3050: DynamicMethod is not supported by AOT
error IL3050: Type.MakeGenericType() requires dynamic code
error IL2070: Type.GetProperties() requires DynamicallyAccessedMembers
error IL2046: ICustomTypeDescriptor without RequiresUnreferencedCode

Dapper.AOT interceptors correctly replace all SqlMapper calls at compile time, so the base Dapper code is never executed at runtime. However, ILC still scans the entire Dapper.dll assembly and treats the 45+ trim/AOT warnings as fatal errors.

Reproduction

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <PublishAot>true</PublishAot>
    <PublishTrimmed>true</PublishTrimmed>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Dapper" Version="2.1.66" />
    <PackageReference Include="Dapper.AOT" Version="1.0.48" />
  </ItemGroup>
</Project>

using Dapper;
using System.Data.Common;

[DapperAot]
static class Queries
{
    public static Product GetProduct(DbConnection connection, int id)
        => connection.QueryFirst<Product>("select @id as Id", new { id });
}

record Product(int Id);

dotnet publish -c Release
# Fails with IL3050/IL2070/IL2046 errors from Dapper.dll

Root cause

The getting started docs state: "Your project still needs to reference Dapper, so we can see what your code is trying to do."

This is correct — Dapper.AOT needs the SqlMapper type signatures to detect and intercept calls. But this also means Dapper.dll ends up in the output, and ILC scans it. Since Dapper uses Reflection.Emit, MakeGenericType(), etc., ILC produces fatal warnings.

The interceptors work perfectly — the generated code uses CommandFactory<T> and RowFactory<T> directly, bypassing SqlMapper entirely. The problem is purely that ILC sees the unreachable base Dapper code and rejects it.

Proposed solution: AOT-annotated stubs

I've implemented and tested a solution: a minimal Dapper.Stubs assembly that provides the same public API surface as Dapper.dll but with:

1. Empty method bodies (throw new NotSupportedException) — they are never called because interceptors replace all call sites
2. AOT annotations ([RequiresDynamicCode] + [RequiresUnreferencedCode]) on every method — ILC sees these and trims the unreachable code cleanly
3. Working GridReader base class — because AotGridReader extends it and calls OnBeforeGrid/OnAfterGrid at runtime
4. Working DbString — because the generated DbStringHelpers reads its properties at runtime
5. IWrappedDataReader interface — referenced by generated AotWrappedDbDataReader

Result

With Dapper.Stubs replacing Dapper:

• dotnet publish -c Release succeeds with zero ILC warnings
• The native binary is produced and runs correctly
• No code changes required in user projects — just swap the package reference
• Existing non-AOT projects continue using real Dapper unchanged

How users would use it

<!-- For AOT projects, replace: -->
<PackageReference Include="Dapper" Version="2.1.66" />

<!-- With: -->
<PackageReference Include="Dapper.AOT.Stubs" Version="..." />

Or even better — Dapper.AOT could auto-substitute via MSBuild targets when PublishAot=true is detected.

Questions for maintainers

1. Is this something you'd want integrated into the DapperAOT repo? I'm happy to submit a PR adapting the code to fit your project structure.

2. Would you prefer a different approach? For example:

   • A .targets file in Dapper.AOT that excludes Dapper.dll from ILC scanning
   • ILLink.Substitutions.xml to suppress specific warnings
   • Something else entirely

3. If a PR is welcome, where should the stubs project live? I'd suggest src/Dapper.AOT.Stubs/ with AssemblyName=Dapper, published as a separate NuGet package.

Implementation

My working implementation is at: https://github.com/Harol-Reina/DapperAOT/tree/fix/aot-native-compilation

Key files:

• src/Dapper.Stubs/SqlMapper.cs — ~90 extension methods with AOT annotations
• src/Dapper.Stubs/SqlMapper.GridReader.cs — Working state machine (adapted from Dapper source)
• src/Dapper.Stubs/DbString.cs — Working POCO with properties
• test/Dapper.AOT.AotTest/ — Test project that validates dotnet publish with AOT

The design spec with full rationale is in docs/superpowers/specs/2026-03-16-dapper-stubs-design.md.

Review the proposed implementation on the fix/aot-native-compilation branch, especially src/Dapper.Stubs/SqlMapper.cs, src/Dapper.Stubs/SqlMapper.GridReader.cs, src/Dapper.Stubs/DbString.cs, and test/Dapper.AOT.AotTest/. Start by running the AOT test project's dotnet publish validation and compare it with the existing Dapper.AOT structure. Done means maintainers select an approach and the test confirms a native publish with zero ILC warnings while generated code still runs.