次の方法で共有

チュートリアル: テンプレートパッケージを作成する

  • [アーティクル]

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

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

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

  • Microsoft.TemplateEngine.Authoring.Templates NuGet パッケージを使用してテンプレート パッケージを作成します。
  • NuGet パッケージ ファイルからテンプレート パッケージをインストールする。
  • パッケージ ID を使用してテンプレート パッケージをアンインストールする。
  • テンプレート パッケージをビルドするための *.csproj プロジェクトを作成する。
  • パックのためのプロジェクト ファイルを構成する。
  • NuGet パッケージ ファイルからテンプレート パッケージをインストールする。
  • パッケージ ID を使用してテンプレート パッケージをアンインストールする。

前提条件

  • このチュートリアル シリーズのパート 1 とパート 2 を完了します。

    このチュートリアルでは、このチュートリアル シリーズの最初の 2 つのパートで作成した 2 つのテンプレートを使います。 そのテンプレートをフォルダーとして working\content フォルダー内にコピーしていれば、別のテンプレートを使用することもできます。

  • ターミナルを開いて working フォルダーに移動します。

  • .NET 8 をインストールします。

  • NuGet パッケージ フィードから Microsoft.TemplateEngine.Authoring.Templates テンプレートをインストールします。

    • ターミナルから dotnet new install Microsoft.TemplateEngine.Authoring.Templates コマンドを実行します。

重要

この記事は、.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 コマンドを使用してください。

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

テンプレート パッケージは、NuGet パッケージにパックされた 1 つ以上のテンプレートです。 テンプレート パッケージをインストール/アンインストールすると、そのパッケージに含まれているすべてのテンプレートが追加/削除されます。

テンプレート パッケージは、NuGet パッケージ ( .nupkg) ファイルによって表されます。 また、すべての NuGet パッケージと同様に、テンプレート パッケージを NuGet フィードにアップロードできます。 dotnet new install コマンドは、NuGet パッケージ フィード、.nupkg ファイル、またはテンプレートを含むディレクトリからのテンプレート パッケージのインストールをサポートします。

通常は、C# プロジェクト ファイルを使用してコードをコンパイルし、バイナリを生成します。 しかし、プロジェクトを使用してテンプレート パッケージを生成することもできます。 .csproj の設定を変更して、コードがコンパイルされないようにし、代わりにテンプレートのすべての資産をリソースとして含めることができます。 このプロジェクトをビルドすると、テンプレート パッケージの NuGet パッケージが生成されます。

生成するパッケージには、[item] と (cli-templates-create-item-template.md) と、先ほど作成したプロジェクト テンプレートが含まれます。

Microsoft.TemplateEngine.Authoring.Templates パッケージには、テンプレートの作成に役立つテンプレートが含まれています。 このパッケージをインストールするには、作業ディレクトリで nuget.org が NuGet フィードとして使用できるようにする必要があります。

  1. working フォルダーで次のコマンドを実行して、テンプレート パッケージを作成します。

    dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

    -n パラメーターを指定して、プロジェクト ファイル名を AdatumCorporation.Utility.Templates.csproj に設定します。 次の出力のような結果が表示されます。

    The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

  2. 次に、コード エディターで AdatumCorporation.Utility.Templates.csproj ファイルを開き、テンプレートのヒントに従って設定します。

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

  1. working フォルダーで次のコマンドを実行して、テンプレート パッケージを作成します。

    dotnet new console -n AdatumCorporation.Utility.Templates

    -n パラメーターを指定して、プロジェクト ファイル名を AdatumCorporation.Utility.Templates.csproj に設定します。 次の出力のような結果が表示されます。

    The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on .\AdatumCorporation.Utility.Templates.csproj...
  Restore completed in 52.38 ms for C:\code\working\AdatumCorporation.Utility.Templates.csproj.

Restore succeeded.

  2. Program.cs ファイルを削除します。 新しいプロジェクト テンプレートを使うと、このファイルが生成されますが、テンプレート エンジンには使われません。

  3. 次に、お好みのテキスト エディターで AdatumCorporation.Utility.Templates.csproj ファイルを開き、コンテンツを次の XML で置き換えます。

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;adatum</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="content\**\*" Exclude="content\**\bin\**;content\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

プロジェクト XML の説明

XML スニペットの <PropertyGroup> の下の設定は、2 つのグループに分かれています。

最初のグループでは、NuGet パッケージに必要なプロパティが処理されます。 <Package*> の 4 つの設定は、NuGet フィード上でパッケージを識別するための NuGet パッケージ プロパティと関係しています。 NuGet で使われている <PackageId> 値は、テンプレート パッケージのアンインストールにも使われます。 <Title>、<PackageTags> などの残りの設定は、NuGet フィードと .NET パッケージ マネージャーに表示されるメタデータに関連しています。 NuGet の設定の詳細については、NuGet と MSBuild のプロパティに関する記事を参照してください。

Note

テンプレート パッケージが dotnet new search の結果に表示されるようにするには、<PackageType> を Template に設定する必要があります。

2 番目のグループの <TargetFramework> の設定により、pack コマンドを実行してプロジェクトをコンパイルおよびパックするときに、MSBuild が正しく実行されるようになります。 このグループには、テンプレートが作成されたときに NuGet パッケージ内の適切なフォルダーに含まれるようなプロジェクトの構成に関連する設定も含まれています。

  • <NoWarn> 設定を使用すると、テンプレート パッケージ プロジェクトに適用されない警告メッセージを非表示にすることができます。

  • <NoDefaultExcludes> の設定により、(.gitignore のような) . で始まるファイルとフォルダーがテンプレートに含まれるようになります。 NuGet パッケージの "既定" の動作では、これらのファイルとフォルダーは無視されます。

<ItemGroup> には 2 つの項目が含まれています。 まず、<Content> の項目には、templates フォルダー内のすべてのものがコンテンツとして含まれています。 また、コンパイル済みのコード (テンプレートをテストしてコンパイルした場合) が含まれないようにするために、すべての bin または obj フォルダーを除外するよう設定されます。 次に、<Compile> の項目では、すべてのコード ファイルがその場所に関係なくコンパイルから除外されます。 この設定により、テンプレート パッケージの作成に使用されているプロジェクトで templates フォルダー階層内のコードのコンパイルが試行されなくなります。

ヒント

NuGet メタデータ設定の詳細については、「テンプレートをパッケージ化し、NuGet パッケージ (nupkg ファイル) を作成する」を参照してください。

作成されたプロジェクト ファイルには、MSBuild タスクを作成するテンプレートとローカライズ設定が含まれます。

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

重要

content コンテンツ フォルダーには、SampleTemplate フォルダーが含まれています。 このフォルダーは、デモ目的で作成テンプレートに追加されたので削除します。

これらの MSBuild タスクは、テンプレートの検証と テンプレートのローカライズ機能を提供します。 ローカライズは既定で無効になっています。 ローカライズ ファイルの作成を有効にするには、LocalizeTemplates を true に設定します。

パックとインストール

プロジェクト ファイルを保存します。 テンプレート パッケージを構築する前に、フォルダー構造が正しいことを確認してください。 パックするすべてのテンプレートを、そのフォルダー内の templates フォルダーに配置する必要があります。 フォルダー構造は次の階層のようになります。

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

content フォルダーには、extensions と consoleasync という 2 つのフォルダーがあります。

ターミナルで、working フォルダーから dotnet pack コマンドを実行します。 このコマンドを実行すると、次の出力で示すように、プロジェクトがビルドされ、working\bin\Debug フォルダーに NuGet パッケージが作成されます。

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

次に、dotnet new install コマンドを使用してテンプレート パッケージをインストールします。 Windows の場合:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Linux または macOS の場合:

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

次のような出力が表示されます。

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

NuGet パッケージを NuGet フィードにアップロードした場合は、dotnet new install <PACKAGE_ID> コマンドを使用できます。ここで、<PACKAGE_ID> は .csproj ファイルに含まれる <PackageId> 設定と同じです。

テンプレート パッケージをアンインストールする

テンプレート パッケージを削除する方法は、テンプレート パッケージをインストールした方法 ( .nupkg ファイルを使用して直接、または NuGet フィードを使用) にかかわらず同じです。 アンインストールするテンプレートの <PackageId> を使用します。 dotnet new uninstall コマンドを実行すると、インストールされているテンプレートの一覧を取得できます。

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

dotnet new uninstall AdatumCorporation.Utility.Templates を実行してテンプレート パッケージをアンインストールします。 コマンドにより、アンインストールされたテンプレート パッケージに関する情報が出力されます。

おめでとうございます。 テンプレート パッケージをインストールしてアンインストールしました。

次のステップ

テンプレートの詳細については、ほとんどを既に説明しましたが、記事「dotnet new のカスタム テンプレート」を参照してください。