Esercitazione: Creare un modello di elemento

  • Articolo

Con .NET è possibile creare e distribuire modelli che generano progetti, file e risorse. Questa esercitazione è la prima parte di una serie che illustra come creare, installare e disinstallare i modelli da usare con il comando dotnet new.

È possibile visualizzare il modello completato nel repository GitHub .NET Samples.

Suggerimento

I modelli di elemento non vengono visualizzati nella finestra di dialogo Aggiungi>nuovo elemento di Visual Studio.

In questa parte della serie si apprenderà come:

  • Creare una classe per un modello di elemento.
  • Creare la cartella e il file di configurazione del modello.
  • Installare un modello da un percorso di file.
  • Testare un modello di elemento.
  • Disinstallare un modello di elemento.

Prerequisiti

  • .NET SDK 7.0.100 o una versione successiva.

    L'articolo di riferimento presenta i concetti di base sui modelli e il modo in cui vengono creati. Alcune di queste informazioni sono ripetute qui.

  • Aprire un terminale e passare in una cartella in cui archiviare e testarei modelli.

Importante

Questo articolo è stato scritto per .NET 7. Tuttavia, si applica anche a .NET 6 e alle versioni precedenti, con una differenza: la sintassi dotnet new è diversa. I sottocomandi list, search, installe uninstall devono essere rispettivamente le opzioni --list, --search, --installe --uninstall.

Ad esempio, il comando dotnet new install in .NET 7 diventa dotnet new --install in .NET 6. Usare il comando dotnet new --help per visualizzare un elenco di tutte le opzioni e i sottocomandi.

Creare le cartelle necessarie

Questa serie usa una "cartella di lavoro" in cui è contenuta l'origine del modello e una "cartella di test" usata per testare i modelli. La cartella di lavoro e la cartella di test devono trovarsi nella stessa cartella padre.

Per prima cosa, creare la cartella padre; il nome non ha importanza. Creare quindi due sottocartelle denominate working e test. All'interno della cartella working creare una sottocartella denominata content.

La struttura della cartella dovrebbe essere la seguente.

parent_folder
├───test
└───working
    └───content

Creare un modello di elemento

Un modello di elemento è un tipo specifico di modello che contiene uno o più file. Questi tipi di modelli sono utili quando si ha già un progetto e si vuole generare un altro file, come un file di configurazione o di codice. In questo esempio verrà creata una classe che aggiunge un metodo di estensione al tipo stringa.

Nel terminale passare alla cartella working\content e creare una nuova sottocartella denominata extensions.

working
└───content
    └───extensions

Passare alla cartella extensions e creare un nuovo file denominato StringExtensions.cs. Apri il file in un editor di testo. Questa classe fornirà un metodo di estensione denominato Reverse che inverte il contenuto di una stringa. Incollare il codice seguente e salvare il file:

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Al termine del contenuto del modello, il passaggio successivo consiste nel creare la configurazione del modello.

Crea la configurazione del modello

In questa parte dell'esercitazione la cartella del modello si trova in working\content\extensions.

I modelli vengono riconosciuti da .NET perché hanno una cartella e un file di configurazione speciali che esistono nella radice della cartella del modello.

Per prima cosa, creare una nuova sottocartella denominata .template.confige immetterla. Creare quindi un nuovo file denominato template.json. La struttura di cartelle dovrebbe essere simile alla seguente:

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

Aprire il file template.json con l'editor di testo preferito, incollarlo nel codice JSON seguente e salvarlo.

{
    "$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"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

Questo file di configurazione contiene tutte le impostazioni per il modello. È possibile visualizzare le impostazioni di base, ad esempio name e shortName, ma esiste anche un valore tags/type impostato su item. In questo modo il modello viene categorizzato come modello di "elemento". Non esiste alcuna restrizione per il tipo di modello che si può creare. I valori item e project sono nomi comuni che .NET consiglia per consentire agli utenti di filtrare facilmente il tipo di modello da cercare.

L'elemento classifications rappresenta la colonna tags visualizzata quando si esegue dotnet new e si ottiene un elenco di modelli. Gli utenti possono anche eseguire ricerche in base ai tag di classificazione. Non confondere la proprietà tags nel file template.json con l'elenco dei tag classifications. Sono due concetti diversi che purtroppo hanno lo stesso nome. Lo schema completo per il file di template.json è disponibile nella Archivio schemi JSON e viene descritto in Riferimento per template.json. Per altre informazioni sul file template.json, vedere il wiki sulla creazione di modelli dotnet.

La parte symbols di questo oggetto JSON viene usata per definire i parametri che possono essere usati nel modello. In questo caso, è presente un parametro definito, ClassName. Il parametro definito contiene le impostazioni seguenti:

  • type: questa è un'impostazione obbligatoria e deve essere impostata su parameter.
  • description: la descrizione del parametro, che viene stampata nella guida del modello.
  • datatype: Il tipo di dati del valore del parametro quando il parametro viene usato.
  • replaces: specifica un valore di testo che deve essere sostituito in tutti i file di modello in base al valore del parametro.
  • fileRename: Simile a replaces, specifica un valore di testo che viene sostituito nei nomi di tutti i file modello dal valore del parametro.
  • defaultValue: il valore predefinito di questo parametro quando non viene specificato dall'utente.

Quando si usa il modello, l'utente può fornire un valore per il parametro ClassName e questo valore sostituisce tutte le occorrenze di StringExtensions. Se non viene specificato un valore, viene usato defaultValue. Per questo modello sono presenti due occorrenze di StringExtensions: il file StringExtensions.cs e la classe StringExtensions. Poiché il defaultValue del parametro è StringExtensions, il nome del file e il nome della classe rimangono invariati se il parametro non viene specificato quando si usa il modello. Quando viene specificato un valore, ad esempio dotnet new stringext -ClassName MyExts, il file viene rinominato MyExts.cs e la classe viene rinominata in MyExts.

Per visualizzare i parametri disponibili per un modello, usare il parametro -? con il nome del modello:

dotnet new stringext -?

L'output ottenuto sarà il seguente:

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

Ora che è disponibile un file .template.config/template.json valido, il modello è pronto per l'installazione. Nel terminale passare alla cartella extensions ed eseguire il comando seguente per installare il modello che si trova nella cartella corrente:

  • In Windows: dotnet new install .\
  • In Linux o macOS: dotnet new install ./

Questo comando restituisce l'elenco dei modelli installati, che dovrebbe includere quello creato in questa esercitazione.

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

Testare il modello di elemento

Ora che è stato installato un modello di elemento, è opportuno testarlo.

  1. Passare alla cartella test.

  2. Creare una nuova applicazione console con dotnet new console, che genera un progetto funzionante che può essere facilmente testato con il comando dotnet run.

    dotnet new console

    Si ottiene un output simile al seguente.

    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.

  3. Eseguire il progetto usando il comando seguente.

    dotnet run

    Il risultato è il seguente.

    Hello, World!

  4. Eseguire dotnet new stringext per generare il file StringExtensions.cs dal modello.

    dotnet new stringext

    Il risultato è il seguente.

    The template "Example templates: string extensions" was created successfully.

  5. Modificare il codice in Program.cs per invertire la stringa "Hello, World!" con il metodo di estensione fornito dal modello.

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

    Eseguire di nuovo il programma e verificare che il risultato sia invertito.

    dotnet run

    Il risultato è il seguente.

    !dlroW ,olleH

Complimenti. È stato creato e distribuito un modello di elemento con .NET. Per prepararsi alla parte successiva di questa serie di esercitazioni, è necessario disinstallare il modello creato. Assicurarsi di eliminare anche tutti i file e le cartelle della cartella test. In questo modo viene ripristinato uno stato pulito, pronto per la parte successiva di questa serie di esercitazioni.

Disinstallare il modello

Nel terminale passare alla cartella estensioni ed eseguire il comando seguente per disinstallare i modelli presenti nella cartella corrente:

  • In Windows: dotnet new uninstall .\
  • In Linux o macOS: dotnet new uninstall ./

Questo comando restituisce un elenco dei modelli disinstallati, che dovrebbe includere i propri.

Success: <root path>\working\content\extensions was uninstalled.

In qualsiasi momento, è possibile usare dotnet new uninstall per visualizzare un elenco di pacchetti di modelli installati, incluso per ogni pacchetto di modello il comando per disinstallarlo.

Passaggi successivi

In questa esercitazione è stato creato un modello di elemento. Per scoprire come creare un modello di progetto, continuare con questa serie di esercitazioni.

Creare un modello di progetto