Partage via

Tutoriel : Créer un package de modèle

  • Article

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 la troisième partie d’une série qui vous apprend à créer, installer et désinstaller des modèles à utiliser avec la commande dotnet new.

Vous pouvez consulter le modèle complété dans le dépôt GitHub des échantillons .NET .

Dans cette partie de la série, vous allez apprendre à :

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

Conditions préalables

  • Terminez partie 1 et partie 2 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 tant que vous copiez le modèle, en tant que dossier, dans le working\content dossier.

  • Ouvrez un terminal et accédez au dossier de travail.

  • Installez .NET 8 ou .NET 9.

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

Créer un projet de package de modèles

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

Les packages de modèle sont représentés par un package NuGet (fichier .nupkg). Et, comme n’importe quel package NuGet, vous pouvez charger le package de modèle 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 du code et produire un fichier binaire. Toutefois, le projet peut également être utilisé pour générer un package de modèle. En modifiant les paramètres du.csproj , vous pouvez l’empêcher de compiler n’importe quel code et d’inclure 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 inclura les modèles d’éléments et de projets 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.

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

  2. Ensuite, ouvrez le fichier AdatumCorporation.Utility.Templates.csproj dans un éditeur de code et remplissez-le en fonction des indicateurs 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 ...

Description du code XML du projet

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 liés aux 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, tels que <Title> et <PackageTags>, doivent être associé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, <PackageType> doit être défini 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 packer 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èle.

  • 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 tout ce qui se trouve dans les modèles dossier en tant que contenu. Il est également défini pour exclure tout dossier bin ou dossier obj pour empêcher tout code compilé (si vous avez testé et compilé vos modèles) d’être inclus. Deuxièmement, l’élément <Compile> exclut tous les fichiers de code de la compilation, quel que soit l’emplacement où ils se trouvent. Ce paramètre empêche le projet utilisé pour créer le package de modèle d’essayer de compiler le code dans les modèles hiérarchie de dossiers.

Conseil

Pour plus d’informations sur les paramètres de métadonnées NuGet, consultez Emballer un modèle dans un package NuGet (fichier nupkg).

Le fichier projet créé inclut le modèle de création de tâches MSBuild et les 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. Supprimer 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.

Pack et installation

Enregistrez le fichier projet. Avant de générer le package de modèle, vérifiez que votre structure de dossiers est correcte. Tout modèle que vous souhaitez compresser doit être placé dans le dossier modèles, dans son propre sous-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 de travail, exécutez la commande dotnet pack. Cette commande génère le projet et crée un package NuGet dans le dossier working\bin\Release, 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'.

Ensuite, installez le package de modèle 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 voir une sortie similaire à ce qui suit :

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 de <PackageId> à partir du fichier .csproj.

Désinstaller le package de modèles

Quelle que soit la façon dont vous avez installé le package de modèle, soit avec le fichier .nupkg directement, soit par le flux NuGet, la suppression d’un package de modèle est la même. Utilisez la <PackageId> du modèle que vous souhaitez 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èle. La commande génère des informations sur les packages de modèle qui ont été désinstallés.

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

Étapes suivantes

Pour en savoir plus sur les modèles, dont vous connaissez déjà la plupart, consultez l'article Modèles personnalisés pour dotnet new.