dotnet-aot-architecture

AOT-first application design patterns for .NET 8+: preferring source generators over reflection, explicit DI registration over assembly scanning, AOT-safe serialization choices, library compatibility assessment, and factory patterns replacing Activator.CreateInstance.

Version assumptions: .NET 8.0+ baseline. Patterns apply to all AOT-capable project types (console, ASP.NET Core Minimal APIs, worker services).

Scope

• Source generator replacements for reflection patterns
• AOT-safe DI patterns (explicit registration, keyed services)
• Serialization choices for AOT (STJ source gen, Protobuf, MessagePack)
• Factory patterns replacing Activator.CreateInstance
• Library compatibility assessment for AOT
• AOT application architecture template

Out of scope

• Native AOT publish pipeline and MSBuild configuration -- see [skill:dotnet-native-aot]
• Trim-safe library authoring and annotations -- see [skill:dotnet-trimming]
• WASM AOT compilation -- see [skill:dotnet-aot-wasm]
• MAUI-specific AOT -- see [skill:dotnet-maui-aot]
• Source generator authoring (Roslyn API) -- see [skill:dotnet-csharp-source-generators]
• DI container internals -- see [skill:dotnet-csharp-dependency-injection]
• Serialization depth -- see [skill:dotnet-serialization]

Cross-references: [skill:dotnet-native-aot] for the AOT publish pipeline, [skill:dotnet-trimming] for trim annotations and library authoring, [skill:dotnet-serialization] for serialization patterns, [skill:dotnet-csharp-source-generators] for source gen mechanics, [skill:dotnet-csharp-dependency-injection] for DI fundamentals, [skill:dotnet-containers] for runtime-deps deployment, [skill:dotnet-native-interop] for general P/Invoke patterns and marshalling.

---

Source Generators Over Reflection

The primary AOT enabler is replacing runtime reflection with compile-time source generation. Source generators produce code at build time that the AOT compiler can analyze and include.

Key Source Generator Replacements

Reflection Pattern	Source Generator / AOT-Safe Alternative	Library
JsonSerializer.Deserialize<T>()	[JsonSerializable] context	System.Text.Json (built-in)
Activator.CreateInstance<T>()	Factory pattern with explicit new	Manual
Type.GetProperties() for mapping	[Mapper] attribute	Mapperly
Regex pattern compilation	[GeneratedRegex] attribute	Built-in (.NET 7+)
ILogger.Log(...) with string interpolation	[LoggerMessage] attribute	Microsoft.Extensions.Logging
Assembly scanning for DI	Explicit services.Add*()	Manual
[DllImport] P/Invoke	[LibraryImport]	Built-in (.NET 7+)
AutoMapper CreateMap<>()	[Mapper] source gen	Mapperly

Example: Migrating to Source Gen

// BEFORE: Reflection-based (breaks under AOT)
var logger = loggerFactory.CreateLogger<OrderService>();
logger.LogInformation("Order {OrderId} created for {Customer}", order.Id, order.CustomerId);

// AFTER: Source-generated (AOT-safe, zero-alloc)
public partial class OrderService
{
    [LoggerMessage(Level = LogLevel.Information,
        Message = "Order {OrderId} created for {Customer}")]
    private static partial void LogOrderCreated(
        ILogger logger, int orderId, string customer);
}

// Usage:
LogOrderCreated(_logger, order.Id, order.CustomerId);

```text

See [skill:dotnet-csharp-source-generators] for source generator mechanics and authoring patterns.

---

## AOT-Safe DI Patterns

Dependency injection in AOT requires explicit service registration. Assembly scanning (`AddServicesFromAssembly`) and
open-generic resolution may require reflection that AOT cannot satisfy.

### Explicit Registration (Preferred)

```csharp

var builder = WebApplication.CreateSlimBuilder(args);

// Explicit registrations -- AOT-safe
builder.Services.AddSingleton<IOrderRepository, PostgresOrderRepository>();
builder.Services.AddScoped<IOrderService, OrderService>();
builder.Services.AddTransient<IEmailSender, SmtpEmailSender>();
builder.Services.AddSingleton(TimeProvider.System);

```text

### Avoid Assembly Scanning

```csharp

// BAD: Assembly scanning uses reflection -- breaks under AOT
builder.Services.Scan(scan => scan
    .FromAssemblyOf<OrderService>()
    .AddClasses(classes => classes.AssignableTo<IService>())
    .AsImplementedInterfaces()
    .WithScopedLifetime());

// GOOD: Explicit registrations grouped by concern
builder.Services.AddOrderServices();
builder.Services.AddInventoryServices();

// Extension method groups related registrations
public static class OrderServiceExtensions
{
    public static IServiceCollection AddOrderServices(
        this IServiceCollection services)
    {
        services.AddScoped<IOrderService, OrderService>();
        services.AddScoped<IOrderRepository, PostgresOrderRepository>();
        services.AddScoped<IOrderValidator, OrderValidator>();
        return services;
    }
}

```text

### Keyed Services (.NET 8+)

```csharp

// AOT-safe keyed service registration
builder.Services.AddKeyedSingleton<INotificationSender, EmailSender>("email");
builder.Services.AddKeyedSingleton<INotificationSender, SmsSender>("sms");

// Resolve by key
app.MapPost("/notify", ([FromKeyedServices("email")] INotificationSender sender) =>
    sender.SendAsync("Hello"));

```text

See [skill:dotnet-csharp-dependency-injection] for full DI patterns.

---

## Serialization Choices for AOT

### Decision Matrix

| Serializer                    | AOT-Safe | Setup Required                              | Best For                     |
| ----------------------------- | -------- | ------------------------------------------- | ---------------------------- |
| System.Text.Json + source gen | Yes      | `[JsonSerializable]` context                | APIs, config, JSON interop   |
| Protobuf (Google.Protobuf)    | Yes      | `.proto` schema files                       | gRPC, service-to-service     |
| MessagePack + source gen      | Yes      | `[MessagePackObject]` + source gen resolver | Caching, real-time           |
| Newtonsoft.Json               | **No**   | N/A                                         | **Do not use for AOT**       |
| STJ without source gen        | **No**   | N/A                                         | **Falls back to reflection** |

### STJ Source Gen Setup

```csharp

// Define serializable types
[JsonSerializable(typeof(Product))]
[JsonSerializable(typeof(List<Product>))]
[JsonSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
internal partial class AppJsonContext : JsonSerializerContext { }

// Register in ASP.NET Core
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0,
        AppJsonContext.Default);
});

```json

See [skill:dotnet-serialization] for comprehensive serialization patterns.

---

## Factory Patterns Replacing Activator.CreateInstance

`Activator.CreateInstance` uses runtime reflection to create instances and is incompatible with AOT. Replace with
factory patterns that use explicit construction.

### Simple Factory

```csharp

// BAD: Reflection-based creation -- breaks under AOT
public T CreateHandler<T>() where T : class
    => (T)Activator.CreateInstance(typeof(T))!;
// NOTE: Activator.CreateInstance uses runtime reflection and is AOT-unfriendly.
// Prefer factory registration or explicit constructors in AOT builds. For example:

// Registration:
// services.AddSingleton<Func<Type, object>>(sp => t => ActivatorUtilities.CreateInstance(sp, t));

// Better (AOT-safe):
// services.AddSingleton<IPaymentProcessorFactory, PaymentProcessorFactory>();
// Then resolve via factory.Create("Stripe");

// GOOD: Factory with explicit registration
public class HandlerFactory
{
    private readonly Dictionary<Type, Func<IHandler>> _factories = new();

    public void Register<T>(Func<T> factory) where T : IHandler
        => _factories[typeof(T)] = () => factory();

    public IHandler Create<T>() where T : IHandler
        => _factories[typeof(T)]();
}

// Registration
var factory = new HandlerFactory();
factory.Register<OrderHandler>(() => new OrderHandler(repository, logger));
factory.Register<PaymentHandler>(() => new PaymentHandler(gateway));

```text

### Strategy Pattern via DI

```csharp

// BAD: Dynamic type resolution
public IPaymentProcessor GetProcessor(string type)
{
    var processorType = Type.GetType($"MyApp.Payments.{type}Processor");
    return (IPaymentProcessor)Activator.CreateInstance(processorType!)!;
}

// GOOD: Keyed services (.NET 8+)
builder.Services.AddKeyedScoped<IPaymentProcessor, CreditCardProcessor>("CreditCard");
builder.Services.AddKeyedScoped<IPaymentProcessor, BankTransferProcessor>("BankTransfer");
builder.Services.AddKeyedScoped<IPaymentProcessor, WalletProcessor>("Wallet");

// Resolve at runtime without reflection
app.MapPost("/pay", (
    [FromQuery] string type,
    IServiceProvider sp) =>
{
    var processor = sp.GetRequiredKeyedService<IPaymentProcessor>(type);
    return processor.ProcessAsync();
});

```text

### Enum-Based Factory

```csharp

// For a fixed set of types, use a switch expression
public static IExporter CreateExporter(ExportFormat format) => format switch
{
    ExportFormat.Csv => new CsvExporter(),
    ExportFormat.Json => new JsonExporter(),
    ExportFormat.Pdf => new PdfExporter(),
    _ => throw new ArgumentOutOfRangeException(nameof(format))
};

```json

---

## Library Compatibility Assessment

### Assessment Checklist

Before adopting a NuGet package in an AOT project:

1. **Check for `IsAotCompatible` in the package source** -- packages that set this are validated against AOT analyzers
2. **Check for `[RequiresDynamicCode]` / `[RequiresUnreferencedCode]` annotations** -- these indicate AOT-incompatible
   APIs
3. **Run AOT analyzers against your usage** -- `dotnet build /p:EnableAotAnalyzer=true`
4. **Check the package's GitHub issues for AOT/trimming reports** -- search for "Native AOT", "trimming", "IL2026",
   "IL3050"
5. **Look for source-generated alternatives** -- many reflection-based libraries now have source-gen companions

### Common Library Status

| Library               | AOT Status                       | AOT-Safe Alternative            |
| --------------------- | -------------------------------- | ------------------------------- |
| AutoMapper            | Breaks                           | Mapperly                        |
| MediatR               | Partial (explicit registration)  | Direct method calls or factory  |
| FluentValidation      | Partial                          | Manual validation or source gen |
| Dapper                | Compatible (.NET 8+ AOT support) | --                              |
| Entity Framework Core | Partial (precompiled queries)    | Dapper for AOT-heavy paths      |
| Refit                 | Compatible (7+ with source gen)  | --                              |
| Polly                 | Compatible (v8+)                 | --                              |
| Serilog               | Partial                          | `[LoggerMessage]` source gen    |
| Hangfire              | Breaks                           | Custom `IHostedService`         |

### Testing Compatibility

```bash

# Build with all analyzers enabled
dotnet build /p:EnableAotAnalyzer=true /p:EnableTrimAnalyzer=true /p:TrimmerSingleWarn=false

# Warnings indicate AOT-incompatible usage
# IL3050 = RequiresDynamicCode (definitely breaks)
# IL2026 = RequiresUnreferencedCode (may break)

```text

---

## AOT Application Architecture Template

```text

src/
  MyApp/
    Program.cs                   # CreateSlimBuilder, explicit DI
    MyApp.csproj                 # PublishAot=true, EnableAotAnalyzer=true
    JsonContext.cs               # [JsonSerializable] for all API types
    Endpoints/
      OrderEndpoints.cs          # Minimal API route groups
      ProductEndpoints.cs
    Services/
      OrderService.cs            # Business logic (no reflection)
      IOrderService.cs
    Repositories/
      OrderRepository.cs         # Data access (Dapper or EF precompiled)
    Extensions/
      ServiceCollectionExtensions.cs  # Grouped DI registrations

```csharp

---

## Agent Gotchas

1. **Do not use `Activator.CreateInstance` in AOT projects.** It requires runtime reflection that is not available. Use
   factory patterns, DI keyed services, or switch expressions instead.
2. **Do not use assembly scanning for DI registration** (`Scan`, `RegisterAssemblyTypes`, `FromAssemblyOf`). These use
   reflection to discover types at runtime. Register services explicitly.
3. **Do not use `System.Text.Json` without a `[JsonSerializable]` context in AOT.** Without a source-generated context,
   STJ falls back to reflection and fails at runtime.
4. **Do not assume a library is AOT-compatible without testing.** Run `dotnet build /p:EnableAotAnalyzer=true` and check
   for IL3050/IL2026 warnings against your specific usage.
5. **Do not use `Type.GetType()` or `Assembly.GetTypes()` for runtime discovery.** These rely on metadata that may be
   trimmed. Use compile-time known types.

---



## Code Navigation (Serena MCP)

**Primary approach:** Use Serena symbol operations for efficient code navigation:

1. **Find definitions**: `serena_find_symbol` instead of text search
2. **Understand structure**: `serena_get_symbols_overview` for file organization
3. **Track references**: `serena_find_referencing_symbols` for impact analysis
4. **Precise edits**: `serena_replace_symbol_body` for clean modifications

**When to use Serena vs traditional tools:**
- ✅ **Use Serena**: Navigation, refactoring, dependency analysis, precise edits
- ✅ **Use Read/Grep**: Reading full files, pattern matching, simple text operations
- ✅ **Fallback**: If Serena unavailable, traditional tools work fine

**Example workflow:**
```text
# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"

# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"
```
## References

- [Native AOT deployment](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/)
- [Source generation in .NET](https://learn.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview)
- [System.Text.Json source generation](https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/source-generation)
- [LoggerMessage source generation](https://learn.microsoft.com/en-us/dotnet/core/extensions/logger-message-generator)
- [Mapperly object mapper](https://mapperly.riok.app/)
- [Prepare .NET libraries for trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/prepare-libraries-for-trimming)