Skip to content

Commit 8cbddbb

Browse files
YuliiaKovalovaYuliiaKovalova
authored
Update cli-templates-create-template-package.md (#35985)
1 parent 9935075 commit 8cbddbb

File tree

3 files changed

+181
-8
lines changed

3 files changed

+181
-8
lines changed

‎docs/core/tutorials/cli-templates-create-item-template.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,7 @@ dotnet run
167167
You get the following output.
168168

169169
```console
170-
Hello World!
170+
Hello, World!
171171
```
172172

173173
Next, run `dotnet new stringext` to generate the _CommonExtensions.cs_ from the template.
@@ -182,10 +182,10 @@ You get the following output.
182182
The template "Example templates: string extensions" was created successfully.
183183
```
184184

185-
Change the code in _Program.cs_ to reverse the `"Hello World"` string with the extension method provided by the template.
185+
Change the code in _Program.cs_ to reverse the `"Hello, World!"` string with the extension method provided by the template.
186186

187187
```csharp
188-
Console.WriteLine("Hello World!".Reverse());
188+
Console.WriteLine("Hello, World!".Reverse());
189189
```
190190

191191
Run the program again and you'll see that the result is reversed.
@@ -197,7 +197,7 @@ dotnet run
197197
You get the following output.
198198

199199
```console
200-
!dlroW olleH
200+
!dlroW ,olleH
201201
```
202202

203203
Congratulations! You created and deployed an item template with .NET. In preparation for the next part of this tutorial series, you must uninstall the template you created. Make sure to delete all files from the _test_ folder too. This will get you back to a clean state ready for the next major section of this tutorial.

‎docs/core/tutorials/cli-templates-create-project-template.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,6 @@ recommendations: false
1212

1313
With .NET, you can create and deploy templates that generate projects, files, even resources. This tutorial is part two of a series that teaches you how to create, install, and uninstall, templates for use with the `dotnet new` command.
1414

15-
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).
16-
1715
> [!TIP]
1816
> The official .NET templates that are shipped with the .NET SDK can be found in the following repositories:
1917
>
@@ -62,7 +60,7 @@ working
6260

6361
## Modify Program.cs
6462

65-
Open up the _program.cs_ file. The standard console project doesn't asynchronously write to the console output, so let's add that. Change the code to the following and save the file:
63+
Open up the _Program.cs_ file. The standard console project doesn't asynchronously write to the console output, so let's add that. Change the code to the following and save the file:
6664

6765
```csharp
6866
await Console.Out.WriteAsync("Hello World with C#");

‎docs/core/tutorials/cli-templates-create-template-package.md‎

Lines changed: 176 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,185 @@ title: Create a template package for dotnet new
33
description: Learn how to create a csproj file that will build a template package for the dotnet new command.
44
author: adegeo
55
ms.date: 02/03/2022
6+
zone_pivot_groups: dotnet-preview-version
67
ms.topic: tutorial
78
ms.author: adegeo
89
---
910

1011
# Tutorial: Create a template package
1112

13+
::: zone pivot="dotnet-8-0"
14+
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.
16+
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).
18+
19+
In this part of the series you'll learn how to:
20+
21+
> [!div class="checklist"]
22+
>
23+
> * Create a template package by using the [Microsoft.TemplateEngine.Authoring.Templates](https://www.nuget.org/packages/Microsoft.TemplateEngine.Authoring.Templates) NuGet package.
24+
> * Install a template package from a NuGet package file
25+
> * Uninstall a template package by package ID
26+
27+
## Prerequisites
28+
29+
* Complete [part 1](cli-templates-create-item-template.md) and [part 2](cli-templates-create-project-template.md) of this tutorial series.
30+
31+
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.
32+
33+
* Open a terminal and navigate to the _working\\_ folder.
34+
35+
## Create a template package project
36+
37+
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.
38+
39+
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`](../tools/dotnet-new-install.md) command supports installing template packages from a NuGet package feed. Additionally, you can install a template package from a _.nupkg_ file directly.
40+
41+
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.
42+
43+
The package you are going to generate will include the [item template](cli-templates-create-item-template.md) and [package template](cli-templates-create-project-template.md) previously created.
44+
45+
In order to create the template package, you will use the template for the template package provided by [Microsoft.TemplateEngine.Authoring.Templates](https://www.nuget.org/packages/Microsoft.TemplateEngine.Authoring.Templates).
46+
In your terminal, run the command:
47+
48+
```dotnetcli
49+
dotnet new install Microsoft.TemplateEngine.Authoring.Templates
50+
```
51+
52+
This [template package](https://www.nuget.org/packages/Microsoft.TemplateEngine.Authoring.Templates) contains templates useful for template authoring. To install this package, nuget.org should be available as NuGet feed in the working directory.
53+
54+
Run the following command to create the template for the template package:
55+
56+
```dotnetcli
57+
dotnet new templatepack --output "AdatumCorporation.Utility.Templates"
58+
```
59+
60+
The `--output` parameter creates the template for template package in _AdatumCorporation.Utility.Templates_ subfolder and sets the _.csproj_ filename to _AdatumCorporation.Utility.Templates.csproj_. You should see a result similar to the following output.
61+
62+
```output
63+
The template "Template Package" was created successfully.
64+
65+
Processing post-creation actions...
66+
Description: Manual actions required
67+
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to 'content' folder. Fill in README.md.
68+
```
69+
70+
Next, navigate to _AdatumCorporation.Utility.Templates_ folder, open the _AdatumCorporation.Utility.Templates.csproj_ file in a code editor and populate it according to the hints in the template:
71+
72+
```xml
73+
<PropertyGroup>
74+
<!-- The package metadata. Fill in the properties marked as TODO below -->
75+
<!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
76+
<PackageId>AdatumCorporation.Utility.Templates</PackageId>
77+
<PackageVersion>1.0</PackageVersion>
78+
<Title>AdatumCorporation Templates</Title>
79+
<Authors>Me</Authors>
80+
<Description>Templates to use when creating an application for Adatum Corporation.</Description>
81+
<PackageTags>dotnet-new;templates;contoso</PackageTags>
82+
<PackageProjectUrl>https://github.com/dotnet/samples/tree/main/core/tutorials/cli-templates-create-item-template</PackageProjectUrl>
83+
</PropertyGroup>
84+
```
85+
86+
To get more information about NuGet package metadata available in the _AdatumCorporation.Utility.Templates.csproj_ file, navigate to [Pack a template into a NuGet package (nupkg file)](/dotnet/core/tools/custom-templates#pack-a-template-into-a-nuget-package-nupkg-file).
87+
88+
By default, the created project file includes [template authoring MSBuild tasks](https://aka.ms/templating-authoring-tools).
89+
90+
```xml
91+
<PropertyGroup>
92+
<LocalizeTemplates>false</LocalizeTemplates>
93+
</PropertyGroup>
94+
95+
<ItemGroup>
96+
<PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
97+
</ItemGroup>
98+
```
99+
100+
These MSBuild tasks provide template validation and [localization of the templates](https://aka.ms/templating-localization) capabilities. Localization is disabled by default. To enable creation of localization files, set `LocalizeTemplates` to `true`.
101+
102+
## Build and install
103+
104+
Save changes in _AdatumCorporation.Utility.Templates.csproj_ file.
105+
Copy _extensions_ and _consoleasync_ folders with templates created in previous parts of tutorial to _content_ folder.
106+
Before building the template package, verify that your folder structure is correct. Custom templates should be placed in the _content_ folder, in its own folder. The hierarchy should look similar to:
107+
108+
```console
109+
AdatumCorporation.Utility.Templates
110+
│ AdatumCorporation.Utility.Templates.csproj
111+
└───content
112+
├───extensions
113+
│ └───.template.config
114+
│ template.json
115+
└───consoleasync
116+
└───.template.config
117+
template.json
118+
```
119+
120+
The _content_ folder has two folders: _extensions_ and _consoleasync_. By default, _content_ also contains _SampleTemplate_, which can safely be deleted. It was added to the authoring template for demonstration purposes.
121+
122+
In your terminal, from the _AdatumCorporation.Utility.Templates_ 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:
123+
124+
```output
125+
C:\working\AdatumCorporation.Utility.Templates> dotnet pack
126+
... cut to save space ...
127+
AdatumCorporation.Utility.Templates -> C:\\working\AdatumCorporation.Utility.Templates\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
128+
Successfully created package 'C:\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.
129+
```
130+
131+
Next, install the template package with the `dotnet new install` command.
132+
133+
```output
134+
C:\working\AdatumCorporation.Utility.Templates> dotnet new install bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg
135+
The following template packages will be installed:
136+
C:\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg
137+
138+
Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
139+
Templates Short Name Language Tags
140+
-------------------------------------------- ------------------- ------------ ----------------------
141+
Example templates: string extensions stringext [C#] Common/Code
142+
Example templates: async project consoleasync [C#] Common/Console/C#9
143+
```
144+
145+
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.
146+
147+
## Uninstall the template package
148+
149+
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.
150+
151+
```output
152+
C:\working> dotnet new uninstall
153+
Currently installed items:
154+
... cut to save space ...
155+
156+
AdatumCorporation.Utility.Templates
157+
Details:
158+
NuGetPackageId: AdatumCorporation.Utility.Templates
159+
Version: 1.0.0
160+
Author: Me
161+
Templates:
162+
Example templates: async project (consoleasync) C#
163+
Example templates: string extensions (stringext) C#
164+
Uninstall Command:
165+
dotnet new uninstall AdatumCorporation.Utility.Templates
166+
```
167+
168+
Run `dotnet new uninstall AdatumCorporation.Utility.Templates` to uninstall the template package. The command will output information about what template packages were uninstalled.
169+
170+
Congratulations! You've installed and uninstalled a template package.
171+
172+
## Next steps
173+
174+
To learn more about templates, most of which you've already learned, see the [Custom templates for dotnet new](../tools/custom-templates.md) article.
175+
176+
* [Template Authoring Tools](https://aka.ms/templating-authoring-tools)
177+
* [dotnet/templating GitHub repo Wiki](https://github.com/dotnet/templating/wiki)
178+
* [Template samples](https://aka.ms/template-samples)
179+
* [*template.json* schema at the JSON Schema Store](http://json.schemastore.org/template)
180+
181+
::: zone-end
182+
183+
::: zone pivot="dotnet-7-0,dotnet-6-0"
184+
12185
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.
13186

14187
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).
@@ -188,5 +361,7 @@ Congratulations! You've installed and uninstalled a template package.
188361
To learn more about templates, most of which you've already learned, see the [Custom templates for dotnet new](../tools/custom-templates.md) article.
189362

190363
* [dotnet/templating GitHub repo Wiki](https://github.com/dotnet/templating/wiki)
191-
* [dotnet/dotnet-template-samples GitHub repo](https://github.com/dotnet/dotnet-template-samples)
364+
* [Template samples](https://aka.ms/template-samples)
192365
* [*template.json* schema at the JSON Schema Store](http://json.schemastore.org/template)
366+
367+
::: zone-end

0 commit comments

Comments
 (0)