Esercitazione: Creare un modello di progetto

  • Articolo

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

Suggerimento

I modelli .NET ufficiali forniti con l’SDK .NET sono disponibili nei repository seguenti:

Modelli Repository
Console, libreria di classi e modelli di elementi comuni dotnet/sdk
Modelli ASP.NET e Blazor dotnet/aspnetcore
Modelli di applicazione a pagina singola ASP.NET dotnet/spa-templates
Modelli WPF dotnet/wpf
Modelli Windows Forms dotnet/winforms
Testare i modelli dotnet/test-templates
Modelli MAUI dotnet/maui

È possibile visualizzare i modelli installati sul computer eseguendo il comando dotnet new list.

In questa parte della serie si apprenderà come:

  • Creare le risorse di un modello di progetto.
  • 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

  • Completare la parte 1 di questa serie di esercitazioni.
  • Aprire un terminale e passare alla cartella working\content.

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, install e uninstall devono essere rispettivamente le opzioni --list, --search, --install e --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 un modello di progetto

I modelli di progetto producono progetti pronti per l'esecuzione che consentono agli utenti di iniziare in modo facile a utilizzare un working set di codice. .NET include alcuni modelli di progetto, ad esempio un'applicazione console o una libreria di classi. In questo esempio viene creato un nuovo progetto di applicazione console che sostituisce l'output della console "Hello World" standard con quello eseguito in modo asincrono.

Nel terminale passare alla cartella working\content e creare una nuova sottocartella denominata consoleasync. Immettere la sottocartella ed eseguire dotnet new console per generare l'applicazione console standard. Verranno modificati i file prodotti da questo modello per creare un nuovo modello.

working
└───content
    └───consoleasync
            consoleasync.csproj
            Program.cs

Modificare Program.cs

Aprire il file Program.cs. Il progetto console standard non scrive in modo asincrono nell'output della console, quindi aggiungiamolo. Modificare il codice nel modo seguente e salvare il file:

// See https://aka.ms/new-console-template for more information
await Console.Out.WriteAsync("Hello World with C#");

Ora che è stato creato il contenuto del modello, è necessario creare la configurazione del modello nella cartella radice del modello.

Crea la configurazione del modello

In questa esercitazione la cartella del modello si trova in working\content\consoleasync.

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

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

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

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

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Me",
  "classifications": [ "Common", "Console" ],
  "identity": "ExampleTemplate.AsyncProject",
  "name": "Example templates: async project",
  "shortName": "consoleasync",
  "sourceName":"consoleasync",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

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 project. In questo modo il modello viene categorizzato come modello di "progetto". 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 sourceName viene sostituito quando l'utente usa il modello. Il valore di sourceName nel file di configurazione viene cercato in ogni nome file e contenuto del file e, per impostazione predefinita, viene sostituito con il nome della cartella corrente. Quando il parametro -n o --name viene passato con il comando dotnet new, viene usato il valore specificato anziché il nome della cartella corrente. Nel caso di questo modello, consoleasync viene sostituito nel nome del file .csproj.

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

Ora che è disponibile un file .template.config/template.json valido, il modello è pronto per l'installazione. Prima di installare il modello, assicurarsi di eliminare eventuali file e cartelle aggiuntivi che non si vuole includere nel modello, ad esempio le cartelle bin o obj. Nel terminale passare alla cartella consoleasync ed eseguire dotnet new install .\ per installare il modello che si trova nella cartella corrente. Se si usa un sistema operativo Linux o macOS, usare una barra: dotnet new install ./.

dotnet new install .\

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

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

Success: <root path>\working\content\consoleasync installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: async project                  consoleasync             [C#]              Common/Console

Testare il modello di progetto

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

  1. Passare alla cartella test.

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

    dotnet new consoleasync -n MyProject

    Il risultato è il seguente.

    The template "Example templates: async project" was created successfully.

  3. Eseguire il progetto usando il comando seguente.

    dotnet run

    Il risultato è il seguente.

    Hello World with C#

Complimenti. È stato creato e distribuito un modello di progetto con .NET. Per prepararsi alla parte successiva di questa serie di esercitazioni, è necessario disinstallare il modello creato. Assicurarsi di eliminare anche tutti i file dalla 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 consoleasync ed eseguire il comando seguente per disinstallare il modello 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\consoleasync 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 progetto. Per informazioni su come creare un pacchetto dei modelli di elementi e di progetto in un file di facile utilizzo, continuare con questa serie di esercitazioni.

Creare un pacchetto di modelli