Esercitazione: Creare un pacchetto modello

2025-04-21

Con .NET è possibile creare e distribuire modelli che generano progetti, file e persino risorse. Questa esercitazione è la terza 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.

In questa parte della serie si apprenderà come:

Creare un pacchetto modello usando il pacchetto NuGet Microsoft.TemplateEngine.Authoring.Templates .
Installare un pacchetto modello da un file di pacchetto NuGet.
Disinstallare un pacchetto modello tramite ID pacchetto.

Prerequisiti

Completare la parte 1 e la parte 2 di questa serie di esercitazioni.

Questa esercitazione usa i due modelli creati nelle prime due parti di questa serie di esercitazioni. È possibile usare un modello diverso purché si copia il modello, come cartella, nella cartella working\content .
Aprire un terminale e passare alla cartella di lavoro .
Installare .NET 8 o .NET 9.
Installare il Microsoft.TemplateEngine.Authoring.Templates modello dal feed del pacchetto NuGet.
- Eseguire il dotnet new install Microsoft.TemplateEngine.Authoring.Templates comando dal terminale.

Creare un progetto di pacchetto modello

Un pacchetto modello è uno o più modelli compressi in un pacchetto NuGet. Quando si installa o si disinstalla un pacchetto modello, tutti i modelli contenuti nel pacchetto vengono aggiunti o rimossi, rispettivamente.

I pacchetti modello sono rappresentati da un file di pacchetto NuGet (con estensione nupkg). Analogamente a qualsiasi pacchetto NuGet, è possibile caricare il pacchetto modello in un feed NuGet. Il dotnet new install comando supporta l'installazione di pacchetti modello da un feed di pacchetti NuGet, un file con estensione nupkg o una directory con un modello.

In genere si usa un file di progetto C# per compilare il codice e produrre un file binario. Tuttavia, il progetto può anche essere usato per generare un pacchetto modello. Modificando le impostazioni di .csproj, è possibile impedirne la compilazione di qualsiasi codice e includere invece tutti gli asset dei modelli come risorse. Quando questo progetto viene compilato, genera un pacchetto NuGet modello.

Il pacchetto che verrà generato includerà gli elementi e i modelli di progetto creati in precedenza.

Il pacchetto Microsoft.TemplateEngine.Authoring.Templates contiene modelli utili per la creazione di modelli. Per installare questo pacchetto, nuget.org deve essere presente come feed NuGet nella directory di lavoro.

Nella cartella di lavoro eseguire il comando seguente per creare il pacchetto modello:

dotnet new templatepack -n "AdatumCorporation.Utility.Templates"

Il -n parametro imposta il nome del file di progetto su AdatumCorporation.Utility.Templates.csproj. Verrà visualizzato un risultato simile all'output seguente.

The template "Template Package" was created successfully.

Processing post-creation actions...
Description: Manual actions required
Manual instructions: Open *.csproj in the editor and complete the package metadata configuration. Copy the templates to _content_ folder. Fill in README.md.

Aprire quindi il file AdatumCorporation.Utility.Templates.csproj in un editor di codice e popolarlo in base agli hint nel modello:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- The package metadata. Fill in the properties marked as TODO below -->
    <!-- Follow the instructions on https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices -->
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <PackageVersion>1.0</PackageVersion>
    <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>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>net8.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
    ... cut for brevity ...

Descrizione del codice XML del progetto

Le impostazioni in <PropertyGroup> nel frammento XML vengono suddivise in due gruppi.

Il primo gruppo si occupa delle proprietà necessarie per un pacchetto NuGet. Le quattro <Package*> impostazioni devono avere a che fare con le proprietà del pacchetto NuGet per identificare il pacchetto in un feed NuGet. Il <PackageId> valore, mentre viene usato da NuGet, viene usato anche per disinstallare il pacchetto modello. Le impostazioni rimanenti, ad esempio <Title> e <PackageTags>, devono avere a che fare con i metadati visualizzati nel feed NuGet e nella gestione pacchetti .NET. Per altre informazioni sulle impostazioni di NuGet, vedere Proprietà NuGet e MSBuild.

Annotazioni

Per assicurarsi che il pacchetto modello venga visualizzato nei dotnet new search risultati, <PackageType> deve essere impostato su Template.

Nel secondo gruppo, l'impostazione <TargetFramework> garantisce che MSBuild venga eseguito correttamente quando si esegue il comando pack per compilare e comprimere il progetto. Il gruppo include anche le impostazioni che devono avere a che fare con la configurazione del progetto per includere i modelli nella cartella appropriata nel pacchetto NuGet al momento della creazione:

L'impostazione <NoWarn> elimina un messaggio di avviso che non si applica ai progetti del pacchetto modello.
L'impostazione <NoDefaultExcludes> garantisce che i file e le cartelle che iniziano con un . oggetto (ad esempio .gitignore) facciano parte del modello. Il comportamento predefinito dei pacchetti NuGet consiste nell'ignorare tali file e cartelle.

<ItemGroup> contiene due elementi. In primo luogo, l'elemento <Content> include tutti gli elementi nella cartella templates come contenuto. È anche impostato per escludere qualsiasi cartella bin o cartella obj per impedire l'inclusione di codice compilato (se sono stati testati e compilati i modelli). In secondo luogo, l'elemento <Compile> esclude tutti i file di codice dalla compilazione indipendentemente dalla posizione in cui si trovano. Questa impostazione impedisce al progetto usato per creare il pacchetto modello di tentare di compilare il codice nella gerarchia di cartelle templates .

Suggerimento

Per altre informazioni sulle impostazioni dei metadati NuGet, vedere Comprimere un modello in un pacchetto NuGet (file nupkg).

Il file di progetto creato include la creazione di modelli di attività MSBuild e le impostazioni di localizzazione.

  <PropertyGroup>
    <LocalizeTemplates>false</LocalizeTemplates>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.TemplateEngine.Tasks" Version="*" PrivateAssets="all" IsImplicitlyDefined="true"/>
  </ItemGroup>

Importante

La cartella del contenuto contiene una cartella SampleTemplate . Eliminare questa cartella, perché è stata aggiunta al modello di creazione a scopo dimostrativo.

Queste attività di MSBuild forniscono la convalida dei modelli e la localizzazione delle funzionalità dei modelli . La localizzazione è disabilitata per impostazione predefinita. Per abilitare la creazione di file di localizzazione, impostare LocalizeTemplates su true.

Confeziona e installa

Salvare il file di progetto. Prima di compilare il pacchetto modello, verificare che la struttura di cartelle sia corretta. Tutti i modelli che si desidera inserire nella cartella del contenuto devono essere inseriti nella cartella del contenuto, nella relativa cartella. La struttura di cartelle dovrebbe essere simile alla gerarchia seguente:

working
│   AdatumCorporation.Utility.Templates.csproj
└───content
    ├───extensions
    │   └───.template.config
    │           template.json
    └───consoleasync
        └───.template.config
                template.json

La cartella del contenuto include due cartelle: estensioni e consoleasync.

Nel terminale, dalla cartella di lavoro , eseguire il dotnet pack comando . Questo comando compila il progetto e crea un pacchetto NuGet nella cartella working\bin\Release , come indicato dall'output seguente:

MSBuild version 17.8.0-preview-23367-03+0ff2a83e9 for .NET
  Determining projects to restore...
  Restored C:\code\working\AdatumCorporation.Utility.Templates.csproj (in 1.16 sec).

  AdatumCorporation.Utility.Templates -> C:\code\working\bin\Release\net8.0\AdatumCorporation.Utility.Templates.dll
  Successfully created package 'C:\code\working\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg'.

Installare quindi il pacchetto modello con il dotnet new install comando . In Windows:

dotnet new install .\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

In Linux o macOS:

dotnet new install bin/Release/AdatumCorporation.Utility.Templates.1.0.0.nupkg

L'output dovrebbe essere simile al seguente:

The following template packages will be installed:
   C:\code\working\AdatumCorporation.Utility.Templates\bin\Release\AdatumCorporation.Utility.Templates.1.0.0.nupkg

Success: AdatumCorporation.Utility.Templates::1.0.0 installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code
Example templates: async project                  consoleasync             [C#]              Common/Console/C#9

Se il pacchetto NuGet è stato caricato in un feed NuGet, è possibile usare il dotnet new install <PACKAGE_ID> comando dove <PACKAGE_ID> corrisponde all'impostazione <PackageId> del file con l'estensione .csproj.

Disinstallare il pacchetto modello

Indipendentemente dal modo in cui è stato installato il pacchetto modello, con il file con estensione nupkg direttamente o dal feed NuGet, la rimozione di un pacchetto modello è la stessa. Usare il <PackageId> del modello da disinstallare. È possibile ottenere un elenco di modelli installati eseguendo il dotnet new uninstall comando .

C:\working> dotnet new uninstall
Currently installed items:
... cut to save space ...

  AdatumCorporation.Utility.Templates
    Details:
      NuGetPackageId: AdatumCorporation.Utility.Templates
      Version: 1.0.0
      Author: Me
    Templates:
      Example templates: async project (consoleasync) C#
      Example templates: string extensions (stringext) C#
    Uninstall Command:
      dotnet new uninstall AdatumCorporation.Utility.Templates

Eseguire dotnet new uninstall AdatumCorporation.Utility.Templates per disinstallare il pacchetto modello. Il comando restituisce informazioni sui pacchetti modello disinstallati.

Congratulazioni! È stato installato e disinstallato un pacchetto modello.

Passaggi successivi

Per ulteriori informazioni sui modelli, la maggior parte dei quali hai già appreso, vedere l'articolo Modelli personalizzati per dotnet new.

Condividi tramite