Tutorial: Create a template pack
With .NET Core, you can create and deploy templates that generate projects, files, even resources. This tutorial is part three of a series that teaches you how to create, install, and uninstall, templates for use with the
dotnet new command.
In this part of the series you'll learn how to:
- Create a _.csproj* project to build a template pack
- Configure the project file for packing
- Install a template from a NuGet package file
- Uninstall a template by package ID
This tutorial uses the two templates created in the first two parts of this tutorial. It's possible you can use a different template as long as you copy the template as a folder into the working\templates\ folder.
Open a terminal and navigate to the working\templates\ folder.
Create a template pack project
A template pack is one or more templates packaged into a file. When you install or uninstall a pack, all templates contained in the pack are added or removed, respectively. The previous parts of this tutorial series only worked with individual templates. To share a non-packed template, you have to copy the template folder and install via that folder. Because a template pack can have more than one template in it, and is a single file, sharing is easier.
Template packs are represented by a NuGet package (.nupkg) file. And, like any NuGet package, you can upload the template pack to a NuGet feed. The
dotnet new -i command supports installing template pack from a NuGet package feed. Additionally, you can install a template pack from a .nupkg file directly.
Normally you use a C# project file to compile code and produce a binary. However, the project can also be used to generate a template pack. By changing the settings of the .csproj, you can prevent it from compiling any code and instead include all the assets of your templates as resources. When this project is built, it produces a template pack NuGet package.
The pack you'll create will include the item template and package template previously created. Because we grouped the two templates into the working\templates\ folder, we can use the working folder for the .csproj file.
In your terminal, navigate to the working folder. Create a new project and set the name to
templatepack and the output folder to the current folder.
dotnet new console -n templatepack -o .
-n parameter sets the .csproj filename to templatepack.csproj and the
-o parameters creates the files in the current directory. You should see a result similar to the following output.
C:\working> dotnet new console -n templatepack -o . The template "Console Application" was created successfully. Processing post-creation actions... Running 'dotnet restore' on .\templatepack.csproj... Restore completed in 52.38 ms for C:\working\templatepack.csproj. Restore succeeded.
Next, open the templatepack.csproj file in your favorite editor and replace the content with the following XML:
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <PackageType>Template</PackageType> <PackageVersion>1.0</PackageVersion> <PackageId>AdatumCorporation.Utility.Templates</PackageId> <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> <TargetFramework>netstandard2.0</TargetFramework> <IncludeContentInPack>true</IncludeContentInPack> <IncludeBuildOutput>false</IncludeBuildOutput> <ContentTargetFolders>content</ContentTargetFolders> </PropertyGroup> <ItemGroup> <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> <Compile Remove="**\*" /> </ItemGroup> </Project>
<PropertyGroup> settings in the XML above is broken into three groups. The first group deals with properties required for a NuGet package. The three
<Package settings have to do with the NuGet package properties to identify your package on a NuGet feed. Specifically the
<PacakgeId> value is used to uninstall the template pack with a single name instead of a directory path. It can also be used to install the template pack from a NuGet feed. The remaining settings such as
<Tags> have to do with metadata displayed on the NuGet feed. For more information about NuGet settings, see NuGet and MSBuild properties.
<TargetFramework> setting must be set so that MSBuild will run properly when you run the pack command to compile and pack the project.
The last three settings have to do with configuring the project correctly to include the templates in the appropriate folder in the NuGet pack when it's created.
<ItemGroup> contains two settings. First, the
<Content> setting includes everything in the templates folder as content. It's also set to exclude any bin folder or obj folder to prevent any compiled code (if you tested and compiled your templates) from being included. Second, the
<Compile> setting excludes all code files from compiling no matter where they're located. This setting prevents the project being used to create a template pack from trying to compile the code in the templates folder hierarchy.
Build and install
Save this file and then run the pack command
This command will build your project and create a NuGet package in This should be the working\bin\Debug folder.
C:\working> dotnet pack Microsoft (R) Build Engine version 16.2.0-preview-19278-01+d635043bd for .NET Core Copyright (C) Microsoft Corporation. All rights reserved. Restore completed in 123.86 ms for C:\working\templatepack.csproj. templatepack -> C:\working\bin\Debug\netstandard2.0\templatepack.dll Successfully created package 'C:\working\bin\Debug\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.
Next, install the template pack file with the
dotnet new -i PATH_TO_NUPKG_FILE command.
C:\working> dotnet new -i C:\working\bin\Debug\AdatumCorporation.Utility.Templates.1.0.0.nupkg Usage: new [options] Options: -h, --help Displays help for this command. -l, --list Lists templates containing the specified name. If no name is specified, lists all templates. ... cut to save space ... Templates Short Name Language Tags ------------------------------------------------------------------------------------------------------------------------------- Example templates: string extensions stringext [C#] Common/Code Console Application console [C#], F#, VB Common/Console Example templates: async project consoleasync [C#] Common/Console/C#8 Class library classlib [C#], F#, VB Common/Library
If you uploaded the NuGet package to a NuGet feed, you can use the
dotnet new -i PACKAGEID command where
PACKAGEID is the same as the
<PackageId> setting from the .csproj file. This package ID is the same as the NuGet package identifier.
Uninstall the template pack
No matter how you installed the template pack, either with the .nupkg file directly or by NuGet feed, removing a template pack is the same. Use the
<PackageId> of the template you want to uninstall. You can get a list of templates that are installed by running the
dotnet new -u command.
C:\working> dotnet new -u Template Instantiation Commands for .NET Core CLI Currently installed items: Microsoft.DotNet.Common.ItemTemplates Templates: dotnet gitignore file (gitignore) global.json file (globaljson) NuGet Config (nugetconfig) Solution File (sln) Dotnet local tool manifest file (tool-manifest) Web Config (webconfig) ... cut to save space ... NUnit3.DotNetNew.Template Templates: NUnit 3 Test Project (nunit) C# NUnit 3 Test Item (nunit-test) C# NUnit 3 Test Project (nunit) F# NUnit 3 Test Item (nunit-test) F# NUnit 3 Test Project (nunit) VB NUnit 3 Test Item (nunit-test) VB AdatumCorporation.Utility.Templates Templates: Example templates: async project (consoleasync) C# Example templates: string extensions (stringext) C#
dotnet new -u AdatumCorporation.Utility.Templates to uninstall the template. The
dotnet new command will output help information that should omit the templates you previously installed.
Congratulations! you've installed and uninstalled a template pack.
To learn more about templates, most of which you've already learned, see the Custom templates for dotnet new article.