Modelli personalizzati per dotnet new

  • Articolo

.NET SDK viene distribuito con molti modelli già installati e pronti per l'uso. Il comando dotnet new non consente solo di usare un modello, ma anche di installarlo e disinstallarlo. È possibile creare modelli personalizzati per qualsiasi tipo di progetto, ad esempio un'app, un servizio, uno strumento o una libreria di classi. È possibile anche creare un modello che restituisce uno o più file indipendenti, ad esempio un file di configurazione.

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

Il motore del modello è open source e il repository del codice online si trova in dotnet/templating su GitHub. È possibile trovare altri modelli, anche di terze parti, usando dotnet new search. 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.

Nota

Modelli di esempio sono disponibili nel repository GitHub dotnet/templating.

Per seguire una procedura dettagliata e creare un modello, vedere l'esercitazione Creare un modello personalizzato per dotnet new.

Modelli predefiniti .NET

Quando si installa .NET SDK, si ricevono più di dieci modelli predefiniti per la creazione di progetti e file, tra cui app console, librerie di classi, progetti di unit test, app ASP.NET Core (inclusi progetti Angular e React) e file di configurazione. Per ottenere un elenco dei modelli predefiniti, eseguire il comando dotnet new list:

dotnet new list

Impostazione

Un modello è costituito dai componenti seguenti:

  • File e cartelle di origine.
  • Un file di configurazione (template.json).

File e cartelle di origine

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>. Il motore del modello è progettato per usare progetti eseguibili come codice sorgente per creare i progetti. Ciò comporta diversi vantaggi:

  • Il motore del modello non richiede di inserire speciali token nel codice sorgente del progetto.
  • I file di codice non sono file speciali o modificati in alcun modo per essere usati con il motore del modello. Gli strumenti usati in genere quando si usano progetti funzionano quindi anche con il contenuto del modello.
  • Compilare, eseguire ed effettuare il debug dei progetti di modello, proprio come per qualsiasi altro progetto.
  • È possibile creare rapidamente un modello da un progetto esistente aggiungendo semplicemente un file di configurazione ./.template.config/template.json al progetto.

I file e le cartelle archiviati nel modello non sono limitati ai tipi di progetto .NET formali. 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.

I file generati dal modello possono essere modificati in base alla logica e alle impostazioni specificate nel file di configurazione template.json. L'utente può eseguire l'override di queste impostazioni passando opzioni al comando dotnet new <TEMPLATE>. 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.

template.json

Il file template.json si trova in una cartella .template.config nella directory radice del modello. Il file fornisce informazioni di configurazione al motore del modello. Per la configurazione minima sono necessari i membri visualizzati nella tabella seguente, sufficiente per creare un modello funzionale.

Membro Tipo Descrizione
$schema URI Lo schema JSON per il file template.json. Gli editor che supportano gli schemi JSON abilitano le funzionalità di modifica JSON quando viene specificato lo schema. Ad esempio, Visual Studio Code richiede questo membro per abilitare IntelliSense. Usare un valore di http://json.schemastore.org/template.
author string L'autore del modello.
classifications array(string) Zero o più caratteristiche del modello che un utente può usare per individuare il modello durante la ricerca. Le classificazioni vengono visualizzate anche nella colonna Tags quando viene visualizzata in un elenco di modelli generati usando il comando dotnet new list.
identity string Un nome univoco per questo modello.
name string Il nome per il modello che verrà visualizzato agli utenti.
shortName string 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. 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.
sourceName string Il nome nell'albero di origine da sostituire con il nome specificato dall'utente. Il motore di modelli cercherà qualsiasi occorrenza dell'elemento sourceName indicato nel file di configurazione e la sostituirà nei nomi di file e nel contenuto dei file. Il valore sostitutivo può essere assegnato usando le opzioni -n o --name durante l'esecuzione di un modello. Se non viene specificato alcun nome, viene usata la directory corrente.
preferNameDirectory Booleano Indica se creare una directory per il modello se viene specificato il nome, ma non è impostata una directory di output (anziché creare il contenuto direttamente nella directory corrente). Il valore predefinito è false.

Lo schema completo per il file template.json è disponibile nell'archivio degli schemi JSON. Per altre informazioni sul file template.json, vedere il wiki sulla creazione di modelli dotnet. Per informazioni ed esempi più approfonditi su come rendere visibili i propri modelli in Visual Studio, vedere le risorse create da Sayed Hashimi.

Esempio

Qui è ad esempio riportata la cartella di un modello che include due file di contenuto: console.cs e readme.txt. È presente anche la cartella obbligatoria denominata .template.config che contiene il file template.json.

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

Il file template.json ha un aspetto simile al seguente:

{
  "$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. Dopo aver installato il pacchetto, è possibile usare shortName con il comando dotnet new. dotnet new adatumconsole, ad esempio, genera come output i file console.cs e readme.txt nella cartella corrente.

Localizzazione dei modelli

I modelli .NET sono localizzabili. Se un modello viene localizzato per la lingua corrispondente alle impostazioni locali correnti, i suoi elementi vengono visualizzati nella stessa lingua dell'interfaccia della riga di comando. La localizzazione è facoltativa quando si creano nuovi modelli.

Gli elementi localizzabili di un modello sono:

  • Nome
  • Autore
  • Descrizione
  • Simboli
    • Descrizione
    • Nome visualizzato
    • Descrizioni e nome visualizzato delle opzioni per i parametri di scelta
  • Azioni Post
    • Descrizione
    • Istruzioni manuali

I file di localizzazione sono in formato JSON e deve esistere un solo file per impostazioni cultura. La convenzione di denominazione è templatestrings.<lang code>.json, dove lang code corrisponde a una delle opzioni CultureInfo. Tutti i file di localizzazione devono trovarsi all'interno della cartella .template-config\localize.

Il codice JSON di localizzazione è costituito da coppie chiave-valore:

  • La chiave è il riferimento a un elemento di template.json da localizzare. Se si tratta di un elemento figlio, usare il percorso completo con un delimitatore /.
  • Il valore è la stringa di localizzazione dell'elemento specificato dalla chiave.

Per altre informazioni sulla localizzazione dei modelli, vedere la pagina sulla localizzazione del wiki sui modelli dotnet.

Esempio

Ad esempio, ecco un file template.json con alcuni campi localizzabili:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": "Config",
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

Alcuni campi devono essere localizzati in portoghese brasiliano. Il nome del file sarà templatestrings.pt-BR.json, per corrispondere alle impostazioni cultura, e l'aspetto sarà simile al seguente:

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

Comprimere un modello in un pacchetto NuGet (file nupkg)

Un modello personalizzato viene compresso in un pacchetto con il comando dotnet pack e un file con estensione csproj. In alternativa, è possibile usare NuGet con il comando nuget pack e un file con estensione nuspec. Per l'uso di NuGet, tuttavia, è necessario .NET Framework su Windows e Mono su Linux e macOS.

Il file con estensione csproj è leggermente diverso da un file csproj di un progetto di codice tradizionale. Si notino le impostazioni seguenti:

  1. È inclusa l'impostazione <PackageType> con il valore Template.
  2. È inclusa l'impostazione <PackageVersion> con un numero di versione NuGet valido.
  3. È inclusa l'impostazione <PackageId> con un identificatore univoco. Questo identificatore è utile per disinstallare il pacchetto di modelli e viene usato dai feed NuGet per registrare tale pacchetto.
  4. Le impostazioni dei metadati generici devono essere definite: <Title>, <Authors>, <Description> e <PackageTags>.
  5. L'impostazione <TargetFramework> deve essere definita, anche se non viene usato il file binario generato dal processo del modello. Nell'esempio seguente è definito il valore netstandard2.0.

Per un pacchetto di modelli in formato NuGet con estensione nupkg è necessario che tutti i modelli siano archiviati nella cartella content all'interno del pacchetto. 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:

  1. L'impostazione <IncludeContentInPack> ha valore true in modo da includere qualsiasi file definito come content del progetto nel pacchetto NuGet.
  2. L'impostazione <IncludeBuildOutput> ha valore false in modo da escludere tutti i file binari generati dal compilatore in base al pacchetto NuGet.
  3. L'impostazione <ContentTargetFolders> ha valore content. Ciò consente di assicurarsi che i file impostati come content vengano archiviati nella cartella content del pacchetto NuGet. Questa cartella del pacchetto NuGet viene analizzata dal sistema di modelli dotnet.

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

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. In questo modo, è possibile usare un singolo elemento di progetto per includere tutti i file e le cartelle in templates come content. All'interno di un elemento <ItemGroup> creare un elemento <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.

Di seguito è riportato un esempio di file con estensione csproj che rispetta tutte queste linee guida. Comprime la sottocartella templates nella cartella content del pacchetto ed esclude qualsiasi file di codice compilato.

<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. Il file MyDotnetTemplates.csproj e la cartella templates si trovano entrambi nella radice di una directory denominata project_folder. La cartella templates contiene due modelli, mytemplate1 e mytemplate2. Ogni modello ha file di contenuto e una cartella .template.config con un file di configurazione template.json.

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

Nota

Per assicurarsi che il pacchetto di modelli compaia nei risultati di dotnet new search, impostare il tipo di pacchetto NuGet su Template.

Installare un pacchetto di modelli

Usare il comando dotnet new install per installare un pacchetto di modelli.

Per installare un pacchetto di modelli da un pacchetto NuGet archiviato in nuget.org

Usare l'identificatore del pacchetto NuGet per installare un pacchetto di modelli.

dotnet new install <NUGET_PACKAGE_ID>

Per installare un pacchetto di modelli da un'origine NuGet personalizzata

Specificare un'origine NuGet personalizzata, ad esempio https://api.my-custom-nuget.com/v3/index.json.

dotnet new --install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

Per installare un pacchetto di modelli da un file nupkg locale

Specificare il percorso di un file di pacchetto NuGet con estensione nupkg.

dotnet new install <PATH_TO_NUPKG_FILE>

Per installare un pacchetto di modelli da una directory del file system

I modelli possono essere installati da una cartella di modello, come la cartella mytemplate1 nell'esempio precedente. Specificare il percorso della cartella .template.config. Non occorre che il percorso della directory del modello sia assoluto.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Ottenere un elenco dei pacchetti di modelli installati

Il comando uninstall, senza altri parametri, elenca tutti i modelli di pacchetti installati e i modelli che contengono.

dotnet new uninstall

Il comando restituisce un output simile al seguente:

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

Il primo livello degli elementi dopo Currently installed items: è costituito dagli identificatori usati nella disinstallazione di un modello di pacchetti. Nell'esempio precedente è elencato Microsoft.Azure.WebJobs.ProjectTemplates. Se il modello di pacchetti è stato installato usando un percorso del file system, questo identificatore corrisponde al percorso della cartella .template.config. Nell'elenco vengono visualizzati solo i pacchetti di modelli installati tramite dotnet new install. I pacchetti di modelli integrati in .NET SDK non vengono visualizzati.

Disinstallare un pacchetto di modelli

Usare il comando dotnet new uninstall per disinstallare un pacchetto di modelli.

Se il pacchetto è stato installato tramite un feed NuGet o direttamente da un file con estensione nupkg, specificare l'identificatore.

dotnet new uninstall <NUGET_PACKAGE_ID>

Se il pacchetto è stato installato specificando un percorso per la cartella .template.config, usare tale percorso per disinstallare il pacchetto. È possibile visualizzare il percorso assoluto del pacchetto di modelli nell'output generato dal comando dotnet new uninstall. Per altre informazioni, vedere la sezione Ottenere un elenco dei modelli installati.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Creare un progetto usando un modello personalizzato

Dopo l'installazione di un modello, usarlo eseguendo il comando dotnet new <TEMPLATE> come si farebbe con qualsiasi altro modello preinstallato. È possibile anche specificare options per il comando dotnet new, includendo le opzioni specifiche del modello configurate nelle impostazioni del modello. Specificare il nome breve del modello direttamente nel comando:

dotnet new <TEMPLATE>

Vedi anche