RID 固有、自己完結型、および AOT .NET ツールを作成する

この記事の対象: ✔️ .NET SDK 10 以降のバージョン

ネイティブ、高速、トリミングされたアプリケーションを配布できるように、特定のプラットフォームとアーキテクチャ用の .NET ツールをパッケージ化します。 この機能により、MCP サーバーやその他のプラットフォーム固有のユーティリティなどのコマンド ライン ツール用に最適化されたアプリケーションを配布しやすくなります。

概要

.NET SDK 10 以降では、(ランタイム識別子 (RID) で表される) 特定のオペレーティング システム環境を対象とする .NET ツールを作成できます。 次のツールを使用できます。

• RID 固有: 特定のオペレーティング システムとアーキテクチャ用にコンパイルされます。
• 自己完結型: .NET ランタイムを含めます。個別の .NET インストールは必要ありません。
• ネイティブ AOT: 事前コンパイルを使用して、起動時間を短縮し、メモリ占有領域を小さくします。

ユーザーは、ツールをインストールしても違いに気付かない。 .NET CLI は、プラットフォームに最適なパッケージを自動的に選択してインストールします。

RID 固有のパッケージ化にオプトインする

RID 固有のツールを作成するには、次のいずれかの MSBuild プロパティを使用してプロジェクトを構成します。

RuntimeIdentifiers プロパティ

RuntimeIdentifiersを使用して、ツールでサポートされるプラットフォームを指定します。

<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 プロパティ

または、ツール固有の RID 構成に ToolPackageRuntimeIdentifiers を使用します。

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

RID 値のセミコロン区切りのリストを使用します。 ランタイム識別子の一覧については、 RID カタログを参照してください。

RuntimeIdentifiersを使用するタイミングとToolPackageRuntimeIdentifiers

RuntimeIdentifiersもToolPackageRuntimeIdentifiersも、ツールを RID 固有のパッケージにすることを選択しますが、目的は少し異なります。

次の場合に RuntimeIdentifiers を使用します。

• (ツールとしてだけでなく) RID 固有のアプリを一般的にビルドして発行 するプロジェクトが必要です。
• 主に CoreCLR (非 AOT) を対象としているか、1 つの dotnet pack が複数の RID 固有パッケージを生成する標準的な SDK の動作が必要です。
• RID のサブセットの PublishAot を条件付き化することもできますが、 RuntimeIdentifiersのすべての RID に対して CoreCLR ベースのパッケージが必要です。

次の場合に ToolPackageRuntimeIdentifiers を使用します。

• 他の配置シナリオでプロジェクトのビルド方法を変更せずに、 ツール パッケージに対してのみ RID 固有の動作を定義する必要があります。
• Native AOT を使用しており、を使用して RID ごとに AOT バイナリをdotnet pack -r <RID>することを計画しています。
• 一部の RID がネイティブ AOT を取得し、他の RID が移植可能な CoreCLR 実装にフォールバックする ハイブリッド モデル が必要です。

Notes:

• 最上位のポインター パッケージは、使用可能な RID 固有のパッケージを指定します。 ToolPackageRuntimeIdentifiersを指定すると、ツール RID が決定されます。それ以外の場合は、RuntimeIdentifiersが使用されます。
• ToolPackageRuntimeIdentifiers は、次の RID と等しいか、または一部の RID である必要があります。 RuntimeIdentifiers
• PublishAot=trueすると、RID 固有のパッケージは、特定の RID (たとえば、dotnet pack -r linux-x64) 用にパックする場合にのみ生成されます。
• ネイティブ AOT ビルド (PublishAot=true) は、ビルド OS とターゲット OS が一致する場合にのみサポートされます。

ツールをパッケージ化する

パッケージ化プロセスは、AOT コンパイルを使用しているかどうかによって異なります。 プロジェクトから NuGet パッケージまたは .nupkg ファイルをビルドするには、 dotnet pack コマンドを実行します。

RID に特有の自己完結型ツール

dotnet packを 1 回実行します。

dotnet pack

このコマンドは、複数の NuGet パッケージを作成します。

• RID ごとに 1 つのパッケージ: <packageName>.<RID>.<packageVersion>.nupkg
  • 例: mytool.win-x64.1.0.0.nupkg
  • 例: mytool.linux-x64.1.0.0.nupkg
  • 例: mytool.osx-arm64.1.0.0.nupkg
• 1 つの RID に依存しないポインター パッケージ: <packageName>.<packageVersion>.nupkg
  • 例: mytool.1.0.0.nupkg

AOT ツール

AOT コンパイル (<PublishAot>true</PublishAot>) を使用するツールの場合は、プラットフォームごとに個別にパックする必要があります。

ネイティブ AOT のプラットフォーム要件

ネイティブ AOT コンパイルでは、SDK RID のオペレーティング システム (OS) 部分がターゲット RID の OS と一致する必要があります。 SDK は、異なるアーキテクチャ (x64 から ARM64 など) に対してクロスコンパイルできますが、オペレーティング システム (Windows から Linux など) 間ではコンパイルできません。

つまり、ネイティブ AOT パッケージをビルドするには、いくつかのオプションがあります。

• 開発用マシン専用にビルドする: 開発対象の OS に対してのみネイティブ AOT をサポートします。
• Linux ビルドにコンテナーを使用する: macOS または Windows を使用している場合は、コンテナーを使用して Linux 用にクロスコンパイルします。 たとえば、コンテナー イメージ mcr.microsoft.com/dotnet/sdk:10.0-noble-aot 使用します。
• マシン間でビルドをフェデレーションする: GitHub Actions や Azure DevOps Pipelines などの CI/CD システムを使用して、さまざまなオペレーティング システム上に構築します。

同じコンピューターまたは同時にすべての RID 固有パッケージをビルドする必要はありません。 最上位レベルのパッケージを発行する前に、ビルドして発行するだけで済みます。

ネイティブ AOT ツールのパッキング

最上位レベルのパッケージを 1 回 (任意のプラットフォームで) パックします。

dotnet pack

対応するプラットフォーム上の特定の RID ごとにパックします。次に例を示します。

dotnet pack -r linux-x64

各 RID 固有のパック コマンドは、OS がターゲット RID の OS と一致するプラットフォームで実行する必要があります。 ネイティブ AOT コンパイルの前提条件の詳細については、「 ネイティブ AOT のデプロイ」を参照してください。

PublishAotを true に設定すると、パッキング動作が変わります。

• dotnet pack では、 最上位のポインター パッケージ (パッケージの種類 DotnetTool) が生成されます。
• RID 固有の AOT パッケージは、-r <RID>やdotnet pack -r linux-x64など、dotnet pack -r osx-arm64を明示的に渡す場合にのみ生成されます。

ハイブリッド AOT + CoreCLR パッケージ パターン (例)

一部のツールでは、両方の長所が必要です。

• (ツールに応じて) 優先度の高いプラットフォームのサブセット用のネイティブ AOT。
• ネイティブ AOT ビルドの対象ではないプラットフォームで動作する 移植可能な CoreCLR フォールバック 。

この "ハイブリッド" モデルは、次のパターンで実現できます。

1. ネイティブ AOT およびツール固有の RID 用にツールを構成します。

   プロジェクト ファイルで、 ToolPackageRuntimeIdentifiers を使用し、 PublishAotを有効にします。

   例えば次が挙げられます。

   <ToolPackageRuntimeIdentifiers>osx-arm64;linux-arm64;linux-x64;any</ToolPackageRuntimeIdentifiers>
   <PublishAot>true</PublishAot>
   

2. ポインター パッケージを作成します。

   (任意のプラットフォームで) dotnet pack 1 回実行して、RID 固有のパッケージを指す最上位レベルのパッケージをビルドします。

   dotnet pack
   

3. 選択した RID のネイティブ AOT パッケージをビルドします。

   ネイティブ AOT コンパイルでは、ターゲット プラットフォームでビルドする必要があります。 dotnet pack -r <RID>を使用して、一致するプラットフォームで各 AOT 対応 RID パッケージをビルドします。

例えば次が挙げられます。

dotnet pack -r linux-x64

1. CoreCLR フォールバック パッケージをビルドします。

   ユニバーサル フォールバックを提供するには、AOT なしで any RID をパックします。

   dotnet pack -r any -p:PublishAot=false
   

   これにより、専用の AOT ビルドを持たないプラットフォームで実行できるポータブル CoreCLR パッケージ ( yourtool.any.<version>.nupkg など) が生成されます。

注

.NET SDK 10.0-noble-aot コンテナー イメージを使用して、Linux コンテナーをサポートする任意のホストから Linux Native AOT ツールをビルドしてパッケージ化することもできます。 例えば次が挙げられます。

• mcr.microsoft.com/dotnet/sdk:10.0-noble-aot

これは、開発用マシンが Linux をネイティブに実行していない場合に便利です。

このハイブリッド セットアップでは、次の操作を行います。

• ポインター パッケージ (yourtool.<version>.nupkg) は両方を参照します。
  • RID 固有のネイティブ AOT パッケージ ( yourtool.osx-arm64、 yourtool.linux-x64など)。
  • フォールバックとしての any CoreCLR パッケージ。
• .NET CLI は、ユーザーが dotnet tool install または dnxを実行するときに、ユーザーのプラットフォームに最適なパッケージを自動的に選択します。

例: dotnet10-hybrid-tool

dotnet10-hybrid-tool リポジトリでは、osx-arm64、linux-arm64、linux-x64用のネイティブ AOT パッケージに加えて、any RID 用の CoreCLR フォールバック パッケージ (AOT ビルドが使用できない場合など、Windows で使用) を使用するこのハイブリッド パッケージ パターンを示します。

ツールを自分でインストールして試すことができます。

dotnet tool install -g dotnet10-hybrid-tool
dotnet10-hybrid-tool

このツールは、ランタイム フレームワークの説明、ランタイム識別子 (RID)、およびコンパイル モード (ネイティブ AOT または CoreCLR) を報告します。

ネイティブ AOT を使用したプラットフォームでの出力例:

Hi, I'm a 'DotNetCliTool v2' tool!
Yes, I'm quite fancy.

Version: .NET 10.0.2
RID: osx-arm64
Mode: Native AOT

CoreCLR フォールバックを使用したプラットフォームでの出力例:

Hi, I'm a 'DotNetCliTool v2' tool!
Yes, I'm quite fancy.

Version: .NET 10.0.2
RID: win-x64
Mode: CoreCLR

これにより、RID 固有の AOT コンパイル ツールと CoreCLR フォールバック動作を試す便利な方法になります。

ツールを公開する

RID 固有のツール パッケージを発行する場合、.NET CLI は最上位パッケージのバージョン番号を使用して、一致する RID 固有のパッケージを選択します。 これは、以下のようなことを意味します。

• RID 固有のパッケージはすべて、最上位パッケージとまったく同じバージョンである必要があります。
• 最上位レベルのパッケージが使用可能になる前に、すべてのパッケージをフィードに発行する必要があります。

スムーズな発行プロセスを確保するには:

1. 最初にすべての RID 固有パッケージを発行します。

   dotnet nuget push yourtool.win-x64.1.0.0.nupkg
   dotnet nuget push yourtool.linux-x64.1.0.0.nupkg
   dotnet nuget push yourtool.osx-arm64.1.0.0.nupkg
   dotnet nuget push yourtool.any.1.0.0.nupkg
   

2. 最上位レベルのパッケージを最後に発行します。

   dotnet nuget push yourtool.1.0.0.nupkg
   

最上位レベルのパッケージを最後に発行すると、ユーザーがツールをインストールするときに、参照されているすべての RID 固有のパッケージを使用できるようになります。 すべての RID パッケージが発行される前にユーザーがツールをインストールすると、インストールは失敗します。

ツールのインストールと実行

ツールで RID 固有のパッケージ化を使用するかどうかは、ユーザーに対して透過的な実装の詳細です。 ツール開発者が RID 固有のパッケージ化を選択したかどうかに関係なく、ツールをインストールして実行する方法は同じです。

ツールをグローバルにインストールするには:

dotnet tool install -g mytool

インストールが完了したら、それを直接呼び出すことができます。

mytool

dnx ヘルパーを使用することもできます。これは、Node.js エコシステムのnpxと同様に動作します。ツールがまだ存在しない場合は、1 つのジェスチャでツールをダウンロードして起動します。

dnx mytool

ツールで RID 固有のパッケージを使用すると、.NET CLI によってプラットフォームに適したパッケージが自動的に選択されます。 RID を指定する必要はありません。CLI はシステムから RID を推論し、適切な RID 固有のパッケージをダウンロードします。

こちらも参照ください

• チュートリアル: .NET ツールを作成する
• .NET ツールの概要
• dotnet pack コマンド
• RID カタログ
• ネイティブ AOT デプロイ