.NET CLI tools are useful for automating development tasks, managing projects, generating code, and performing operations from the command line. Developers can install these tools globally or locally and run them using the dotnet command.
However, distributing a traditional .NET tool can introduce an additional requirement: the target machine must have a compatible .NET runtime installed.
This can become inconvenient when distributing utilities to developers, running tools inside build agents, or deploying command-line applications to restricted environments.
Native AOT provides another option. It compiles an application into native machine code during publishing, allowing it to run without a separately installed .NET runtime.
The .NET SDK also supports packaging runtime-specific, self-contained, and Native AOT tools. This makes it possible to distribute a CLI tool through the familiar .NET tool installation experience while providing platform-specific native executables.
This article explains how to build a .NET CLI tool, publish it using Native AOT, package it for different platforms, and identify the compatibility issues that should be addressed before distribution.
Understanding Native AOT for .NET CLI Tools
Normally, a .NET application contains Intermediate Language (IL) that the .NET runtime executes.
In a typical deployment, the application requires a compatible .NET runtime on the target machine.
Native AOT changes this execution model.
Instead of relying on Just-In-Time compilation when the application starts, the Native AOT publishing process compiles the application and its required code into native machine code.
The resulting executable includes the runtime components required by the application and does not require a separate .NET runtime installation.
For example, a traditional console application might be started using:
dotnet MyTool.dll
A Native AOT application can be started directly:
./MyTool
On Windows, the published executable can be:
.\MyTool.exe
The target machine does not need the .NET runtime installed, although the application may still depend on operating-system libraries.
Native AOT is particularly useful for command-line utilities that need fast startup, predictable deployment, or distribution to machines where installing a runtime is undesirable.
Creating a Simple .NET CLI Tool
Start by creating a console application:
dotnet new console -n SystemInfoTool
cd SystemInfoTool
Replace the contents of Program.cs with a simple command-line utility:
using System.Runtime.InteropServices;
Console.WriteLine("System Information Tool");
Console.WriteLine($"Operating System: {RuntimeInformation.OSDescription}");
Console.WriteLine($"Architecture: {RuntimeInformation.ProcessArchitecture}");
Console.WriteLine($"Framework: {RuntimeInformation.FrameworkDescription}");
This application displays basic information about the environment in which it runs.
Run it normally:
dotnet run
The application executes through the installed .NET runtime.
Before publishing it as Native AOT, it is useful to understand how the application behaves in its regular development configuration.
Enabling Native AOT in the Project
Open SystemInfoTool.csproj and add the PublishAot property:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net11.0</TargetFramework>
<PublishAot>true</PublishAot>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
</Project>
The important setting is:
<PublishAot>true</PublishAot>
This enables Native AOT publishing and activates relevant compatibility analysis during development and builds.
It is better to configure this property in the project file rather than only passing it to an individual publish command. The setting also influences build-time analysis and helps identify code that may not work correctly with Native AOT.
Native AOT requires a platform-specific target. The publishing process also requires the appropriate native compiler toolchain.
Publishing a Native AOT Executable
Once Native AOT is enabled, publish the application for the required operating system and architecture.
For 64-bit Windows:
dotnet publish -c Release -r win-x64
For 64-bit Linux:
dotnet publish -c Release -r linux-x64
For 64-bit macOS:
dotnet publish -c Release -r osx-x64
For Apple Silicon:
dotnet publish -c Release -r osx-arm64
The runtime identifier specifies the platform and architecture for which the executable is generated.
The output is available under the project's publish directory, typically:
bin/Release/net11.0/<RID>/publish/
For example:
bin/Release/net11.0/win-x64/publish/
The published Windows application includes an executable that can be started directly.
.\SystemInfoTool.exe
On Linux or macOS:
./SystemInfoTool
The Native AOT executable is self-contained and does not require a separately installed .NET runtime.
However, it is important to understand that Native AOT does not eliminate every external dependency. The executable may still require operating-system libraries and other native dependencies.
Understanding Runtime Identifiers
A Runtime Identifier (RID) tells the .NET publishing system which operating system and architecture to target.
Some commonly used RIDs include:
Platform | Runtime Identifier |
|---|
Windows 64-bit | win-x64 |
Windows ARM64 | win-arm64 |
Linux 64-bit | linux-x64 |
Linux ARM64 | linux-arm64 |
macOS Intel | osx-x64 |
macOS Apple Silicon | osx-arm64 |
A Native AOT executable is platform-specific.
A Windows executable cannot be used directly on Linux, and an x64 executable is not interchangeable with an ARM64 executable.
If a tool needs to support Windows, Linux, and macOS, publish separate native versions for each supported platform.
For example:
dotnet publish -c Release -r win-x64
dotnet publish -c Release -r linux-x64
dotnet publish -c Release -r osx-arm64
Each command produces an executable for its specified target.
For production distribution, consider building on a suitable host environment and testing the resulting artifact on the actual target operating system.
Native compilation and platform-specific native dependencies make cross-platform publishing more involved than publishing a regular managed application.
Packaging Native AOT Applications as .NET Tools
Publishing a Native AOT executable is useful, but developers may want to distribute it through the familiar .NET tool ecosystem.
The .NET SDK supports runtime-specific tool packages, including self-contained and Native AOT tools.
This allows developers to install a tool using familiar commands while the .NET CLI selects the appropriate package for the user's platform.
First, update the project file to include the tool package configuration:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net11.0</TargetFramework>
<PackAsTool>true</PackAsTool>
<ToolCommandName>system-info</ToolCommandName>
<PackageId>SystemInfoTool</PackageId>
<Version>1.0.0</Version>
<Authors>Example Developer</Authors>
<Description>
A cross-platform system information CLI tool.
</Description>
<PublishAot>true</PublishAot>
</PropertyGroup>
</Project>
The PackAsTool property identifies the project as a .NET tool package.
ToolCommandName defines the command users execute after installation.
PackageId identifies the package in a NuGet feed.
For runtime-specific, self-contained, or AOT tool packaging, configure the appropriate runtime-specific packaging properties supported by the .NET SDK. In particular, the following settings enable a Native AOT tool package:
<PropertyGroup>
<PackAsTool>true</PackAsTool>
<ToolCommandName>system-info</ToolCommandName>
<PackAsToolShimRuntimeIdentifiers>
win-x64;win-arm64;linux-x64;linux-arm64;osx-x64;osx-arm64
</PackAsToolShimRuntimeIdentifiers>
<PublishAot>true</PublishAot>
</PropertyGroup>
The listed runtime identifiers represent the platforms for which the package is intended to provide native tool assets.
The actual publishing environment must have the required compiler toolchain for the runtime being built.
The .NET SDK's runtime-specific tool packaging model allows users to install the tool without manually selecting the correct package for every supported platform.
Building and Packing the Tool
Once the project configuration is complete, build the package:
dotnet pack -c Release
The generated NuGet package is typically placed in the bin/Release directory.
Before publishing it to NuGet.org, test the package locally.
For example, create a local package source:
mkdir local-packages
Copy the generated package into that directory.
Register the local package source:
dotnet nuget add source ./local-packages \
--name LocalTools
Install the tool globally:
dotnet tool install SystemInfoTool \
--global \
--add-source ./local-packages
Run it using the configured command name:
system-info
The .NET CLI resolves the appropriate runtime-specific package for the current environment.
This provides a familiar installation experience for developers while allowing the tool to run without a separately installed .NET runtime.
For local development, you can also use a local tool manifest:
dotnet new tool-manifest
Then install the package locally:
dotnet tool install SystemInfoTool \
--local \
--add-source ./local-packages
Run the tool with:
dotnet tool run system-info
Local tool manifests are useful when a development team wants to share the same tool version through source control.
Understanding Native AOT Compatibility Warnings
Native AOT introduces restrictions that do not apply in the same way to traditional JIT-based applications.
The most important difference is that the application must be analyzable during publishing.
The compiler needs to determine which code, types, and methods are required so that it can generate the native executable.
Some dynamic programming techniques make this difficult.
For example, consider an application that loads assemblies at runtime:
var assembly = Assembly.LoadFile(
"/plugins/CustomPlugin.dll");
This pattern depends on loading code dynamically after the application starts.
Native AOT does not support unrestricted dynamic assembly loading in the same way as a regular .NET application.
Another example is runtime code generation:
var method = new DynamicMethod(
"GeneratedMethod",
typeof(int),
Type.EmptyTypes);
System.Reflection.Emit and similar runtime code-generation techniques are not supported in Native AOT.
Reflection can also cause problems when the compiler cannot determine which types or members will be accessed.
For example, serializers that discover types dynamically may require additional configuration or source-generated metadata.
When publishing with Native AOT, review the warnings carefully instead of ignoring them.
Common areas to investigate include:
Dynamic assembly loading.
Runtime code generation.
Reflection over types that cannot be determined during publishing.
Libraries that depend on unsupported runtime features.
Native dependencies that are unavailable for the target platform.
The goal is to resolve compatibility issues before distributing the executable.
Using Source Generators to Improve AOT Compatibility
Source generators can help replace some runtime reflection patterns with code generated during compilation.
For example, System.Text.Json supports source-generated serialization metadata.
Instead of relying entirely on runtime reflection, define a serialization context:
using System.Text.Json.Serialization;
public class Customer
{
public int Id { get; set; }
public string Name { get; set; } = string.Empty;
}
[JsonSerializable(typeof(Customer))]
internal partial class AppJsonContext : JsonSerializerContext
{
}
The application can then use the generated metadata:
using System.Text.Json;
var customer = new Customer
{
Id = 101,
Name = "John"
};
string json = JsonSerializer.Serialize(
customer,
AppJsonContext.Default.Customer);
Console.WriteLine(json);
This makes the serialization requirements visible at build time.
Source generation is not a universal replacement for reflection, but it is a useful approach when preparing applications for trimming and Native AOT.
Before adopting a third-party library, check whether it explicitly supports Native AOT and review its compatibility warnings.
Optimizing the Published Executable
Native AOT applications are already compiled into native code, but developers can influence the publishing process based on their deployment priorities.
For example, an application that runs as a frequently invoked CLI utility may prioritize startup and execution speed.
A small utility distributed to thousands of developers may prioritize executable size.
The OptimizationPreference property allows developers to express this preference.
To prioritize size:
<PropertyGroup>
<PublishAot>true</PublishAot>
<OptimizationPreference>Size</OptimizationPreference>
</PropertyGroup>
To prioritize speed:
<PropertyGroup>
<PublishAot>true</PublishAot>
<OptimizationPreference>Speed</OptimizationPreference>
</PropertyGroup>
The default behavior balances performance and application size.
These settings influence compiler optimization decisions. They do not guarantee a particular executable size or performance improvement.
Measure the output and execution behavior before choosing a setting for production.
Also remember that Native AOT applications include the runtime components they need. A Native AOT executable is not necessarily smaller than every framework-dependent deployment.
Important Production Considerations
Native AOT can simplify distribution, but a few operational considerations deserve attention.
Build for every supported platform
A single native executable cannot serve every operating system and architecture.
Maintain separate publishing targets and verify that each artifact works on its intended platform.
Install the native compiler toolchain
Native AOT publishing requires platform-specific native compilation tools.
For example, Linux environments commonly require Clang and the appropriate build tools.
Windows publishing requires the appropriate Visual C++ toolchain, while macOS requires the Xcode command-line tools.
The required tools depend on the target platform and SDK version.
Test on machines without .NET installed
One of the main reasons to choose Native AOT is to avoid requiring a separate .NET runtime.
Test the published executable in an environment where the runtime is not installed.
This helps verify that the application does not accidentally depend on development-machine configuration.
Check operating-system dependencies
Self-contained does not mean completely independent of the operating system.
Native applications may require system libraries, globalization dependencies, and other native components.
Document these requirements for users.
Preserve debugging information
Native AOT publishing produces native debug information separately by default on supported platforms.
Keep the corresponding symbol files for production releases.
These files are valuable when investigating crashes, debugging production issues, or analyzing native stack traces.
Measure startup and memory usage
Native AOT can improve startup time and memory usage, but the result depends on the application.
Benchmark the original application and the Native AOT executable under comparable conditions.
For command-line utilities, startup time can be especially important because the application may perform a small task and exit immediately.
Summary
Native AOT provides a practical way to distribute .NET command-line tools without requiring users to install a separate .NET runtime.
By enabling PublishAot and publishing for specific runtime identifiers, developers can produce native executables for Windows, Linux, and macOS.
The .NET SDK also supports packaging runtime-specific Native AOT tools, allowing users to install them through the familiar dotnet tool experience.
However, Native AOT introduces restrictions around dynamic assembly loading, runtime code generation, reflection, and trimming. Developers should review compatibility warnings, use source-generated alternatives where appropriate, and test the published executable on its target platform.
For small utilities, development tools, build automation, and command-line applications, Native AOT can simplify distribution and improve startup characteristics.
The most important step is to evaluate the application's dependencies before choosing this deployment model. A successful Native AOT release is not just about producing an executable; it is about making sure that executable works reliably across every platform the tool claims to support.
Join the conversation! Your thoughts help the community grow.