diff --git a/docs/core/tutorials/cli-templates-create-item-template.md b/docs/core/tutorials/cli-templates-create-item-template.md index 22eefa5dde620..7fb0884e4d0a4 100644 --- a/docs/core/tutorials/cli-templates-create-item-template.md +++ b/docs/core/tutorials/cli-templates-create-item-template.md @@ -167,7 +167,7 @@ dotnet run You get the following output. ```console -Hello World! +Hello, World! ``` Next, run `dotnet new stringext` to generate the _CommonExtensions.cs_ from the template. @@ -182,10 +182,10 @@ You get the following output. The template "Example templates: string extensions" was created successfully. ``` -Change the code in _Program.cs_ to reverse the `"Hello World"` string with the extension method provided by the template. +Change the code in _Program.cs_ to reverse the `"Hello, World!"` string with the extension method provided by the template. ```csharp -Console.WriteLine("Hello World!".Reverse()); +Console.WriteLine("Hello, World!".Reverse()); ``` Run the program again and you'll see that the result is reversed. @@ -197,7 +197,7 @@ dotnet run You get the following output. ```console -!dlroW olleH +!dlroW ,olleH ``` 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. diff --git a/docs/core/tutorials/cli-templates-create-project-template.md b/docs/core/tutorials/cli-templates-create-project-template.md index b66397adc30e6..26f9572047633 100644 --- a/docs/core/tutorials/cli-templates-create-project-template.md +++ b/docs/core/tutorials/cli-templates-create-project-template.md @@ -12,8 +12,6 @@ recommendations: false 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. -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). - > [!TIP] > The official .NET templates that are shipped with the .NET SDK can be found in the following repositories: > @@ -62,7 +60,7 @@ working ## Modify Program.cs -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: +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: ```csharp await Console.Out.WriteAsync("Hello World with C#"); diff --git a/docs/core/tutorials/cli-templates-create-template-package.md b/docs/core/tutorials/cli-templates-create-template-package.md index fe29529c6753c..2b535e24f5c21 100644 --- a/docs/core/tutorials/cli-templates-create-template-package.md +++ b/docs/core/tutorials/cli-templates-create-template-package.md @@ -3,12 +3,185 @@ title: Create a template package for dotnet new description: Learn how to create a csproj file that will build a template package for the dotnet new command. author: adegeo ms.date: 02/03/2022 +zone_pivot_groups: dotnet-preview-version ms.topic: tutorial ms.author: adegeo --- # Tutorial: Create a template package +::: zone pivot="dotnet-8-0" + +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. + +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). + +In this part of the series you'll learn how to: + +> [!div class="checklist"] +> +> * Create a template package by using the [Microsoft.TemplateEngine.Authoring.Templates](https://www.nuget.org/packages/Microsoft.TemplateEngine.Authoring.Templates) NuGet package. +> * Install a template package from a NuGet package file +> * Uninstall a template package by package ID + +## Prerequisites + +* Complete [part 1](cli-templates-create-item-template.md) and [part 2](cli-templates-create-project-template.md) of this tutorial series. + + 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. + +* Open a terminal and navigate to the _working\\_ folder. + +## Create a template package project + +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. + +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. + +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. + +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. + +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). +In your terminal, run the command: + +```dotnetcli +dotnet new install Microsoft.TemplateEngine.Authoring.Templates +``` + +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. + +Run the following command to create the template for the template package: + +```dotnetcli +dotnet new templatepack --output "AdatumCorporation.Utility.Templates" +``` + +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. + +```output +The template "Template Package" was created successfully. + +Processing post-creation actions... +Description: Manual actions required +Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to 'content' folder. Fill in README.md. +``` + +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: + +```xml + + + + AdatumCorporation.Utility.Templates + 1.0 + AdatumCorporation Templates + Me + Templates to use when creating an application for Adatum Corporation. + dotnet-new;templates;contoso + https://github.com/dotnet/samples/tree/main/core/tutorials/cli-templates-create-item-template + +``` + +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). + +By default, the created project file includes [template authoring MSBuild tasks](https://aka.ms/templating-authoring-tools). + +```xml + + false + + + + + +``` + +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`. + +## Build and install + +Save changes in _AdatumCorporation.Utility.Templates.csproj_ file. +Copy _extensions_ and _consoleasync_ folders with templates created in previous parts of tutorial to _content_ folder. +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: + +```console +AdatumCorporation.Utility.Templates +│ AdatumCorporation.Utility.Templates.csproj +└───content + ├───extensions + │ └───.template.config + │ template.json + └───consoleasync + └───.template.config + template.json +``` + +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. + +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: + +```output +C:\working\AdatumCorporation.Utility.Templates> dotnet pack +... cut to save space ... + AdatumCorporation.Utility.Templates -> C:\\working\AdatumCorporation.Utility.Templates\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll + Successfully created package 'C:\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'. +``` + +Next, install the template package with the `dotnet new install` command. + +```output +C:\working\AdatumCorporation.Utility.Templates> dotnet new install bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg +The following template packages will be installed: + C:\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg + +Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates: +Templates Short Name Language Tags +-------------------------------------------- ------------------- ------------ ---------------------- +Example templates: string extensions stringext [C#] Common/Code +Example templates: async project consoleasync [C#] Common/Console/C#9 +``` + +If you uploaded the NuGet package to a NuGet feed, you can use the `dotnet new install ` command where `` is the same as the `` setting from the _.csproj_ file. This package ID is the same as the NuGet package identifier. + +## Uninstall the template package + +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 `` of the template you want to uninstall. You can get a list of templates that are installed by running the `dotnet new uninstall` command. + +```output +C:\working> dotnet new uninstall +Currently installed items: +... cut to save space ... + + AdatumCorporation.Utility.Templates + Details: + NuGetPackageId: AdatumCorporation.Utility.Templates + Version: 1.0.0 + Author: Me + Templates: + Example templates: async project (consoleasync) C# + Example templates: string extensions (stringext) C# + Uninstall Command: + dotnet new uninstall AdatumCorporation.Utility.Templates +``` + +Run `dotnet new uninstall AdatumCorporation.Utility.Templates` to uninstall the template package. The command will output information about what template packages were uninstalled. + +Congratulations! You've installed and uninstalled a template package. + +## Next steps + +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 Authoring Tools](https://aka.ms/templating-authoring-tools) +* [dotnet/templating GitHub repo Wiki](https://github.com/dotnet/templating/wiki) +* [Template samples](https://aka.ms/template-samples) +* [*template.json* schema at the JSON Schema Store](http://json.schemastore.org/template) + +::: zone-end + +::: zone pivot="dotnet-7-0,dotnet-6-0" + 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. 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. To learn more about templates, most of which you've already learned, see the [Custom templates for dotnet new](../tools/custom-templates.md) article. * [dotnet/templating GitHub repo Wiki](https://github.com/dotnet/templating/wiki) -* [dotnet/dotnet-template-samples GitHub repo](https://github.com/dotnet/dotnet-template-samples) +* [Template samples](https://aka.ms/template-samples) * [*template.json* schema at the JSON Schema Store](http://json.schemastore.org/template) + +::: zone-end