Esercitazione: creare un modello di elementoTutorial: Create an item template

Con .NET Core è possibile creare e distribuire modelli per generare progetti, file e persino risorse.With .NET Core, you can create and deploy templates that generate projects, files, even resources. Questa esercitazione è la prima parte di una serie che illustra come creare, installare e disinstallare i modelli da usare con il comando dotnet new.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 questa parte della serie si apprenderà come:In this part of the series, you'll learn how to:

  • Creare una classe per un modello di elementoCreate a class for an item template
  • Creare la cartella e il file di configurazione del modelloCreate the template config folder and file
  • Installare un modello da un percorso di fileInstall a template from a file path
  • Testare un modello di elementoTest an item template
  • Disinstallare un modello di elementoUninstall an item template

PrerequisitiPrerequisites

  • .NET Core 2.2 SDK o versioni successive..NET Core 2.2 SDK or later versions.

  • Leggere l'articolo di riferimento Modelli personalizzati per dotnet new.Read the reference article Custom templates for dotnet new.

    L'articolo di riferimento presenta i concetti di base sui modelli e il modo in cui vengono creati.The reference article explains the basics about templates and how they're put together. Alcune di queste informazioni verranno ripetute qui.Some of this information will be reiterated here.

  • Aprire un terminale e passare alla cartella working\templatesOpen a terminal and navigate to the working\templates folder.

Creare le cartelle necessarieCreate the required folders

Questa serie usa una "cartella di lavoro" in cui è contenuta l'origine del modello e una "cartella di test" usata per testare i modelli.This series uses a "working folder" where your template source is contained and a "testing folder" used to test your templates. La cartella di lavoro e la cartella di test devono trovarsi nella stessa cartella padre.The working folder and testing folder should be under the same parent folder.

Prima di tutto creare la cartella padre. Il nome non è rilevante.First, create the parent folder, the name does not matter. Creare quindi una sottocartella denominata working.Then, create a subfolder named working. All'interno della cartella working creare una sottocartella denominata templates.Inside of the working folder, create a subfolder named templates.

Creare poi una cartella nella cartella padre denominata test.Next, create a folder under the parent folder named test. La struttura di cartelle dovrebbe essere simile alla seguente:The folder structure should look like the following:

parent_folder
├───test
└───working
    └───templates

Creare un modello di elementoCreate an item template

Un modello di elemento è un tipo specifico di modello che contiene uno o più file.An item template is a specific type of template that contains one or more files. Questi tipi di modelli sono utili quando si vogliono generare elementi come un file di configurazione, di codice o di soluzione.These types of templates are useful when you want to generate something like a config, code, or solution file. In questo esempio verrà creata una classe che aggiunge un metodo di estensione al tipo stringa.In this example, you'll create a class that adds an extension method to the string type.

Nel terminale passare alla cartella working\templates e creare una nuova sottocartella denominata Extensions.In your terminal, navigate to the working\templates folder and create a new subfolder named extensions. Accedere alla cartella.Enter the folder.

working
└───templates
    └───extensions

Creare un nuovo file denominato CommonExtensions.cs e aprirlo con l'editor di testo preferito.Create a new file named CommonExtensions.cs and open it with your favorite text editor. Questa classe fornirà un metodo di estensione denominato Reverse che inverte il contenuto di una stringa.This class will provide an extension method named Reverse that reverses the contents of a string. Incollare il codice seguente e salvare il file:Paste in the following code and save the file:

using System;

namespace System
{
    public static class StringExtensions
    {
        public static string Reverse(this string value)
        {
            var tempArray = value.ToCharArray();
            Array.Reverse(tempArray);
            return new string(tempArray);
        }
    }
}

Ora che è stato creato il contenuto del modello, è necessario creare la configurazione del modello nella cartella radice del modello.Now that you have the content of the template created, you need to create the template config at the root folder of the template.

Crea la configurazione del modelloCreate the template config

I modelli sono riconosciuti in .NET Core grazie a una cartella e a un file di configurazione speciali disponibili nella radice del modello.Templates are recognized in .NET Core by a special folder and config file that exist at the root of your template. In questa esercitazione la cartella dei modelli si trova in working\templates\extensions.In this tutorial, your template folder is located at working\templates\extensions.

Quando si crea un modello, tutti i file e le cartelle nella cartella del modello vengono inclusi come parte del modello, ad eccezione della cartella di configurazione speciale.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. Questa cartella di configurazione è denominata .template.config.This config folder is named .template.config.

Per prima cosa, creare una nuova sottocartella denominata .template.config e aprirla.First, create a new subfolder named .template.config, enter it. Creare quindi un nuovo file denominato template.json.Then, create a new file named template.json. La struttura di cartelle dovrebbe essere simile alla seguente:Your folder structure should look like this:

working
└───templates
    └───extensions
        └───.template.config
                template.json

Aprire il file template.json con l'editor di testo preferito, incollare il codice JSON seguente e salvarlo:Open the template.json with your favorite text editor and paste in the following JSON code and save it:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Me",
  "classifications": [ "Common", "Code" ],
  "identity": "ExampleTemplate.StringExtensions",
  "name": "Example templates: string extensions",
  "shortName": "stringext",
  "tags": {
    "language": "C#",
    "type": "item"
  }
}

Questo file di configurazione contiene tutte le impostazioni per il modello.This config file contains all the settings for your template. È possibile visualizzare le impostazioni di base, ad esempio name e shortName, ma anche un valore tags/type impostato su item.You can see the basic settings, such as name and shortName, but there's also a tags/type value that is set to item. In questo modo il modello viene categorizzato come modello di elemento.This categorizes your template as an item template. Non esiste alcuna restrizione per il tipo di modello che si può creare.There's no restriction on the type of template you create. I valori item e project sono nomi comuni consigliati da .NET Core in modo che gli utenti possano filtrare facilmente il tipo di modello per eventuali ricerche.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.

L'elemento classifications rappresenta la colonna tags visualizzata quando si esegue dotnet new e si ottiene un elenco di modelli.The classifications item represents the tags column you see when you run dotnet new and get a list of templates. Gli utenti possono anche eseguire ricerche in base ai tag di classificazione.Users can also search based on classification tags. Non confondere la proprietà tags nel file *.json con l'elenco dei tag classifications.Don't confuse the tags property in the *.json file with the classifications tags list. Si tratta di due cose diverse, sfortunatamente con nomi simili.They're two different things unfortunately named similarly. Lo schema completo per il file template.json è disponibile nell'archivio degli schemi JSON.The full schema for the template.json file is found at the JSON Schema Store. Per altre informazioni sul file template.json, vedere il wiki sulla creazione di modelli dotnet.For more information about the template.json file, see the dotnet templating wiki.

Ora che è disponibile un file .template.config/template.json valido, il modello è pronto per l'installazione.Now that you have a valid .template.config/template.json file, your template is ready to be installed. Nel terminale passare alla cartella extensions ed eseguire il comando seguente per installare il modello che si trova nella cartella corrente:In your terminal, navigate to the extensions folder and run the following command to install the template located at the current folder:

  • In Windows: dotnet new -i .\On Windows: dotnet new -i .\
  • In Linux o macOS: dotnet new -i ./On Linux or macOS: dotnet new -i ./

Questo comando restituisce l'elenco dei modelli installati, che dovrebbe includere quello creato in questa esercitazione.This command outputs the list of templates installed, which should include yours.

C:\working\templates\extensions> dotnet new -i .\
Usage: new [options]

Options:
  -h, --help          Displays help for this command.
  -l, --list          Lists templates containing the specified name. If no name is specified, lists all templates.

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

Testare il modello di elementoTest the item template

Ora che è stato installato un modello di elemento, è opportuno testarlo.Now that you have an item template installed, test it. Passare alla cartella test/ e creare una nuova applicazione console con dotnet new console.Navigate to the test/ folder and create a new console application with dotnet new console. Viene generato un progetto funzionante che è possibile testare facilmente con il comando dotnet run.This generates a working project you can easily test with the dotnet run command.

C:\test> dotnet new console
The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on C:\test\test.csproj...
  Restore completed in 54.82 ms for C:\test\test.csproj.

Restore succeeded.
C:\test> dotnet run
Hello World!

Eseguire quindi dotnet new stringext per generare il file CommonExtensions.cs dal modello.Next, run dotnet new stringext to generate the CommonExtensions.cs from the template.

C:\test> dotnet new stringext
The template "Example templates: string extensions" was created successfully.

Modificare il codice in Program.cs per invertire la stringa "Hello World" con il metodo di estensione fornito dal modello.Change the code in Program.cs to reverse the "Hello World" string with the extension method provided by the template.

Console.WriteLine("Hello World!".Reverse());

Eseguire di nuovo il programma per verificare che il risultato sia invertito.Run the program again and you'll see that the result is reversed.

C:\test> dotnet run
!dlroW olleH

La procedura è stata completata.Congratulations! È stato creato e distribuito un modello di elemento con .NET Core.You created and deployed an item template with .NET Core. Per prepararsi per la parte successiva di questa serie di esercitazioni, è necessario disinstallare il modello creato.In preparation for the next part of this tutorial series, you must uninstall the template you created. Assicurarsi di eliminare anche tutti i file dalla cartella test.Make sure to delete all files from the test folder too. Verrà ripristinato uno stato pulito, pronto per la prossima sezione principale di questa esercitazione.This will get you back to a clean state ready for the next major section of this tutorial.

Disinstallare il modelloUninstall the template

Poiché il modello è stato installato usando un percorso di file, è necessario disinstallarlo con il percorso di file assoluto.Because you installed the template by file path, you must uninstall it with the absolute file path. È possibile visualizzare un elenco dei modelli installati eseguendo il comando dotnet new -u.You can see a list of templates installed by running the dotnet new -u command. Il modello creato in questo articolo dovrebbe essere l'ultimo dell'elenco.Your template should be listed last. Usare il percorso indicato per disinstallare il modello con il comando dotnet new -u <ABSOLUTE PATH TO TEMPLATE DIRECTORY>.Use the path listed to uninstall your template with the dotnet new -u <ABSOLUTE PATH TO TEMPLATE DIRECTORY> command.

C:\working> dotnet new -u
Template Instantiation Commands for .NET Core CLI

Currently installed items:
  Microsoft.DotNet.Common.ItemTemplates
    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)

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

Passaggi successiviNext steps

In questa esercitazione è stato creato un modello di elemento.In this tutorial, you created an item template. Per scoprire come creare un modello di progetto, continuare con questa serie di esercitazioni.To learn how to create a project template, continue this tutorial series.