Tutoriel : créer un package de modèles

Article
10/09/2023

Avec .NET, vous pouvez créer et déployer des modèles qui génèrent des projets, des fichiers et même des ressources. Ce tutoriel est le troisième d’une série qui vous apprend comment créer, installer et désinstaller des modèles à utiliser avec la commande dotnet new.

Vous pouvez consulter le modèle terminé dans le référentiel d’échantillons GitHub .NET.

Dans cette partie de la série, vous découvrirez comment :

Créez un package de modèle à l’aide du package NuGet Microsoft.TemplateEngine.Authoring.Templates.
Installez un package de modèles à partir d'un fichier de package NuGet.
Désinstallez un package de modèles par ID de package.

Créez un projet *.csproj pour générer un package de modèles.
Configurez le fichier projet pour la compression.
Installez un package de modèles à partir d'un fichier de package NuGet.
Désinstallez un package de modèles par ID de package.

Prérequis

Complétez la première partie et la deuxième partie de cette série de tutoriels.

Ce tutoriel utilise les deux modèles créés dans les deux premières parties de cette série de tutoriels. Vous pouvez utiliser un autre modèle à condition de copier le modèle en tant que dossier dans le dossier working\content.
Ouvrez un terminal et accédez au dossier working.

Installez .NET 8.
Installez le modèle Microsoft.TemplateEngine.Authoring.Templates à partir du flux de package NuGet.
- Exécutez la commande dotnet new install Microsoft.TemplateEngine.Authoring.Templates à partir de votre terminal.

Important

Cet article est écrit pour .NET 7. Cependant, il s’applique aussi à .NET 6 et aux versions antérieures, à une différence près : la syntaxe de dotnet new est différente. Les sous-commandes list, search, install et uninstall doivent être les options --list, --search, --install et --uninstall, respectivement.

Par exemple, la commande dotnet new install dans .NET 7 devient dotnet new --install dans .NET 6. Utilisez la commande dotnet new --help pour afficher la liste de toutes les options et sous-commandes.

Créer un projet de package de modèles

Un package de modèles désigne un ou plusieurs modèles empaquetés dans un package NuGet. Lorsque vous installez ou désinstallez un package de modèles, tous les modèles contenus dans le package sont ajoutés ou supprimés, respectivement.

Les packages de modèles sont représentés par un fichier de package NuGet (.nupkg). Et, comme n’importe quel package NuGet, vous pouvez charger le package de modèles dans un flux NuGet. La commande dotnet new install prend en charge l'installation de packages de modèles à partir d'un flux de package NuGet, d'un fichier .nupkg ou d'un répertoire avec un modèle.

Normalement, vous utilisez un fichier projet C# pour compiler le code et produire un fichier binaire. Toutefois, le projet peut également être utilisé pour générer un package de modèles. En modifiant les paramètres de .csproj, vous pouvez l’empêcher de compiler n’importe quel code et inclure à la place toutes les ressources de vos modèles en tant que ressources. Lorsque ce projet est généré, il produit un package NuGet de package de modèles.

Le package que vous allez générer inclut les modèles [item] et (cli-templates-create-item-template.md), ainsi que les modèles de projet précédemment créés.

Le package Microsoft.TemplateEngine.Authoring.Templates contient des modèles utiles pour la création de modèles. Pour installer ce package, nuget.org doit être disponible en tant que flux NuGet dans le répertoire de travail.

Dans le dossier de travail, exécutez la commande suivante pour créer le package de modèle :

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

Le paramètre -n définit le nom du fichier projet sur AdatumCorporation.Utility.Templates.csproj. Vous devez voir un résultat similaire à la sortie suivante.

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.

Ensuite, ouvrez le fichier AdatumCorporation.Utility.Templates.csproj dans un éditeur de code et remplissez-le en fonction des conseils du modèle :

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

Dans le dossier de travail, exécutez la commande suivante pour créer le package de modèle :

dotnet new console -n AdatumCorporation.Utility.Templates

Le paramètre -n définit le nom du fichier projet sur AdatumCorporation.Utility.Templates.csproj. Vous devez voir un résultat similaire à la sortie suivante.

The template "Console Application" was created successfully.

Processing post-creation actions...
Running 'dotnet restore' on .\AdatumCorporation.Utility.Templates.csproj...
  Restore completed in 52.38 ms for C:\code\working\AdatumCorporation.Utility.Templates.csproj.

Restore succeeded.

Supprimez le fichier Program.cs. Le nouveau modèle de projet génère ce fichier, mais il n'est pas utilisé par le moteur de modèles.

Ensuite, ouvrez le fichier AdatumCorporation.Utility.Templates.csproj dans votre éditeur favori et remplacez le contenu par le code XML suivant :

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

  <PropertyGroup>
    <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;adatum</PackageTags>
    <PackageProjectUrl>https://your-url</PackageProjectUrl>

    <PackageType>Template</PackageType>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
    <NoWarn>$(NoWarn);NU5128</NoWarn>
    <NoDefaultExcludes>true</NoDefaultExcludes>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="content\**\*" Exclude="content\**\bin\**;content\**\obj\**" />
    <Compile Remove="**\*" />
  </ItemGroup>

</Project>

Description du projet XML

Les paramètres sous <PropertyGroup> dans l'extrait de code XML sont divisés en deux groupes.

Le premier groupe traite des propriétés requises pour un package NuGet. Les quatre paramètres <Package*> doivent être définis avec les propriétés du package NuGet pour identifier votre package sur un flux NuGet. La valeur <PackageId>, utilisée par NuGet, est également utilisée pour désinstaller le package de modèle. Les paramètres restants, notamment <Title> et <PackageTags>, doivent être liés aux métadonnées affichées sur le flux NuGet et le gestionnaire de package .NET. Pour plus d’informations sur les paramètres NuGet, consultez Propriétés NuGet et MSBuild.

Remarque

Pour vous assurer que le package de modèles apparaît dans les résultats dotnet new search, définissez <PackageType> sur Template.

Dans le deuxième groupe, le paramètre <TargetFramework> garantit que MSBuild s'exécute correctement lorsque vous exécutez la commande pack pour compiler et compresser le projet. Le groupe inclut également des paramètres qui doivent être utilisés pour configurer le projet afin d'inclure les modèles dans le dossier approprié du package NuGet lors de sa création :

Le paramètre <NoWarn> supprime un message d’avertissement qui ne s’applique pas aux projets de package de modèles.
Le paramètre <NoDefaultExcludes> garantit que les fichiers et dossiers qui commencent par un . (comme .gitignore) font partie du modèle. Le comportement par défaut des packages NuGet consiste à ignorer ces fichiers et dossiers.

<ItemGroup> contient deux éléments. Tout d’abord, l’élément <Content> inclut l’ensemble du dossier templates en tant que contenu. Il est également défini pour exclure tout dossier bin ou obj pour empêcher l’inclusion de code compilé (si vous avez testé et compilé vos modèles). Ensuite, l’élément <Compile> exclut la compilation de tous les fichiers de code, quel que soit l’emplacement où ils se trouvent. Ce paramètre empêche le projet utilisé pour créer un package de modèles d’essayer de compiler le code dans la hiérarchie des dossiers templates.

Conseil

Pour plus d'informations sur les paramètres de métadonnées NuGet, reportez-vous à Compresser un modèle dans un package NuGet (fichier nupkg).

Le fichier projet créé inclut des modèles de création de tâches MSBuild et des paramètres de localisation.

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

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

Important

Le dossier de contenu contient un dossier SampleTemplate. Supprimez ce dossier, car il a été ajouté au modèle de création à des fins de démonstration.

Ces tâches MSBuild fournissent la validation des modèles et la localisation des fonctionnalités des modèles. La localisation est désactivée par défaut. Pour activer la création de fichiers de localisation, définissez LocalizeTemplates sur true.

Compresser et installer

Enregistrez le fichier projet. Avant de générer le package de modèles, vérifiez que votre structure de dossiers est correcte. Tout modèle que vous souhaitez empaqueter doit être placé dans le dossier templates, dans son propre dossier. La structure de dossiers doit ressembler à la hiérarchie suivante :

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

Le dossier contenu comporte deux dossiers : extensions et consoleasync.

Dans votre terminal, à partir du dossier working, exécutez la commande dotnet pack. Cette commande génère le projet et crée un package NuGet dans le dossier working\bin\Debug, comme indiqué par la sortie suivante :

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

Installez ensuite le package de modèles avec la commande dotnet new install. Sur Windows :

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

Sur Linux ou macOS :

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

Vous devez obtenir une sortie similaire à la suivante :

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

Si vous avez chargé le package NuGet dans un flux NuGet, vous pouvez utiliser la commande dotnet new install <PACKAGE_ID>, où <PACKAGE_ID> est identique au paramètre <PackageId> du fichier .csproj.

Désinstaller le package de modèles

Quelle que soit la façon dont vous avez installé le package de modèles, directement avec le fichier .nupkg ou avec le flux NuGet, la suppression d’un package de modèles est identique. Utilisez <PackageId> du modèle à désinstaller. Vous pouvez obtenir la liste des modèles installés en exécutant la commande dotnet new uninstall.

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

Exécutez dotnet new uninstall AdatumCorporation.Utility.Templates pour désinstaller le package de modèles. La commande génère des informations sur les packages de modèles qui ont été désinstallés.

Félicitations ! Vous avez installé et désinstallé un package de modèles.

Étapes suivantes

Pour en savoir plus sur les modèles, consultez l’article Modèles personnalisés pour dotnet new.

Partager via