You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/core/tutorials/cli-templates-create-template-package.md
+194-5Lines changed: 194 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,15 @@ title: Create a template package for dotnet new
3
3
description: Learn how to create a csproj file that will build a template package for the dotnet new command.
4
4
author: adegeo
5
5
ms.date: 02/03/2022
6
+
zone_pivot_groups: dotnet-preview-version
6
7
ms.topic: tutorial
7
8
ms.author: adegeo
8
9
---
9
10
10
11
# Tutorial: Create a template package
11
12
13
+
::: zone pivot="dotnet-8-0"
14
+
12
15
With .NET, you can create and deploy templates that generate projects, files, and 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.
13
16
14
17
You can view the completed template in the [.NET Samples GitHub repository](https://github.com/dotnet/samples/tree/main/core/tutorials/cli-templates-create-item-template).
@@ -29,8 +32,6 @@ In this part of the series you'll learn how to:
A template package is one or more templates packed into a NuGet package. When you install or uninstall a template package, all templates contained in the package are added or removed, respectively.
@@ -118,7 +119,7 @@ The _content_ folder has two folders: _extensions_ and _consoleasync_. By defaul
118
119
119
120
In your terminal, from the _working_ folder, run the `dotnet pack` command. This command builds your project and creates a NuGet package in the _working\bin\Debug_ folder, as indicated by the following output:
120
121
121
-
```console
122
+
```output
122
123
C:\working> dotnet pack
123
124
124
125
Microsoft (R) Build Engine version 16.8.0+126527ff1 for .NET
@@ -132,6 +133,193 @@ Copyright (C) Microsoft Corporation. All rights reserved.
132
133
133
134
Next, install the template package with the `dotnet new install` command.
134
135
136
+
```output
137
+
C:\working> dotnet new install C:\working\bin\Debug\AdatumCorporation.Utility.Templates.1.0.0.nupkg
138
+
The following template packages will be installed:
Example templates: string extensions stringext [C#] Common/Code
145
+
Example templates: async project consoleasync [C#] Common/Console/C#9
146
+
```
147
+
148
+
If you uploaded the NuGet package to a NuGet feed, you can use the `dotnet new install <PACKAGE_ID>` command where `<PACKAGE_ID>` is the same as the `<PackageId>` setting from the _.csproj_ file. This package ID is the same as the NuGet package identifier.
149
+
150
+
## Uninstall the template package
151
+
152
+
No matter how you installed the template package, either with the _.nupkg_ file directly or by NuGet feed, removing a template package 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 uninstall` command.
Example templates: async project (consoleasync) C#
166
+
Example templates: string extensions (stringext) C#
167
+
Uninstall Command:
168
+
dotnet new uninstall AdatumCorporation.Utility.Templates
169
+
```
170
+
171
+
Run `dotnet new uninstall AdatumCorporation.Utility.Templates` to uninstall the template package. The command will output information about what template packages were uninstalled.
172
+
173
+
Congratulations! You've installed and uninstalled a template package.
174
+
175
+
## Next steps
176
+
177
+
To learn more about templates, most of which you've already learned, see the [Custom templates for dotnet new](../tools/custom-templates.md) article.
*[*template.json* schema at the JSON Schema Store](http://json.schemastore.org/template)
183
+
184
+
::: zone-end
185
+
186
+
::: zone pivot="dotnet-7-0,dotnet-6-0"
187
+
188
+
With .NET, you can create and deploy templates that generate projects, files, and 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.
189
+
190
+
You can view the completed template in the [.NET Samples GitHub repository](https://github.com/dotnet/samples/tree/main/core/tutorials/cli-templates-create-item-template).
191
+
192
+
In this part of the series you'll learn how to:
193
+
194
+
> [!div class="checklist"]
195
+
>
196
+
> * Create a \*.csproj project to build a template package
197
+
> * Configure the project file for packing
198
+
> * Install a template package from a NuGet package file
199
+
> * Uninstall a template package by package ID
200
+
201
+
## Prerequisites
202
+
203
+
* Complete [part 1](cli-templates-create-item-template.md) and [part 2](cli-templates-create-project-template.md) of this tutorial series.
204
+
205
+
This tutorial uses the two templates created in the first two parts of this tutorial. You can use a different template as long as you copy the template, as a folder, into the _working\templates\\_ folder.
206
+
207
+
* Open a terminal and navigate to the _working\\_ folder.
A template package is one or more templates packaged into a NuGet package. When you install or uninstall a template package, all templates contained in the package 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 package can have more than one template in it, and is a single file, sharing is easier.
214
+
215
+
Template packages are represented by a NuGet package (_.nupkg_) file. And, like any NuGet package, you can upload the template package to a NuGet feed. The `dotnet new install` command supports installing template package from a NuGet package feed. Additionally, you can install a template package from a _.nupkg_ file directly.
216
+
217
+
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 package. 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 package NuGet package.
218
+
219
+
The package you'll create will include the [item template](cli-templates-create-item-template.md) and [package template](cli-templates-create-project-template.md) previously created. Because we grouped the two templates into the _working\templates\\_ folder, we can use the _working_ folder for the _.csproj_ file.
220
+
221
+
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.
222
+
223
+
```dotnetcli
224
+
dotnet new console -n templatepack -o .
225
+
```
226
+
227
+
The `-n` parameter sets the _.csproj_ filename to _templatepack.csproj_. The `-o` parameter creates the files in the current directory. You should see a result similar to the following output.
228
+
229
+
```console
230
+
The template "Console Application" was created successfully.
231
+
232
+
Processing post-creation actions...
233
+
Running 'dotnet restore' on .\templatepack.csproj...
234
+
Restore completed in 52.38 ms for C:\working\templatepack.csproj.
235
+
236
+
Restore succeeded.
237
+
```
238
+
239
+
The new project template generates a _Program.cs_ file. You can safely delete this file as it's not used by the templates.
240
+
241
+
Next, open the _templatepack.csproj_ file in your favorite editor and replace the content with the following XML:
The settings under `<PropertyGroup>` in the XML snippet are broken into three groups.
273
+
274
+
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 `<PackageId>` value is used to uninstall the template package with a single name instead of a directory path. It can also be used to install the template package from a NuGet feed. The remaining settings, such as `<Title>` and `<PackageTags>`, have to do with metadata displayed on the NuGet feed. For more information about NuGet settings, see [NuGet and MSBuild properties](/nuget/reference/msbuild-targets).
275
+
276
+
> [!NOTE]
277
+
> To ensure that the template package appears in `dotnet new search` results, set `<PackageType>` to `Template`.
278
+
279
+
In the second group, the `<TargetFramework>` setting ensures that MSBuild executes properly when you run the pack command to compile and pack the project.
280
+
281
+
The third group includes settings that have to do with configuring the project to include the templates in the appropriate folder in the NuGet pack when it's created:
282
+
283
+
* The `<NoWarn>` setting suppresses a warning message that doesn't apply to template package projects.
284
+
285
+
* The `<NoDefaultExcludes>` setting ensures that files and folders that start with a `.` (like `.gitignore`) are part of the template. The *default* behavior of NuGet packages is to ignore those files and folders.
286
+
287
+
`<ItemGroup>` contains two items. First, the `<Content>` item 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>` item excludes all code files from compiling no matter where they're located. This setting prevents the project that's used to create the template package from trying to compile the code in the _templates_ folder hierarchy.
288
+
289
+
## Build and install
290
+
291
+
Save the project file. Before building the template package, verify that your folder structure is correct. Any template you want to pack should be placed in the _templates_ folder, in its own folder. The folder structure should look similar to the following hierarchy:
292
+
293
+
```console
294
+
working
295
+
│ templatepack.csproj
296
+
└───templates
297
+
├───extensions
298
+
│ └───.template.config
299
+
│ template.json
300
+
└───consoleasync
301
+
└───.template.config
302
+
template.json
303
+
```
304
+
305
+
The _templates_ folder has two folders: _extensions_ and _consoleasync_.
306
+
307
+
In your terminal, from the _working_ folder, run the `dotnet pack` command. This command builds your project and creates a NuGet package in the _working\bin\Debug_ folder, as indicated by the following output:
308
+
309
+
```console
310
+
C:\working> dotnet pack
311
+
312
+
Microsoft (R) Build Engine version 16.8.0+126527ff1 for .NET
313
+
Copyright (C) Microsoft Corporation. All rights reserved.
314
+
315
+
Restore completed in 123.86 ms for C:\working\templatepack.csproj.
0 commit comments