チュートリアル: 項目テンプレートを作成する

  • [アーティクル]

.NET を使用すると、プロジェクト、ファイル、リソースを生成するテンプレートを作成して配置することができます。 このチュートリアルは、dotnet new コマンドで使用するテンプレートの作成、インストール、アンインストール方法を説明するシリーズのパート 1 です。

完成したテンプレートは、.NET サンプル GitHub リポジトリで表示することができます。

ヒント

項目テンプレートは、Visual Studio の [追加]>[新しい項目] ダイアログには表示されません。

シリーズのこのパートで学習する内容は次のとおりです。

  • 項目テンプレートのクラスを作成する。
  • テンプレートの構成フォルダーとファイルを作成する。
  • ファイル パスからテンプレートをインストールする。
  • 項目テンプレートをテストする。
  • 項目テンプレートをアンインストールする。

前提条件

  • .NET SDK 7.0.100 以降のバージョン。

    この参照記事では、テンプレートの基本と、テンプレートをまとめる方法が説明されています。 ここでは、この情報の一部を繰り返して示します。

  • ターミナルを開き、テンプレートを保存してテストするためのフォルダーに移動します。

重要

この記事は、.NET 7 用に作成されています。 ただし、構文 dotnet new が異なることを除き、.NET 6 以前のバージョンにも適用できます。 list、search、install、および uninstall のサブコマンドが、それぞれ --list、--search、--install、および --uninstall オプションになります。

たとえば、.NET 7 の dotnet new install コマンドは、.NET 6 で dotnet new --install になります。 すべてのオプションとサブコマンドの一覧を表示するには、dotnet new --help コマンドを使用してください。

必要なフォルダーを作成する

このシリーズでは、テンプレートのソースが含まれる "作業フォルダー" と、テンプレートをテストするための "テスト フォルダー" を使用します。 作業フォルダーとテスト フォルダーは、同じ親フォルダーの下に配置する必要があります。

まず、親フォルダーを作成します。名前は何でもかまいません。 次に、working と test という名前のサブフォルダーを 2 つ作成します。 working フォルダー内に、content という名前のサブフォルダーを作成します。

フォルダー構造は次のようになります。

parent_folder
├───test
└───working
    └───content

項目テンプレートを作成する

項目テンプレートは、1 つ以上のファイルを含む特定の種類のテンプレートです。 これらの種類のテンプレートは、既にプロジェクトがあり、構成ファイルやコード ファイルなどの別のファイルを生成する場合に便利です。 この例では、文字列型に拡張メソッドを追加するクラスを作成します。

ターミナルで working\content フォルダーに移動し、extensions という名前の新しいサブフォルダーを作成します。

working
└───content
    └───extensions

etensions フォルダーに移動し、StringExtensions.cs という名前の新しいファイルを作成します。 テキスト エディターで ファイルを開きます。 このクラスにより、文字列のコンテンツを反転させる Reverse という名前の拡張メソッドが提供されます。 次のコードを貼り付けて、ファイルを保存します。

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

テンプレートのコンテンツが完了したら、次の手順としてテンプレート構成を作成します。

テンプレートの構成を作成する

チュートリアルのこの部分では、テンプレート フォルダーは working\content\extensions にあります。

テンプレート フォルダーのルートには特別なフォルダーと構成ファイルが存在するため、テンプレートが .NET によって認識されます。

まず、.template.config という名前の新しいサブフォルダーを作成し、このフォルダーに入ります。 次に、template.json という名前の新しいファイルを作成します。 フォルダー構造は次のようになります。

working
└───content
    └───extensions
        └───.template.config
                template.json

お好みのテキスト エディターで template.json を開き、次の JSON コードを貼り付けて保存します。

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

この構成ファイルには、テンプレートのすべての設定が含まれます。 name や shortName などの基本設定を確認できますが、item に設定された tags/type 値もあります。 これにより、テンプレートが "項目" テンプレートとして分類されます。 作成するテンプレートの種類に制限はありません。 item および project 値は、ユーザーが検索しているテンプレートの種類を簡単にフィルター処理できるように .NET で推奨されている一般的な名前です。

classifications 項目は、dotnet new を実行してテンプレートの一覧を取得したときに表示される tags 列を表します。 ユーザーは分類タグに基づいて検索することもできます。 template.json ファイル内の tags プロパティと、classifications の tags 一 覧を混同しないようにしてください。 これらは、残念なことに同じ名前になっていますが、2 つの異なる概念です。 template.json ファイルの完全スキーマは JSON Schema Store にあり、「template.json のリファレンス」に説明があります。 template.json ファイルについて詳しくは、dotnet テンプレート wiki をご覧ください。

この JSON オブジェクトの symbols 部分は、テンプレートで使用できるパラメーターを定義するために使用されます。 この場合、1 つのパラメータが定義されています ClassName。 定義されたパラメータには、次の設定が含まれています。

  • type - これは必須の設定であり、parameter を設定する必要があります。
  • description - パラメータの説明。テンプレート ヘルプに出力されます。
  • datatype - パラメータを使用する場合のパラメータ値のデータ型。
  • replaces - すべてのテンプレート ファイルでパラメータの値で置き換えるテキスト値を指定します。
  • fileRename - replaces 同様に、すべてのテンプレート ファイルの名前でパラメータの値に置き換えられるテキスト値を指定します。
  • defaultValue - パラメータがユーザーによって指定されていない場合の、このパラメータの既定値。

テンプレートを使用すると、ユーザーは ClassName パラメータの値を指定できます。この値は、 StringExtensionsのすべての出現回数を置き換えます。 値が指定されていない場合は、defaultValue が使用されます。 このテンプレートでは、StringExtensions.cs ファイルと StringExtensions クラスの 2 つの出現回数StringExtensionsがあります。 パラメータの defaultValue は StringExtensions であるため、テンプレートの使用時にパラメータが指定されていない場合、ファイル名とクラス名は変更されません。 たとえばdotnet new stringext -ClassName MyExts、値を指定すると、ファイルの名前が MyExts.cs になり、クラスの名前が MyExts に変更されます。

テンプレートで使用できるパラメータを確認するには、テンプレート名と共に -? パラメータを使用します。

dotnet new stringext -?

次の出力が生成されます。

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

有効な .template.config/template.json ファイルを用意したので、テンプレートをインストールする準備ができました。 ターミナルで extensions フォルダーに移動し、次のコマンドを実行して現在のフォルダーにあるテンプレートをインストールします。

  • Windows の場合: dotnet new install .\
  • Linux または macOS の場合: dotnet new install ./

このコマンドにより、インストールされているテンプレートの一覧が出力されます。作成したテンプレートも含まれているはずです。

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

項目テンプレートをテストする

項目テンプレートをインストールしたので、テストします。

  1. test フォルダーに移動します。

  2. dotnet new console コマンドを使用して、新しいコンソール アプリケーションを作成します。これにより、dotnet run コマンドを使用して簡単にテストできる作業プロジェクトが生成されます。

    dotnet new console

    次のような出力が得られます。

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.

  3. 次のコマンドを使用して、プロジェクトを実行します。

    dotnet run

    次の出力が得られます。

    Hello, World!

  4. テンプレートから StringExtensions.cs ファイルを生成するために dotnet new stringext を実行します。

    dotnet new stringext

    次の出力が得られます。

    The template "Example templates: string extensions" was created successfully.

  5. テンプレートによって提供される拡張メソッドを使用して、"Hello, World!" 文字列を反転するように Program.cs 内のコードを変更します。

    Console.WriteLine("Hello, World!".Reverse());

    プログラムをもう一度実行し、結果が反転されたことを確認します。

    dotnet run

    次の出力が得られます。

    !dlroW ,olleH

おめでとうございます! .NET で項目テンプレートを作成し、配置しました。 このチュートリアル シリーズの次のパートの準備として、作成したテンプレートをアンインストールします。 test フォルダー内のすべてのファイルとフォルダーも削除してください。 これにより、このチュートリアル シリーズの次のパートの準備が整った状態に戻ります。

テンプレートをアンインストールする

ターミナルで extensions フォルダーに移動し、次のコマンドを実行して現在のフォルダーにあるテンプレートをアンインストールします。

  • Windows の場合: dotnet new uninstall .\
  • Linux または macOS の場合: dotnet new uninstall ./

このコマンドにより、アンインストールされたテンプレートの一覧が出力されます。作成したテンプレートも含まれているはずです。

Success: <root path>\working\content\extensions was uninstalled.

いつでも dotnet new uninstall を使用して、インストールされているテンプレート パッケージの一覧を表示できます。これにはテンプレート パッケージごとに、それをアンインストールするコマンドも含まれています。

次の手順

このチュートリアルでは、項目テンプレートを作成しました。 プロジェクト テンプレートを作成する方法については、このチュートリアル シリーズの続きを参照してください。

プロジェクト テンプレートを作成する