Modelli personalizzati per dotnet newCustom templates for dotnet new

.NET Core SDK viene distribuito con molti modelli già installati e pronti per l'uso.The .NET Core SDK comes with many templates already installed and ready for you to use. Il comando dotnet new non consente solo di usare un modello, ma anche di installarlo e disinstallarlo.The dotnet new command isn't only the way to use a template, but also how to install and uninstall templates. A partire da .NET Core 2.0, è possibile creare modelli personalizzati per qualsiasi tipo di progetto, ad esempio un'app, un servizio, uno strumento o una libreria di classi.Starting with .NET Core 2.0, you can create your own custom templates for any type of project, such as an app, service, tool, or class library. È possibile anche creare un modello che restituisce uno o più file indipendenti, ad esempio un file di configurazione.You can even create a template that outputs one or more independent files, such as a configuration file.

È possibile installare modelli personalizzati da un pacchetto NuGet in qualsiasi feed NuGet, facendo direttamente riferimento a un file NuGet con estensione nupkg o specificando una directory del file system che contiene il modello.You can install custom templates from a NuGet package on any NuGet feed, by referencing a NuGet .nupkg file directly, or by specifying a file system directory that contains the template. Il motore del modello offre funzionalità che consentono di sostituire i valori, includere ed escludere file ed eseguire operazioni di elaborazione personalizzate quando si usa il modello.The template engine offers features that allow you to replace values, include and exclude files, and execute custom processing operations when your template is used.

Il motore del modello è open source e il repository del codice online si trova in dotnet/templating su GitHub.The template engine is open source, and the online code repository is at dotnet/templating on GitHub. Visitare il repository dotnet/dotnet-template-samples per gli esempi di modelli.Visit the dotnet/dotnet-template-samples repo for samples of templates. Più modelli, inclusi i modelli di terze parti, sono disponibili in Available templates for dotnet new (Modelli disponibili per dotnet new) su GitHub.More templates, including templates from third parties, are found at Available templates for dotnet new on GitHub. Per altre informazioni sulla creazione e l'uso di modelli personalizzati, vedere Come creare modelli personalizzati per dotnet new e la wiki del repository GitHub dotnet/templating.For more information about creating and using custom templates, see How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki.

Per seguire una procedura dettagliata e creare un modello, vedere l'esercitazione Creare un modello personalizzato per dotnet new.To follow a walkthrough and create a template, see the Create a custom template for dotnet new tutorial.

Modelli predefiniti .NET.NET default templates

Quando si installa .NET Core SDK, si riceve circa una decina di modelli predefiniti per la creazione di progetti e file, tra cui app console, librerie di classi, progetti unit test, app ASP.NET Core (inclusi i progetti Angular e React) e file di configurazione.When you install the .NET Core SDK, you receive over a dozen built-in templates for creating projects and files, including console apps, class libraries, unit test projects, ASP.NET Core apps (including Angular and React projects), and configuration files. Per elencare i modelli predefiniti, eseguire il comando dotnet new con l'opzione -l|--list:To list the built-in templates, run the dotnet new command with the -l|--list option:

dotnet new --list

ConfigurazioneConfiguration

Un modello è costituito dai componenti seguenti:A template is composed of the following parts:

  • File e cartelle di origine.Source files and folders.
  • Un file di configurazione (template.json).A configuration file (template.json).

File e cartelle di origineSource files and folders

I file e le cartelle di origine includono tutti i file e le cartelle che devono essere usati dal motore del modello quando viene eseguito il comando dotnet new <TEMPLATE>.The source files and folders include whatever files and folders you want the template engine to use when the dotnet new <TEMPLATE> command is run. Il motore del modello è progettato per usare progetti eseguibili come codice sorgente per creare i progetti.The template engine is designed to use runnable projects as source code to produce projects. Ciò comporta diversi vantaggi:This has several benefits:

  • Il motore del modello non richiede di inserire speciali token nel codice sorgente del progetto.The template engine doesn't require you to inject special tokens into your project's source code.
  • I file di codice non sono file speciali o modificati in alcun modo per essere usati con il motore del modello.The code files aren't special files or modified in any way to work with the template engine. Gli strumenti usati in genere quando si usano progetti funzionano quindi anche con il contenuto del modello.So, the tools you normally use when working with projects also work with template content.
  • Compilare, eseguire ed effettuare il debug dei progetti di modello, proprio come per qualsiasi altro progetto.You build, run, and debug your template projects just like you do for any of your other projects.
  • È possibile creare rapidamente un modello da un progetto esistente aggiungendo semplicemente un file di configurazione ./.template.config/template.json al progetto.You can quickly create a template from an existing project just by adding a ./.template.config/template.json configuration file to the project.

I file e le cartelle archiviati nel modello non sono limitati ai tipi di progetto .NET formali.Files and folders stored in the template aren't limited to formal .NET project types. I file e le cartelle di origine possono essere costituiti da qualsiasi contenuto che si vuole creare quando viene usato il modello, anche se il motore del modello genera un solo file di output.Source files and folders may consist of any content that you wish to create when the template is used, even if the template engine produces just one file as its output.

I file generati dal modello possono essere modificati in base alla logica e alle impostazioni specificate nel file di configurazione template.json.Files generated by the template can be modified based on logic and settings you've provided in the template.json configuration file. L'utente può eseguire l'override di queste impostazioni passando opzioni al comando dotnet new <TEMPLATE>.The user can override these settings by passing options to the dotnet new <TEMPLATE> command. Un esempio comune di logica personalizzata consiste nel fornire un nome per una classe o una variabile nel file di codice che viene distribuito da un modello.A common example of custom logic is providing a name for a class or variable in the code file that's deployed by a template.

template.jsontemplate.json

Il file template.json si trova in una cartella .template.config nella directory radice del modello.The template.json file is placed in a .template.config folder in the root directory of the template. Il file fornisce informazioni di configurazione al motore del modello.The file provides configuration information to the template engine. Per la configurazione minima sono necessari i membri visualizzati nella tabella seguente, sufficiente per creare un modello funzionale.The minimum configuration requires the members shown in the following table, which is sufficient to create a functional template.

MemberMember TipoType DESCRIZIONEDescription
$schema URIURI Lo schema JSON per il file template.json.The JSON schema for the template.json file. Gli editor che supportano gli schemi JSON abilitano le funzionalità di modifica JSON quando viene specificato lo schema.Editors that support JSON schemas enable JSON-editing features when the schema is specified. Ad esempio, Visual Studio Code richiede questo membro per abilitare IntelliSense.For example, Visual Studio Code requires this member to enable IntelliSense. Usare un valore di http://json.schemastore.org/template.Use a value of http://json.schemastore.org/template.
author stringstring L'autore del modello.The author of the template.
classifications array(string)array(string) Zero o più caratteristiche del modello che un utente può usare per individuare il modello durante la ricerca.Zero or more characteristics of the template that a user might use to find the template when searching for it. Le classificazioni vengono visualizzate anche nella colonna Tags quando viene visualizzata in un elenco di modelli generati usando il comando dotnet new -l|--list.The classifications also appear in the Tags column when it appears in a list of templates produced by using the dotnet new -l|--list command.
identity stringstring Un nome univoco per questo modello.A unique name for this template.
name stringstring Il nome per il modello che verrà visualizzato agli utenti.The name for the template that users should see.
shortName stringstring Un nome breve predefinito per la selezione del modello che si applica agli ambienti in cui il nome del modello viene specificato dall'utente e non selezionato tramite un'interfaccia utente grafica.A default shorthand name for selecting the template that applies to environments where the template name is specified by the user, not selected via a GUI. Ad esempio, il nome breve è utile quando si usano i modelli da un prompt dei comandi con i comandi dell'interfaccia della riga di comando.For example, the short name is useful when using templates from a command prompt with CLI commands.

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.

EsempioExample

Qui è ad esempio riportata la cartella di un modello che contiene due file di contenuto: console.cs e readme.txt.For example, here is a template folder that contains two content files: console.cs and readme.txt. Si noti che è presente la cartella obbligatoria denominata .template.config che contiene il file template.json.Take notice that there is the required folder named .template.config that contains the template.json file.

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

Il file template.json ha un aspetto simile al seguente:The template.json file looks like the following:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

La cartella mytemplate è un pacchetto di modelli installabile.The mytemplate folder is an installable template pack. Dopo aver installato il pacchetto, è possibile usare shortName con il comando dotnet new.Once the pack is installed, the shortName can be used with the dotnet new command. dotnet new adatumconsole, ad esempio, genera come output i file console.cs e readme.txt nella cartella corrente.For example, dotnet new adatumconsole would output the console.cs and readme.txt files to the current folder.

Compressione di un modello in un pacchetto NuGet (file nupkg)Packing a template into a NuGet package (nupkg file)

Un modello personalizzato viene compresso in un pacchetto con il comando dotnet pack e un file con estensione csproj.A custom template is packed with the dotnet pack command and a .csproj file. In alternativa, è possibile usare NuGet con il comando nuget pack e un file con estensione nuspec.Alternatively, NuGet can be used with the nuget pack command along with a .nuspec file. Per l'uso di NuGet, tuttavia, è necessario .NET Framework su Windows e Mono su Linux e MacOS.However, NuGet requires the .NET Framework on Windows and Mono on Linux and MacOS.

Il file con estensione csproj è leggermente diverso da un file csproj di un progetto di codice tradizionale.The .csproj file is slightly different from a traditional code-project .csproj file. Osservare le seguenti impostazioni:Note the following settings:

  1. È inclusa l'impostazione <PackageType> con il valore Template.The <PackageType> setting is added and set to Template.
  2. È inclusa l'impostazione <PackageVersion> con un numero di versione NuGet valido.The <PackageVersion> setting is added and set to a valid NuGet version number.
  3. È inclusa l'impostazione <PackageId> con un identificatore univoco.The <PackageId> setting is added and set to a unique identifier. Questo identificatore è utile per disinstallare il pacchetto di modelli e viene usato dai feed NuGet per registrare tale pacchetto.This identifier is used to uninstall the template pack and is used by NuGet feeds to register your template pack.
  4. Le impostazioni dei metadati generici devono essere definite: <Title>, <Authors>, <Description> e <PackageTags>.Generic metadata settings should be set: <Title>, <Authors>, <Description>, and <PackageTags>.
  5. L'impostazione <TargetFramework> deve essere definita, anche se non viene usato il file binario generato dal processo del modello.The <TargetFramework> setting must be set, even though the binary produced by the template process isn't used. Nell'esempio seguente è definito il valore netstandard2.0.In the example below it's set to netstandard2.0.

Per un pacchetto di modelli, nel formato NuGet con estensione nupkg, è necessario che tutti i modelli siano archiviati nella cartella content all'interno del pacchetto.A template pack, in the form of a .nupkg NuGet package, requires that all templates be stored in the content folder within the package. Vi sono altre impostazioni da aggiungere a un file con estensione csproj per assicurarsi che il file nupkg generato possa essere installato come pacchetto di modelli:There are a few more settings to add to a .csproj file to ensure that the generated .nupkg can be installed as a template pack:

  1. L'impostazione <IncludeContentInPack> ha valore true in modo da includere qualsiasi file definito come content del progetto nel pacchetto NuGet.The <IncludeContentInPack> setting is set to true to include any file the project sets as content in the NuGet package.
  2. L'impostazione <IncludeBuildOutput> ha valore false in modo da escludere tutti i file binari generati dal compilatore in base al pacchetto NuGet.The <IncludeBuildOutput> setting is set to false to exclude all binaries generated by the compiler from the NuGet package.
  3. L'impostazione <ContentTargetFolders> ha valore content.The <ContentTargetFolders> setting is set to content. Ciò consente di assicurarsi che i file impostati come content vengano archiviati nella cartella content del pacchetto NuGet.This makes sure that the files set as content are stored in the content folder in the NuGet package. Questa cartella del pacchetto NuGet viene analizzata dal sistema di modelli dotnet.This folder in the NuGet package is parsed by the dotnet template system.

Un modo semplice per escludere tutti i file del codice dalla compilazione in base al progetto di modello è quello di usare l'elemento <Compile Remove="**\*" /> nel file di progetto, all'interno di un elemento <ItemGroup>.An easy way to exclude all code files from being compiled by your template project is by using the <Compile Remove="**\*" /> item in your project file, inside an <ItemGroup> element.

Un modo semplice per definire la struttura del pacchetto di modelli è quello di inserire tutti i modelli in singole cartelle e quindi ogni cartella di modello all'interno di una cartella templates che si trova nella stessa directory del file con estensione csproj.An easy way to structure your template pack is to put all templates in individual folders, and then each template folder inside of a templates folder that is located in the same directory as your .csproj file. In questo modo, è possibile usare un singolo elemento di progetto per includere tutti i file e le cartelle in templates come content.This way, you can use a single project item to include all files and folders in the templates as content. All'interno di un elemento <ItemGroup> creare un elemento <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.Inside of an <ItemGroup> element, create a <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> item.

Di seguito è riportato un esempio di file con estensione csproj in cui sono rispettate tutte le linee guida indicate sopra.Here is an example .csproj file that follows all of the guidelines above. Comprime la sottocartella templates nella cartella content del pacchetto ed esclude qualsiasi file di codice compilato.It packs the templates child folder to the content package folder and excludes any code file from being compiled.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <Title>AdatumCorporation Templates</Title>
    <Authors>Me</Authors>
    <Description>Templates to use when creating an application for Adatum Corporation.</Description>
    <PackageTags>dotnet-new;templates;contoso</PackageTags>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

L'esempio seguente illustra la struttura di file e cartelle necessaria per usare un file con estensione csproj per creare un pacchetto di modelli.The example below demonstrates the file and folder structure of using a .csproj to create a template pack. Il file MyDotnetTemplates.csproj e la cartella templates si trovano entrambi nella radice di una directory denominata project_folder.The MyDotnetTemplates.csproj file and templates folder are both located at the root of a directory named project_folder. La cartella templates contiene due modelli, mytemplate1 e mytemplate2.The templates folder contains two templates, mytemplate1 and mytemplate2. Ogni modello ha file di contenuto e una cartella .template.config con un file di configurazione template.json.Each template has content files and a .template.config folder with a template.json config file.

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

Installazione di un modelloInstalling a template

Per installare un pacchetto, usare il comando dotnet new -i|--install.Use the dotnet new -i|--install command to install a package.

Per installare un modello da un pacchetto NuGet archiviato in nuget.orgTo install a template from a NuGet package stored at nuget.org

Usare l'identificatore del pacchetto NuGet per installare un pacchetto di modelli.Use the NuGet package identifier to install a template package.

dotnet new -i <NUGET_PACKAGE_ID>

Per installare un modello da un file nupkg localeTo install a template from a local nupkg file

Specificare il percorso di un file di pacchetto NuGet con estensione nupkg.Provide the path to a .nupkg NuGet package file.

dotnet new -i <PATH_TO_NUPKG_FILE>

Per installare un modello da una directory del file systemTo install a template from a file system directory

I modelli possono essere installati da una cartella di modello, come mytemplate1 nell'esempio precedente.Templates can be installed from a template folder, such as the mytemplate1 folder from the example above. Specificare il percorso della cartella .template.config.Specify the folder path of the .template.config folder. Il percorso della directory del modello non deve essere assoluto.The path to the template directory does not need to be absolute. Un percorso assoluto è tuttavia necessario per disinstallare un modello installato da una cartella.However, an absolute path is required to uninstall a template that is installed from a folder.

dotnet new -i <FILE_SYSTEM_DIRECTORY>

Ottenere un elenco dei modelli installatiGet a list of installed templates

Il comando uninstall, senza altri parametri, elenca tutti i modelli installati.The uninstall command, without any other parameters, will list all installed templates.

dotnet new -u

Il comando restituisce un output simile al seguente:That command returns something similar to the following output:

Template Instantiation Commands for .NET Core CLI

Currently installed items:
  Microsoft.DotNet.Common.ItemTemplates
    Templates:
      global.json file (globaljson)
      NuGet Config (nugetconfig)
      Solution File (sln)
      Dotnet local tool manifest file (tool-manifest)
      Web Config (webconfig)
  Microsoft.DotNet.Common.ProjectTemplates.3.0
    Templates:
      Class library (classlib) C#
      Class library (classlib) F#
      Class library (classlib) VB
      Console Application (console) C#
      Console Application (console) F#
      Console Application (console) VB
...

Il primo livello degli elementi dopo Currently installed items: è costituito dagli identificatori usati nella disinstallazione di un modello.The first level of items after Currently installed items: are the identifiers used in uninstalling a template. Nell'esempio precedente sono elencati Microsoft.DotNet.Common.ItemTemplates e Microsoft.DotNet.Common.ProjectTemplates.3.0.And in the example above, Microsoft.DotNet.Common.ItemTemplates and Microsoft.DotNet.Common.ProjectTemplates.3.0 are listed. Se il modello è stato installato usando un percorso del file system, questo identificatore corrisponde al percorso della cartella .template.config.If the template was installed by using a file system path, this identifier will the folder path of the .template.config folder.

Disinstallazione di un modelloUninstalling a template

Per disinstallare un pacchetto, usare il comando dotnet new -u|--uninstall.Use the dotnet new -u|--uninstall command to uninstall a package.

Se il pacchetto è stato installato tramite un feed NuGet o direttamente da un file con estensione nupkg, specificare l'identificatore.If the package was installed by either a NuGet feed or by a .nupkg file directly, provide the identifier.

dotnet new -u <NUGET_PACKAGE_ID>

Se il pacchetto è stato installato specificando un percorso per la cartella .template.config, usare tale percorso assoluto per disinstallare il pacchetto.If the package was installed by specifying a path to the .template.config folder, use that absolute path to uninstall the package. È possibile visualizzare il percorso assoluto del modello nell'output generato dal comando dotnet new -u.You can see the absolute path of the template in the output provided by the dotnet new -u command. Per altre informazioni, vedere la sezione precedente Ottenere un elenco dei modelli installati.For more information, see the Get a list of installed templates section above.

dotnet new -u <ABSOLUTE_FILE_SYSTEM_DIRECTORY>

Creare un progetto usando un modello personalizzatoCreate a project using a custom template

Dopo l'installazione di un modello, usare il modello eseguendo il comando dotnet new <TEMPLATE> come si farebbe con qualsiasi altro modello pre-installato.After a template is installed, use the template by executing the dotnet new <TEMPLATE> command as you would with any other pre-installed template. È possibile anche specificare options per il comando dotnet new, includendo le opzioni specifiche del modello configurate nelle impostazioni del modello.You can also specify options to the dotnet new command, including template-specific options you configured in the template settings. Specificare il nome breve del modello direttamente nel comando:Supply the template's short name directly to the command:

dotnet new <TEMPLATE>

Vedere ancheSee also