.NET ローカル ツールの使い方

この記事はC# その2 Advent Calendar 2019 14日目の記事です。

.NET Core ツールとは

• .NET core グローバル ツール

.NET Core 2.1より、NuGetにアップロードされたコンソール アプリケーションをCLI上でインストール/実行/アップデート/アンインストールする仕組みができました。
それらのアプリケーションを総称して「.NET Core ツール」と呼びます。
npmでいうnpm install -g toolのイメージ。

メリットとしては、以下が挙げられます。

• dotnetコマンドが使える=.NET Core SDKが入っているので、ほぼ確実に事前セットアップなしでツールを使える
• (スクリプトコマンドと比べて)プラットフォームの差異を.NET Coreが吸収してくれる
• (従来のNuGetからのインストールと比べて)PATHが通っているので、実行パスが煩雑になりにくい
  • Nuget: ~/.nuget/packages/パッケージ名/バージョン/...
  • Tool: ~/.dotnet/tools
• (手動でのツール配布に比べて)NuGetの仕組みをそのまま利用できる
  • ファイルサーバにポン置きするだけでプライベート・リポジトリとして配信できる

.NET core グローバル ツールの使用例

# インストール
dotnet tool install -g ツールのパッケージ名

# 実行
# インストール先は.NET Core SDKによりPATHが通っているので、そのまま実行可能
ツールの実行ファイル名 arg1 arg2
# dotnet [コマンド名]で呼ぶように作られている場合
dotnet コマンド名 arg1 arg2

# アップデート
dotnet tool update -g ツールのパッケージ名
# アンインストール
dotnet tool uninstall -g ツールのパッケージ名

.NET Core ローカル ツールとは

npmのグローバルインストールが抱えるのと同様に、.NET Coreのグローバルツールは

• リポジトリごとに使用するツールを変えられない
• 複数人で開発時に、使用するツールのバージョン指定を強制できない

といった問題があります。
これらの問題を解決するために、.NET Core 3.0 SDKではツールをローカルにインストールできる仕組みが用意されました。

ちょっと違うけどnpmではnpm install --save-devのイメージ。

現在英語版を含めドキュメントがないので、仕様は以下のblogおよびissueを参考にしてください。

• Announcing .NET Core 3.0
• https://github.com/dotnet/cli/issues/10288

ローカル ツールを使ってみる

前項にもある通り、.NET Core SDK 3.0以降のバージョンを用意してください。

マニフェストファイルを作成する

パッケージのバージョン管理を行うためのdotnet-tools.jsonファイルを作成します。
プロジェクトのルートで以下のコマンドを実行してください。

dotnet new tool-manifest

実行すると、.configフォルダ内に以下のjsonファイルが生成されます。

.config/dotnet-tools.json

{
  "version": 1,
  "isRoot": true,
  "tools": {
  }
}

ツールをローカルにインストールする

-gオプションを付けないことでローカルインストールになります。
(前述のjsonファイルがないとエラーになります。)

dotnet tool install dotnet-format

実行後、jsonファイルにインストールしたツールとバージョンが書き込まれます。

.config/dotnet-tools.json

 {
   "version": 1,
   "isRoot": true,
   "tools": {
+    "dotnet-format": {
+      "version": "3.1.37601",
+      "commands": [
+        "dotnet-format"
+      ]
+    }
   }
 }

ツールを実行する

実行手段や引数などはツールによって異なるため、ツールのドキュメントを確認してください。

dotnet format

ローカル ツールを復元する

リポジトリからクローンした直後など、まだローカルツールをセットアップしていない場合は、下記のコマンドを実行します。
dotnet-tools.jsonの内容をチェックして、指定されたバージョンのツールがインストールされます。
(npmでいうnpm installのイメージ)

dotnet tool restore

有用なツール類

自分は以下のツールをよく使っています。

• dotnet-format
  • Lintツール
  • ルールは.editorconfigをベースに拡張(記法)
• dotnet-t4
  • Monoベースで作られたテキストテンプレートエンジン(.tt)
  • vscodeでもT4できるようになる

他にも、有用なツールの一覧が以下にまとめられています。

• https://github.com/natemcmaster/dotnet-tools

ツールを自作する

時間があれば作ります
「Postgresqlのテーブル一覧情報を取得し、POCOなクラスを生成する」ツールを作っていましたが、ものの見事にGit for WindowsのAutoCrLf機能でハマってしまったので間に合わず。
作りかけ状態のリポジトリがこちらになります。
dotnet-pg-entity

まとめ

• .NET core CLIからツールを使える仕組みがあるよ
• まだドキュメント化されていないけどローカルインストールもできるようになったよ
• 有用なツールを使って、コードの品質や生産性を上げていきましょう