Condividi tramite

Esercitazione: Creare un modello di elemento

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

È possibile visualizzare il modello completato nel repository GitHub degli esempi .NET.

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 9 o versione successiva.

  • L'articolo di riferimento illustra le nozioni di base sui modelli e il modo in cui vengono messi insieme. Alcune di queste informazioni sono ripetute qui.

  • Aprire un terminale e passare a una cartella in cui archiviare e testare i modelli.

Creare le cartelle necessarie

Questa serie usa una "cartella di lavoro" in cui l'origine del modello è contenuta 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.

Innanzitutto, crea la cartella principale; il nome non è importante. Creare quindi due sottocartelle denominate working e test. All'interno della cartella di lavoro creare una sottocartella denominata contenuto.

La struttura di cartelle dovrebbe essere simile alla 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, ad esempio un file di configurazione o un file di codice. In questo esempio si crea 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 delle estensioni e creare un nuovo file denominato StringExtensions.cs. Aprire il file in un editor di testo. Questa classe fornisce 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);
    }
}

Ora che il contenuto del modello è terminato, creare la configurazione del modello.

Creare la configurazione del template

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 speciale e un file di configurazione presenti nella radice della cartella del modello.

Creare prima di tutto 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 template.json con l'editor di testo preferito e 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 tags/type valore impostato su item. In questo modo il modello viene categorizzato come modello di "elemento". Non esiste alcuna restrizione sul tipo di modello creato. I valori item e project sono nomi comuni che .NET consiglia per consentire agli utenti di filtrare facilmente il tipo di modello che stanno cercando.

L'elemento classifications rappresenta la colonna tag 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 tags proprietà nel file template.json con l'elenco dei classifications tag. Sono due concetti diversi, purtroppo denominati allo stesso modo. Lo schema completo per il file template.json è disponibile nell'archivio schemi JSON ed è descritto in Informazioni di riferimento per template.json. Per altre informazioni sul file template.json , vedere il wiki dotnet templating.

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

  • type - Si tratta di un'impostazione obbligatoria e deve essere impostata su parameter.
  • description - La descrizione del parametro, che viene visualizzata nell'aiuto modello.
  • datatype - Tipo di dati del valore del parametro quando viene usato il parametro.
  • 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 sostituito nei nomi di tutti i file di modello in base al valore del parametro .
  • defaultValue - Valore predefinito di questo parametro quando il parametro non è specificato dall'utente.

Quando si usa il modello, l'utente può fornire un valore per il ClassName parametro 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 parametro è StringExtensions, il nome 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 vedere quali parametri sono disponibili per un modello, usare il -? parametro con il nome del modello:

dotnet new stringext -?

Che produce l'output 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 si dispone di un file di.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 il tuo.

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

Dopo aver installato un modello di elemento, testarlo.

  1. Passare alla cartella di test .

  2. Creare una nuova applicazione console con dotnet new console, che genera un progetto funzionante che è possibile testare facilmente con il dotnet run comando .

    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

    Viene visualizzato l'output seguente.

    Hello, World!

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

    dotnet new stringext

    Viene visualizzato l'output seguente.

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

  5. Modificare il codice in Program.cs in modo da invertire la "Hello, World!" stringa 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

    Viene visualizzato l'output seguente.

    !dlroW ,olleH

Congratulazioni! È stato creato e distribuito un modello di elemento con .NET. In preparazione per la parte successiva di questa serie di esercitazioni, disinstallare il modello creato. Assicurarsi di eliminare anche tutti i file e le cartelle nella cartella di test . In questo modo si torna a uno stato pulito pronto per la parte successiva di questa serie di esercitazioni.

Disinstallare il modello

Nel terminale passare alla cartella extensions 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 il tuo.

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, tra cui per ogni pacchetto di modello il comando da disinstallare.

Passaggi successivi

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

Creare un modello di progetto

  • Last updated on