Edit

Share via

Create RID-specific, self-contained, and AOT .NET tools

This article applies to: ✔️ .NET SDK 10 and later versions

Package .NET tools for specific platforms and architectures so you can distribute native, fast, and trimmed applications. This capability makes it easier to distribute native, fast, trimmed .NET applications for command-line tools like MCP servers or other platform-specific utilities.

Overview

Starting with .NET SDK 10, you can create .NET tools that target specific Runtime Identifiers (RIDs). These tools can be:

  • RID-specific: Compiled for particular operating systems and architectures.
  • Self-contained: Include the .NET runtime and don't require a separate .NET installation.
  • Native AOT: Use Ahead-of-Time compilation for faster startup and smaller memory footprint.

When users install a RID-specific tool, the .NET CLI automatically selects and installs the appropriate package for their platform.

Opt in to RID-specific packaging

To create a RID-specific tool, configure your project with one of the following MSBuild properties:

RuntimeIdentifiers property

Use RuntimeIdentifiers to specify the platforms your tool supports:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>mytool</ToolCommandName>
    <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>
  </PropertyGroup>
</Project>

ToolPackageRuntimeIdentifiers property

Alternatively, use ToolPackageRuntimeIdentifiers for tool-specific RID configuration:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>mytool</ToolCommandName>
    <ToolPackageRuntimeIdentifiers>win-x64;linux-x64;osx-arm64</ToolPackageRuntimeIdentifiers>
  </PropertyGroup>
</Project>

Use a semicolon-delimited list of RID values. For a list of Runtime Identifiers, see the RID catalog.

Package your tool

The packaging process differs depending on whether you're using AOT compilation. To build a NuGet package, or .nupkg file from the project, run the dotnet pack command.

RID-specific and self-contained tools

For tools without AOT compilation, run dotnet pack once:

dotnet pack

This command creates multiple NuGet packages:

  • One package for each RID: <packageName>.<RID>.<packageVersion>.nupkg
    • Example: mytool.win-x64.1.0.0.nupkg
    • Example: mytool.linux-x64.1.0.0.nupkg
    • Example: mytool.osx-arm64.1.0.0.nupkg
  • One RID-agnostic pointer package: <packageName>.<packageVersion>.nupkg
    • Example: mytool.1.0.0.nupkg

AOT tools

For tools with AOT compilation (<PublishAot>true</PublishAot>), you must pack separately for each platform:

  • Pack the top-level package once (on any platform):

    dotnet pack

  • Pack for each specific RID on the corresponding platform:

    dotnet pack -r win-x64
dotnet pack -r linux-x64
dotnet pack -r osx-arm64

    You must run each RID-specific pack command on the matching platform because AOT compilation produces native binaries. For more information about the prerequisites for Native AOT compilation, see Native AOT deployment.

Package structure

Package types

RID-specific tool packages use two package types:

  • DotnetTool: The top-level package that contains metadata.
  • DotnetToolRidPackage: The RID-specific packages that contain the actual tool binaries.

Package metadata

The top-level package includes metadata that signals it's a RID-specific tool and lists the RID-specific packages. When you run dotnet tool install, the CLI reads this metadata to determine which RID-specific package to install for the current platform.

Publish your tool

Publish all packages to NuGet.org or your package feed by using dotnet nuget push:

dotnet nuget push path/to/package/root/*.nupkg

Run a RID-specific tool

Users run RID-specific tools the same way as platform-agnostic tools:

dnx mytool

The CLI automatically:

  1. Downloads the top-level package.
  2. Reads the RID-specific metadata.
  3. Identifies the most appropriate package for the current platform.
  4. Downloads and runs the RID-specific package.

Example: Create an AOT tool

Here's a complete example of creating an AOT-compiled RID-specific tool:

  1. Create a new console application:

    dotnet new console -n MyFastTool
cd MyFastTool

  2. Update the project file to enable AOT and RID-specific packaging:

    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <PackAsTool>true</PackAsTool>
    <ToolCommandName>myfasttool</ToolCommandName>
    <RuntimeIdentifiers>win-x64;linux-x64;osx-arm64</RuntimeIdentifiers>
    <PublishAot>true</PublishAot>
    <PackageId>MyFastTool</PackageId>
    <Version>1.0.0</Version>
    <Authors>Your Name</Authors>
    <Description>A fast AOT-compiled tool</Description>
  </PropertyGroup>
</Project>

  3. Add your application code in Program.cs:

    Console.WriteLine("Hello from MyFastTool!");
Console.WriteLine($"Running on {Environment.OSVersion}");

  4. Pack the top-level package:

    dotnet pack

  5. Pack for each specific RID (on the corresponding platform):

    On Windows:

    dotnet pack -r win-x64

    On Linux:

    dotnet pack -r linux-x64

    On macOS:

    dotnet pack -r osx-arm64

  6. Publish all packages to NuGet.org by using the dotnet nuget push command.

See also

  • Last updated on