Small command-line tools are often expected to start quickly, use little memory, and run without a large runtime environment.
A traditional .NET application can already perform well, but it still depends on the .NET runtime and usually starts by loading assemblies and performing runtime compilation work.
Native AOT takes a different approach. The application is compiled ahead of time into native machine code, producing a self-contained executable that can start without requiring the .NET runtime to be installed separately.
This makes Native AOT particularly interesting for command line utilities, developer tools, build helpers, automation programs, and small internal executables.
The important point is that Native AOT is not automatically the best choice for every .NET application. It works best when the application has a predictable dependency graph and does not depend heavily on runtime features such as unrestricted reflection or dynamic code generation.
What Native AOT Changes
A normal .NET application generally follows this model:
C# Source Code
|
v
.NET Assembly
|
v
.NET Runtime
|
v
ApplicationNative AOT changes the deployment model:
C# Source Code
|
v
Native AOT Compiler
|
v
Native ExecutableThe resulting executable contains the native code required by the application and its dependencies.
For a command line tool, this can simplify deployment because the target machine does not need a separate .NET runtime installation.
Why Command Line Tools Are a Good Fit
Command line applications often have characteristics that match Native AOT well.
They usually:
- Start and finish quickly.
- Have a relatively small dependency graph.
- Perform a focused task.
- Run in CI/CD environments.
- Get distributed as standalone executables.
- Do not require a long-running application server.
- Often have predictable input and output.
Examples include:
dotnet tool
Build helper
Code generator
Repository analyzer
Migration utility
Configuration validator
Release helper
Developer CLI
File processing utilityFor these workloads, startup overhead can matter more than it does for a long-running web application.
Create a Native AOT Console Application
A normal console application can be configured for Native AOT through the project file.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net11.0</TargetFramework>
<PublishAot>true</PublishAot>
<InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>
</Project>The important setting is:
<PublishAot>true</PublishAot>This tells the .NET publishing system that the application should be compiled using Native AOT.
For a small utility, InvariantGlobalization can also reduce the application footprint when the tool does not require culture-specific globalization behavior.
Do not enable it blindly. If the tool needs locale-sensitive formatting, parsing, or culture-specific behavior, configure globalization according to those requirements.
Build a Simple CLI
Consider a small command line application:
using System.CommandLine;
var rootCommand = new RootCommand("Repository utility");
var pathOption = new Option<string>(
"--path",
"Path to the repository");
rootCommand.AddOption(pathOption);
rootCommand.SetHandler(
(string path) =>
{
Console.WriteLine($"Scanning: {path}");
},
pathOption);
return await rootCommand.InvokeAsync(args);The important consideration is not the CLI framework itself.
The application should have a predictable startup path and avoid unnecessary runtime discovery.
For a small utility, keeping the dependency graph simple can make Native AOT easier to adopt.
Publish the Application
A Native AOT application is normally produced through dotnet publish.
For example:
dotnet publish -c Release -r win-x64The runtime identifier determines the target operating system and architecture.
Examples include:
win-x64
linux-x64
linux-arm64
osx-arm64The resulting published output contains the native executable and any files required by the selected deployment configuration.
A Native AOT build is platform-specific, so a Windows executable should not be expected to run directly on Linux.
Cross-Platform Distribution
If a CLI tool needs to support several platforms, publish separate artifacts.
For example:
tool-win-x64
tool-linux-x64
tool-linux-arm64
tool-osx-arm64A CI pipeline can produce these artifacts independently.
A typical build matrix looks like:
Native AOT
|
+-----------+-----------+
| | |
Windows Linux macOS
| | |
x64/ARM x64/ARM ARMDo not build on one operating system and assume the resulting native executable is portable to every platform.
Native AOT and Reflection
Reflection is one of the areas that requires attention.
Traditional .NET applications can discover types and members at runtime:
var type = Type.GetType(typeName);An AOT compiler cannot always determine every type that might be required by runtime reflection.
For example:
var properties = typeof(Product)
.GetProperties();is relatively straightforward when the type is known at compile time.
Dynamic type discovery is more problematic:
var type = Type.GetType(
configuration["TypeName"]);The compiler may not know which type needs to be included in the native application.
This is why Native AOT applications need more deliberate handling of reflection-heavy libraries.
Prefer Source Generation
Source generation is often a better fit for Native AOT than runtime reflection.
For JSON serialization, for example, use System.Text.Json source generation.
Define a serialization context:
using System.Text.Json.Serialization;
[JsonSerializable(typeof(Product))]
internal partial class AppJsonContext
: JsonSerializerContext
{
}Then serialize using the generated metadata:
var json = JsonSerializer.Serialize(
product,
AppJsonContext.Default.Product);This allows the serializer metadata to be generated at build time instead of discovering the required information dynamically at runtime.
For AOT-oriented applications, source generation should be considered whenever a library offers it as an alternative to runtime reflection.
Be Careful With Dependency Injection
Dependency injection itself is not incompatible with Native AOT.
The problem is how services are discovered and created.
A simple registration is predictable:
builder.Services.AddSingleton<IFileScanner, FileScanner>();Runtime assembly scanning is less predictable:
services.Scan(
scan => scan
.FromApplicationDependencies()
.AddClasses()
.AsImplementedInterfaces());Convention-based registration can depend on runtime type discovery.
For a small CLI, explicit registration is often easier to understand and more AOT-friendly.
services.AddSingleton<FileScanner>();
services.AddSingleton<ReportWriter>();
services.AddSingleton<RepositoryAnalyzer>();The application does not need to discover services that could have been registered directly.
Native AOT and Command Line Parsing
CLI parsing libraries can also introduce compatibility considerations.
A small tool may not need a large framework.
For example:
if (args.Length == 0)
{
Console.Error.WriteLine(
"Usage: repo-check <path>");
return 1;
}
var path = args[0];
if (!Directory.Exists(path))
{
Console.Error.WriteLine(
$"Directory not found: {path}");
return 2;
}
Console.WriteLine($"Checking {path}");
return 0;For a tiny utility, this approach has almost no runtime infrastructure.
If the tool requires subcommands, validation, help generation, and complex argument handling, a CLI library can still be appropriate. Check its Native AOT support before adopting it.
Native AOT and Dynamic Code
Native AOT is a poor fit for applications that depend heavily on runtime code generation.
Examples include libraries that generate code dynamically using:
System.Reflection.Emitor applications that depend on dynamically generated proxies.
A library may work perfectly in a regular .NET application but fail during AOT publishing or at runtime.
When evaluating a dependency, check whether it uses:
- Runtime reflection.
- Dynamic assembly loading.
- Runtime code generation.
- Reflection.Emit.
- Dynamic proxies.
- Plugin discovery.
- Runtime type scanning.
Join the conversation! Your thoughts help the community grow.