Skip to content

Commit e60919b

Browse files
ThrakaThraka
authored
Update cli templates to tutorial series (#13024)
* Finished Item and Project template sections * Start of nuget pkg * pack section almost done; going to break into other articles * Start of moving items into tutorial form * Acro item template article * Acro project template article * 80% finished with template pack article * Do TOC and redirect before I forget.. * Update minor syntax * Finished pack article * Add more links; remove old tutorial * fix bookmarks * Move files for better SEO * Files didn't move properly; moving files now * Fixed redirection * Update docs/core/tutorials/cli-templates-create-item-template.md Co-Authored-By: Maira Wenzel <mairaw@microsoft.com> * Set author to adegeo * Apply suggestions from code review Co-Authored-By: Maira Wenzel <mairaw@microsoft.com> * Change produces to contains * Update tutorial per feedback
1 parent 11dd506 commit e60919b

File tree

6 files changed

+635
-211
lines changed

6 files changed

+635
-211
lines changed

‎.openpublishing.redirection.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,6 +240,10 @@
240240
"source_path": "docs/core/tutorials/cli-console-app-tutorial-advanced.md",
241241
"redirect_url": "/dotnet/core/tutorials"
242242
},
243+
{
244+
"source_path": "docs/core/tutorials/create-custom-template.md",
245+
"redirect_url": "/dotnet/core/tutorials/cli-templates-create-item-template"
246+
},
243247
{
244248
"source_path": "docs/core/tutorials/libraries-with-vs.md",
245249
"redirect_url": "/dotnet/csharp/getting-started/library-with-visual-studio"

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

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
---
2+
title: Create an item template for dotnet new - .NET Core CLI
3+
description: Learn how to create an item template for the dotnet new command. Item templates can contain any number of files.
4+
author: thraka
5+
ms.date: 06/25/2019
6+
ms.topic: tutorial
7+
ms.author: adegeo
8+
---
9+
10+
# Tutorial: Create an item template
11+
12+
With .NET Core, you can create and deploy templates that generate projects, files, even resources. This tutorial is part one of a series that teaches you how to create, install, and uninstall, templates for use with the `dotnet new` command.
13+
14+
In this part of the series, you'll learn how to:
15+
16+
> [!div class="checklist"]
17+
> * Create a class for an item template
18+
> * Create the template config folder and file
19+
> * Install a template from a file path
20+
> * Test an item template
21+
> * Uninstall an item template
22+
23+
## Prerequisites
24+
25+
* [.NET Core 2.2 SDK](https://www.microsoft.com/net/core) or later versions.
26+
* Read the reference article [Custom templates for dotnet new](../tools/custom-templates.md).
27+
28+
The reference article explains the basics about templates and how they're put together. Some of this information will be reiterated here.
29+
30+
* Open a terminal and navigate to the _working\templates\\_ folder.
31+
32+
## Create the required folders
33+
34+
This series uses a "working folder" where your template source is contained and a "testing folder" used to test your templates. The working folder and testing folder should be under the same parent folder.
35+
36+
First, create the parent folder, the name does not matter. Then, create a subfolder named _working_. Inside of the _working_ folder, create a subfolder named _templates_.
37+
38+
Next, create a folder under the parent folder named _test_. The folder structure should look like the following:
39+
40+
```console
41+
parent_folder
42+
├───test
43+
└───working
44+
└───templates
45+
```
46+
47+
## Create an item template
48+
49+
An item template is a specific type of template that contains one or more files. These types of templates are useful when you want to generate something like a config, code, or solution file. In this example, you'll create a class that adds an extension method to the string type.
50+
51+
In your terminal, navigate to the _working\templates\\_ folder and create a new subfolder named _extensions_. Enter the folder.
52+
53+
```console
54+
working
55+
└───templates
56+
└───extensions
57+
```
58+
59+
Create a new file named _CommonExtensions.cs_ and open it with your favorite text editor. This class will provide an extension method named `Reverse` that reverses the contents of a string. Paste in the following code and save the file:
60+
61+
```csharp
62+
using System;
63+
64+
namespace System
65+
{
66+
public static class StringExtensions
67+
{
68+
public static string Reverse(this string value)
69+
{
70+
var tempArray = value.ToCharArray();
71+
Array.Reverse(tempArray);
72+
return new string(tempArray);
73+
}
74+
}
75+
}
76+
```
77+
78+
Now that you have the content of the template created, you need to create the template config at the root folder of the template.
79+
80+
## Create the template config
81+
82+
Templates are recognized in .NET Core by a special folder and config file that exist at the root of your template. In this tutorial, your template folder is located at _working\templates\extensions\\_.
83+
84+
When you create a template, all files and folders in the template folder are included as part of the template except for the special config folder. This config folder is named _.template.config_.
85+
86+
First, create a new subfolder named _.template.config_, enter it. Then, create a new file named _template.json_. Your folder structure should look like this:
87+
88+
```console
89+
working
90+
└───templates
91+
└───extensions
92+
└───.template.config
93+
template.json
94+
```
95+
96+
Open the _template.json_ with your favorite text editor and paste in the following JSON code and save it:
97+
98+
```json
99+
{
100+
"$schema": "http://json.schemastore.org/template",
101+
"author": "Me",
102+
"classifications": [ "Common", "Code" ],
103+
"identity": "ExampleTemplate.StringExtensions",
104+
"name": "Example templates: string extensions",
105+
"shortName": "stringext",
106+
"tags": {
107+
"language": "C#",
108+
"type": "item"
109+
}
110+
}
111+
```
112+
113+
This config file contains all the settings for your template. You can see the basic settings, such as `name` and `shortName`, but there's also a `tags/type` value that is set to `item`. This categorizes your template as an item template. There's no restriction on the type of template you create. The `item` and `project` values are common names that .NET Core recommends so that users can easily filter the type of template they're searching for.
114+
115+
The `classifications` item represents the **tags** column you see when you run `dotnet new` and get a list of templates. Users can also search based on classification tags. Don't confuse the `tags` property in the \*.json file with the `classifications` tags list. They're two different things unfortunately named similarly. The full schema for the *template.json* file is found at the [JSON Schema Store](http://json.schemastore.org/template). For more information about the *template.json* file, see the [dotnet templating wiki](https://github.com/dotnet/templating/wiki).
116+
117+
Now that you have a valid _.template.config/template.json_ file, your template is ready to be installed. In your terminal, navigate to the _extensions_ folder and run the following command to install the template located at the current folder:
118+
119+
* **On Windows**: `dotnet new -i .\`
120+
* **On Linux or macOS**: `dotnet new -i ./`
121+
122+
This command outputs the list of templates installed, which should include yours.
123+
124+
```console
125+
C:\working\templates\extensions> dotnet new -i .\
126+
Usage: new [options]
127+
128+
Options:
129+
-h, --help Displays help for this command.
130+
-l, --list Lists templates containing the specified name. If no name is specified, lists all templates.
131+
132+
... cut to save space ...
133+
134+
Templates Short Name Language Tags
135+
-------------------------------------------------------------------------------------------------------------------------------
136+
Example templates: string extensions stringext [C#] Common/Code
137+
Console Application console [C#], F#, VB Common/Console
138+
Class library classlib [C#], F#, VB Common/Library
139+
WPF Application wpf [C#], VB Common/WPF
140+
Windows Forms (WinForms) Application winforms [C#], VB Common/WinForms
141+
Worker Service worker [C#] Common/Worker/Web
142+
```
143+
144+
## Test the item template
145+
146+
Now that you have an item template installed, test it. Navigate to the _test/_ folder and create a new console application with `dotnet new console`. This generates a working project you can easily test with the `dotnet run` command.
147+
148+
```console
149+
C:\test> dotnet new console
150+
The template "Console Application" was created successfully.
151+
152+
Processing post-creation actions...
153+
Running 'dotnet restore' on C:\test\test.csproj...
154+
Restore completed in 54.82 ms for C:\test\test.csproj.
155+
156+
Restore succeeded.
157+
```
158+
159+
```console
160+
C:\test> dotnet run
161+
Hello World!
162+
```
163+
164+
Next, run `dotnet new stringext` to generate the _CommonExtensions.cs_ from the template.
165+
166+
```console
167+
C:\test> dotnet new stringext
168+
The template "Example templates: string extensions" was created successfully.
169+
```
170+
171+
Change the code in _Program.cs_ to reverse the `"Hello World"` string with the extension method provided by the template.
172+
173+
```csharp
174+
Console.WriteLine("Hello World!".Reverse());
175+
```
176+
177+
Run the program again and you'll see that the result is reversed.
178+
179+
```console
180+
C:\test> dotnet run
181+
!dlroW olleH
182+
```
183+
184+
Congratulations! You created and deployed an item template with .NET Core. 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.
185+
186+
## Uninstall the template
187+
188+
Because you installed the template by file path, you must uninstall it with the **absolute** file path. You can see a list of templates installed by running the `dotnet new -u` command. Your template should be listed last. Use the path listed to uninstall your template with the `dotnet new -u <ABSOLUTE PATH TO TEMPLATE DIRECTORY>` command.
189+
190+
```console
191+
C:\working> dotnet new -u
192+
Template Instantiation Commands for .NET Core CLI
193+
194+
Currently installed items:
195+
Microsoft.DotNet.Common.ItemTemplates
196+
Templates:
197+
dotnet gitignore file (gitignore)
198+
global.json file (globaljson)
199+
NuGet Config (nugetconfig)
200+
Solution File (sln)
201+
Dotnet local tool manifest file (tool-manifest)
202+
Web Config (webconfig)
203+
204+
... cut to save space ...
205+
206+
NUnit3.DotNetNew.Template
207+
Templates:
208+
NUnit 3 Test Project (nunit) C#
209+
NUnit 3 Test Item (nunit-test) C#
210+
NUnit 3 Test Project (nunit) F#
211+
NUnit 3 Test Item (nunit-test) F#
212+
NUnit 3 Test Project (nunit) VB
213+
NUnit 3 Test Item (nunit-test) VB
214+
C:\working\templates\extensions
215+
Templates:
216+
Example templates: string extensions (stringext) C#
217+
```
218+
219+
```console
220+
C:\working> dotnet new -u C:\working\templates\extensions
221+
```
222+
223+
## Next steps
224+
225+
In this tutorial, you created an item template. To learn how to create a project template, continue this tutorial series.
226+
227+
> [!div class="nextstepaction"]
228+
> [Create a project template](cli-templates-create-project-template.md)

0 commit comments

Comments
 (0)