Condividi tramite

Modelli personalizzati per dotnet new

.NET SDK include molti modelli già installati e pronti per l'uso. Il dotnet new comando non è solo il modo per usare un modello, ma anche come installare e disinstallare i modelli. È possibile creare modelli personalizzati per qualsiasi tipo di progetto, ad esempio un'app, un servizio, uno strumento o una libreria di classi. È anche possibile 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 riferimento direttamente a un file NuGet con estensione nupkg o specificando una directory del file system che contiene il modello. Il motore di modelli offre funzionalità che consentono di sostituire i valori, includere ed escludere file ed eseguire operazioni di elaborazione personalizzate quando viene usato il modello.

Il motore di modelli è open source e il repository di codice online si trova in dotnet/templating su GitHub. Altri modelli, inclusi i modelli di terze parti, sono disponibili usando dotnet new search. Per altre informazioni sulla creazione e l'uso di modelli personalizzati, vedere Come creare modelli personalizzati per dotnet new e il wiki del repository GitHub dotnet/templating.

Annotazioni

Gli esempi di modelli 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 una dozzina di 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 Angular e progetti React) e file di configurazione. Per ottenere un elenco dei modelli predefiniti, eseguire il comando dotnet new list:

dotnet new list

Configurazione

Un modello è costituito dalle parti 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 il motore di modelli deve usare quando viene eseguito il dotnet new <TEMPLATE> comando. Il motore di modelli è progettato per usare progetti eseguibili come codice sorgente per produrre progetti. Ciò comporta diversi vantaggi:

  • Il motore di modelli non richiede l'inserimento di token speciali nel codice sorgente del progetto.
  • I file di codice non sono file speciali o modificati in alcun modo per lavorare con il motore di modelli. Pertanto, gli strumenti usati normalmente quando si usano progetti funzionano anche con il contenuto del modello.
  • Puoi costruire, eseguire e fare il debug dei progetti modello proprio come fai con qualsiasi altro tuo progetto.
  • È possibile creare rapidamente un modello da un progetto esistente aggiungendo 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 desidera creare quando viene usato il modello, anche se il motore di modelli produce un solo file come output.

I file generati dal modello possono essere modificati in base alla logica e alle impostazioni fornite nel file di configurazione template.json . L'utente può eseguire l'override di queste impostazioni passando le opzioni al dotnet new <TEMPLATE> comando. Un esempio comune di logica personalizzata è fornire un nome per una classe o una variabile nel file di codice distribuito da un modello.

template.json

Il filetemplate.json viene inserito in una cartella .template.config nella directory radice del modello. Il file fornisce informazioni di configurazione al motore di template. La configurazione minima richiede i membri illustrati nella tabella seguente, che è sufficiente per creare un modello funzionale.

Membro TIPO Descrizione
$schema URI (Identificatore Uniforme delle Risorse) 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 che questo membro abiliti IntelliSense. Usare un valore di http://json.schemastore.org/template.
author corda Autore del modello.
classifications array(string) Zero o più caratteristiche del modello che un utente potrebbe usare per trovare il modello durante la ricerca. Le classificazioni vengono visualizzate anche nella colonna Tag quando viene visualizzata in un elenco di modelli prodotti usando il dotnet new list comando .
identity corda Nome univoco per questo modello.
name corda Il nome del modello che gli utenti dovrebbero vedere.
shortName corda Nome abbreviato predefinito per la selezione del modello applicabile agli ambienti in cui il nome del modello viene specificato dall'utente, non selezionato tramite un'interfaccia utente grafica. Ad esempio, il nome breve è utile quando si usano modelli da un prompt dei comandi con i comandi CLI.
sourceName corda Nome nell'albero di origine da sostituire con il nome specificato dall'utente. Il motore di template cercherà qualsiasi occorrenza dell'elemento sourceName indicato nel file di configurazione e lo sostituirà nei nomi e nei contenuti dei file. Il valore con cui deve essere sostituito può essere assegnato usando le opzioni -n o --name durante l'esecuzione di un modello. Se non viene specificato alcun nome, viene utilizzata 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 schemi JSON. Per altre informazioni sul file template.json , vedere il wiki dotnet templating. Per esempi e informazioni più approfondite su come rendere visibili i modelli in Visual Studio, vedere le risorse create da Sayed Hashimi.

Esempio

Ad esempio, ecco una cartella modello che contiene due file di contenuto: console.cs e readme.txt. È presente anche la cartella richiesta denominata .template.config che contiene il file template.json .

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

Il filetemplate.json è 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 modello installabile. Dopo aver installato il pacchetto, è possibile usare il shortName comando dotnet new. Ad esempio, dotnet new adatumconsole restituisce i console.cs file 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 relativi elementi vengono visualizzati nella stessa lingua dell'interfaccia della riga di comando. La localizzazione è facoltativa durante la creazione di nuovi modelli.

Gli elementi localizzabili in un modello sono:

  • Nome
  • Autore
  • Descrizione
  • Simboli
    • Descrizione
    • Nome visualizzato
    • Descrizioni e Nome visualizzato delle scelte per i parametri di scelta
  • Azioni del post
    • Descrizione
    • Istruzioni manuali

I file di localizzazione hanno un formato JSON e deve esistere un solo file per 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 .template-config\localize cartella .

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

  • La chiave è il riferimento a un elemento di template.json da localizzare. Se l'elemento è 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 di localizzazione del wiki dotnet templating.

Esempio

Ad esempio, ecco template.json file 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."
    }
  }
}

E alcuni campi devono essere localizzati in portoghese brasiliano. Il nome del file corrisponderà templatestrings.pt-BR.json alla cultura e 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 è impacchettato con il comando dotnet pack e un file .csproj. In alternativa, NuGet può essere usato con il comando nuget pack insieme a un file con estensione nuspec . Tuttavia, NuGet richiede .NET Framework in Windows e Mono in Linux e macOS.

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

  1. L'impostazione <PackageType> viene aggiunta e impostata su Template.
  2. L'impostazione <PackageVersion> viene aggiunta e impostata su un numero di versione NuGet valido.
  3. L'impostazione <PackageId> viene aggiunta e impostata su un identificatore univoco. Questo identificatore viene usato per disinstallare il pacchetto di modelli e viene usato dai feed NuGet per registrare il pacchetto di modelli.
  4. Le impostazioni dei metadati generici devono essere impostate: <Title>, <Authors><Description>, e <PackageTags>.
  5. L'impostazione <TargetFramework> deve essere impostata, anche se il file binario prodotto dal processo del modello non viene usato. Nell'esempio seguente è impostato su netstandard2.0.

Un pacchetto modello, sotto forma di pacchetto NuGet con estensione nupkg , richiede che tutti i modelli vengano archiviati nella cartella del contenuto all'interno del pacchetto. Esistono altre impostazioni da aggiungere a un file con estensione csproj per assicurarsi che il file con estensione nupkg generato possa essere installato come pacchetto di modelli:

  1. L'impostazione <IncludeContentInPack> è impostata su true per includere qualsiasi file impostato dal progetto come contenuto nel pacchetto NuGet.
  2. L'impostazione <IncludeBuildOutput> è impostata su false per escludere tutti i file binari generati dal compilatore dal pacchetto NuGet.
  3. L'impostazione <ContentTargetFolders> è impostata su content. In questo modo, i file impostati come contenuto vengono archiviati nella cartella del contenuto nel pacchetto NuGet. Questa cartella nel pacchetto NuGet viene analizzata dal sistema di modelli dotnet.

Un modo semplice per escludere tutti i file di codice dalla compilazione dal progetto modello consiste nell'usare l'elemento <Compile Remove="**\*" /> nel file di progetto, all'interno di un <ItemGroup> elemento .

Un modo semplice per strutturare il pacchetto di modelli consiste nell'inserire tutti i modelli in singole cartelle e quindi in ogni cartella 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 nei modelli come contenuto. All'interno di un <ItemGroup> elemento creare un <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> elemento.

Ecco un file con estensione csproj di esempio che segue tutte queste linee guida. Comprime la cartella figlio dei modelli nella cartella del pacchetto di contenuto ed esclude la compilazione di qualsiasi file di codice.

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

Nell'esempio seguente viene illustrata la struttura di file e cartelle di usando un file con estensione csproj per creare un pacchetto modello. 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 include 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

Annotazioni

Per assicurarsi che il pacchetto modello venga visualizzato nel dotnet new search risultato, impostare il tipo di pacchetto NuGet su Template.

Installare un pacchetto modello

Usare il comando dotnet new install per installare un pacchetto modello.

Avvertimento

I modelli possono eseguire codice MSBuild quando viene attivato, non installare o eseguire modelli .NET non attendibili.

Per installare un pacchetto modello da un pacchetto NuGet archiviato in nuget.org

Usare l'identificatore del pacchetto NuGet per installare un pacchetto modello.

dotnet new install <NUGET_PACKAGE_ID>

Per installare un pacchetto modello 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 modello 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 modello, ad esempio la cartella mytemplate1 dell'esempio precedente. Specificare il percorso della cartella .template.config . Il percorso della directory dei modelli non deve essere assoluto.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Ottenere un elenco di pacchetti modello installati

Il comando uninstall, senza altri parametri, elenca tutti i pacchetti modello installati e i modelli inclusi.

dotnet new uninstall

Questo comando restituisce un risultato simile all'output 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 di elementi dopo Currently installed items: sono gli identificatori usati per disinstallare un pacchetto modello. Nell'esempio precedente, Microsoft.Azure.WebJobs.ProjectTemplates è elencato. Se il pacchetto modello è stato installato usando un percorso del file system, questo identificatore è il percorso della cartella .template.config . Nell'elenco vengono visualizzati solo i pacchetti modello installati tramite dotnet new install . I pacchetti modello incorporati in .NET SDK non vengono visualizzati.

Disinstallare un pacchetto modello

Usare il comando dotnet new uninstall per disinstallare un pacchetto modello.

Se il pacchetto è stato installato da 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 della cartella .template.config , usare tale percorso per disinstallare il pacchetto. È possibile visualizzare il percorso assoluto del pacchetto modello nell'output fornito dal dotnet new uninstall comando . Per altre informazioni, vedere la sezione Ottenere un elenco di modelli installati .

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Creare un progetto usando un modello personalizzato

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

dotnet new <TEMPLATE>

Vedere anche

  • Last updated on