Skip to content

Update tool and template tutorials for .NET 5 #21956

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Dec 14, 2020
Merged

Update tool and template tutorials for .NET 5 #21956

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2eccbe1
update for .net 5
tdykstra Dec 11, 2020
bc8029d
remove outdated ref to version 2.1.4
tdykstra Dec 11, 2020
1840354
update to current ui
tdykstra Dec 11, 2020
75bf1c4
more updates
tdykstra Dec 11, 2020
97ce227
nowarn
tdykstra Dec 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/core/tools/global-tools-how-to-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ This tutorial teaches you how to create and package a .NET tool. The .NET CLI le

The tool that you'll create is a console application that takes a message as input and displays the message along with lines of text that create the image of a robot.

This is the first in a series of three tutorials. In this tutorial, you create and package a tool. In the next two tutorials you [use the tool as a global tool](global-tools-how-to-use.md) and [use the tool as a local tool](local-tools-how-to-use.md).
This is the first in a series of three tutorials. In this tutorial, you create and package a tool. In the next two tutorials you [use the tool as a global tool](global-tools-how-to-use.md) and [use the tool as a local tool](local-tools-how-to-use.md). The procedures for creating a tool are the same whether you use it as a global tool or as a local tool.

## Prerequisites

- [.NET Core SDK 3.1](https://dotnet.microsoft.com/download) or a later version.
- [.NET SDK 5.0](https://dotnet.microsoft.com/download) or a later version.

This tutorial and the following [tutorial for global tools](global-tools-how-to-use.md) apply to .NET Core SDK 2.1 and later versions because global tools are available starting in that version. But this tutorial assumes you have installed 3.1 or later so that you have the option of continuing on to the [local tools tutorial](local-tools-how-to-use.md). Local tools are available starting in .NET Core SDK 3.0. The procedures for creating a tool are the same whether you use it as a global tool or as a local tool.
This tutorial uses .NET SDK 5.0, but global tools are available starting in .NET Core SDK 2.1. Local tools are available starting in .NET Core SDK 3.0.

- A text editor or code editor of your choice.

Expand Down Expand Up @@ -153,7 +153,7 @@ Before you can pack and distribute the application as a tool, you need to modify

`<ToolCommandName>` is an optional element that specifies the command that will invoke the tool after it's installed. If this element isn't provided, the command name for the tool is the project file name without the *.csproj* extension.

`<PackageOutputPath>` is an optional element that determines where the NuGet package will be produced. The NuGet package is what the .NET Core CLI uses to install your tool.
`<PackageOutputPath>` is an optional element that determines where the NuGet package will be produced. The NuGet package is what the .NET CLI uses to install your tool.

The project file now looks like the following example:

Expand All @@ -163,7 +163,7 @@ Before you can pack and distribute the application as a tool, you need to modify
<PropertyGroup>

<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp3.1</TargetFramework>
<TargetFramework>net5.0</TargetFramework>

<PackAsTool>true</PackAsTool>
<ToolCommandName>botsay</ToolCommandName>
Expand Down
8 changes: 4 additions & 4 deletions docs/core/tools/local-tools-how-to-use.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "Tutorial: Install and use .NET local tools"
description: Learn how to install and use a .NET tool as a local tool.
ms.topic: tutorial
ms.date: 02/12/2020
ms.date: 12/11/2020
---

# Tutorial: Install and use a .NET local tool using the .NET CLI
Expand Down Expand Up @@ -167,7 +167,7 @@ You typically install a local tool in the root directory of the repository. Afte

## Update a local tool

The installed version of local tool `dotnetsay` is 2.1.3. The latest version is 2.1.4. Use the [dotnet tool update](dotnet-tool-update.md) command to update the tool to the latest version.
The installed version of local tool `dotnetsay` is 2.1.3. Use the [dotnet tool update](dotnet-tool-update.md) command to update the tool to the latest version.

```dotnetcli
dotnet tool update dotnetsay
Expand All @@ -176,7 +176,7 @@ dotnet tool update dotnetsay
The output indicates the new version number:

```console
Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.4'
Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '2.1.7'
(manifest file /home/name/repository/.config/dotnet-tools.json).
```

Expand All @@ -200,4 +200,4 @@ If you get an error message while following the tutorial, see [Troubleshoot .NET

## See also

For more information, see [.NET Core tools](global-tools.md)
For more information, see [.NET tools](global-tools.md)
64 changes: 31 additions & 33 deletions docs/core/tutorials/cli-templates-create-item-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
---
title: Create an item template for dotnet new - .NET Core CLI
title: Create an item template for dotnet new - .NET CLI
description: Learn how to create an item template for the dotnet new command. Item templates can contain any number of files.
author: adegeo
ms.date: 06/25/2019
ms.date: 12/11/2020
ms.topic: tutorial
ms.author: adegeo
---

# Tutorial: Create an item template

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.
With .NET, 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.

In this part of the series, you'll learn how to:

Expand All @@ -23,7 +23,7 @@ In this part of the series, you'll learn how to:

## Prerequisites

* [.NET Core 2.2 SDK](https://dotnet.microsoft.com/download) or later versions.
* [.NET 5.0 SDK](https://dotnet.microsoft.com/download) or a later version.
* Read the reference article [Custom templates for dotnet new](../tools/custom-templates.md).

The reference article explains the basics about templates and how they're put together. Some of this information will be reiterated here.
Expand Down Expand Up @@ -80,7 +80,7 @@ Now that you have the content of the template created, you need to create the te

## Create the template config

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_.
Templates are recognized 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_.

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_.

Expand Down Expand Up @@ -111,7 +111,7 @@ Open the _template.json_ with your favorite text editor and paste in the followi
}
```

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.
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 recommends so that users can easily filter the type of template they're searching for.

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).

Expand All @@ -132,14 +132,12 @@ Options:

... 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
Class library classlib [C#], F#, VB Common/Library
WPF Application wpf [C#], VB Common/WPF
Windows Forms (WinForms) Application winforms [C#], VB Common/WinForms
Worker Service worker [C#] Common/Worker/Web
Templates Short Name Language Tags
-------------------------------------------- ------------------- ------------ ----------------------
Example templates: string extensions stringext [C#] Common/Code
Console Application console [C#], F#, VB Common/Console
Class library classlib [C#], F#, VB Common/Library
WPF Application wpf [C#], VB Common/WPF
```

## Test the item template
Expand Down Expand Up @@ -204,11 +202,11 @@ You get the following output.
!dlroW olleH
```

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.
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.

## Uninstall the template

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.
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 `Uninstall Command` listed to uninstall your template.

```dotnetcli
dotnet new -u
Expand All @@ -220,31 +218,31 @@ You get output similar to the following.
Template Instantiation Commands for .NET Core CLI

Currently installed items:
Microsoft.DotNet.Common.ItemTemplates
Microsoft.DotNet.Common.ProjectTemplates.2.2
Details:
NuGetPackageId: Microsoft.DotNet.Common.ProjectTemplates.2.2
Version: 1.0.2-beta4
Author: Microsoft
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)
Class library (classlib) C#
Class library (classlib) F#
Class library (classlib) VB
Console Application (console) C#
Console Application (console) F#
Console Application (console) VB
Uninstall Command:
dotnet new -u Microsoft.DotNet.Common.ProjectTemplates.2.2

... 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
C:\working\templates\extensions
C:\Test\templatetutorial\working\templates\extensions
Templates:
Example templates: string extensions (stringext) C#
Uninstall Command:
dotnet new -u C:\working\templates\extensions
```

To uninstall a template, run the following command.
To uninstall the template that you created, run the `Uninstall Command` that is shown in the output.

```dotnetcli
dotnet new -u C:\working\templates\extensions
Expand Down
Loading