次の方法で共有


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

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

完成したテンプレートは、.NET Samples GitHub リポジトリで確認できます。

シリーズのこの部分では、次の方法を学習します。

  • Microsoft.TemplateEngine.Authoring.Templates NuGet パッケージを使用してテンプレート パッケージを作成します。
  • NuGet パッケージ ファイルからテンプレート パッケージをインストールします。
  • パッケージ ID でテンプレート パッケージをアンインストールします。

前提 条件

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

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

  • ターミナルを開き、作業 フォルダーに移動します。

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

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

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

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

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

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

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

生成するパッケージには、項目の と、以前に作成したプロジェクト テンプレート が含まれます。

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

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

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

    パラメーターは、プロジェクト ファイル名を 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 ...
    

プロジェクト XML の説明

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

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

手記

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

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

  • <NoWarn> 設定では、テンプレート パッケージ プロジェクトに適用されない警告メッセージが表示されなくなります。

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

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

ヒント

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

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

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

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

重要

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

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

梱包してインストールする

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

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

コンテンツ フォルダーには、拡張機能 と consoleasyncの 2 つのフォルダーがあります。

ターミナルで、作業 フォルダーから、dotnet pack コマンドを実行します。 このコマンドは、次の出力で示すように、プロジェクトをビルドし、working\bin\Release フォルダーに 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 フィードにアップロードした場合は、.csproj ファイルの <PackageId> 設定と同じ <PACKAGE_ID>dotnet new install <PACKAGE_ID> コマンドを使用できます。

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

.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 の新しい の カスタム テンプレートに関する記事を参照してください。