Tutoriel : Créer un modèle d’élément

  • Article

Avec .NET, vous pouvez créer et déployer des modèles qui génèrent des projets, des fichiers et des ressources. Ce didacticiel est le premier 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.

Conseil

Les modèles d’éléments ne sont pas affichés dans la boîte de dialogue Ajouter>un nouvel élément de Visual Studio.

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

  • Créez une classe pour un modèle d'élément.
  • Créez le dossier et le fichier de configuration du modèle.
  • Installez un modèle à partir d'un chemin de fichier.
  • Testez un modèle d'élément.
  • Désinstallez un modèle d'élément.

Prérequis

  • Sdk .NET 7.0.100 ou version ultérieure.

    L’article de référence explique les notions de base sur les modèles et la façon dont ils sont créés. Certaines de ces informations sont réitérées ici.

  • Ouvrez un terminal et accédez à un dossier dans lequel vous stockerez et testerez les modèles.

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 les dossiers requis

Cette série utilise un « dossier de travail » dans lequel se trouve votre source de modèle et un « dossier de test » utilisé pour tester vos modèles. Le dossier de travail et le dossier de test doivent se trouver sous le même dossier parent.

Tout d’abord, créez le dossier parent, le nom n’a pas d’importance. Ensuite, créez deux sous-dossiers nommés de travail et test. À l’intérieur du dossier de travail, créez un sous-dossier nommé content.

La structure des dossiers doit ressembler à ce qui suit.

parent_folder
├───test
└───working
    └───content

Créer un modèle d’élément

Un modèle d’élément est un type spécifique de modèle qui contient un ou plusieurs fichiers. Ces types de modèles sont utiles lorsque vous avez déjà un projet et que vous souhaitez générer un autre fichier, comme un fichier de configuration ou un fichier de code. Dans cet exemple, vous allez créer une classe qui ajoute une méthode d’extension au type de chaîne.

Dans votre terminal, accédez au dossier du travail\content et créez un nouveau sous-dossier nommé extensions.

working
└───content
    └───extensions

Accédez au dossier extensions et créez un nouveau fichier nommé StringExtensions.cs. Ouvrez le fichier dans un éditeur de texte. Cette classe fournit une méthode d’extension nommée Reverse qui inverse le contenu d’une chaîne. Collez le code suivant et enregistrez le fichier :

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Maintenant que le contenu du modèle est terminé, l'étape suivante consiste à créer la configuration du modèle.

Créer la configuration du modèle

Dans cette partie du didacticiel, votre dossier de modèles se trouve dans travail\content\extensions.

Les modèles sont reconnus par .NET car ils disposent d'un dossier spécial et d'un fichier de configuration qui existent à la racine de votre dossier de modèles.

Tout d’abord, créez un nouveau sous-dossier nommé .template.config et saisissez-le. Créez ensuite un nouveau fichier nommé template.json. La structure des dossiers doit ressembler à ceci :

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

Ouvrez le fichier template.json avec votre éditeur de texte favori, puis collez le code JSON suivant et enregistrez-le.

{
    "$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"
      }
    }
  }

Ce fichier de configuration contient tous les paramètres de votre modèle. Vous pouvez voir les paramètres de base, tels que name et shortName, mais il existe également une valeur tags/type définie sur item. Cela classe votre modèle comme un modèle « élément ». Il n’existe aucune restriction sur le type de modèle que vous créez. Les valeurs item et project sont des noms courants que .NET recommande afin que les utilisateurs puissent facilement filtrer le type de modèle qu’ils recherchent.

L’élément classifications représente la colonne tags que vous voyez lorsque vous exécutez dotnet new et obtenez une liste de modèles. Les utilisateurs peuvent également effectuer une recherche sur les balises de classification. Ne confondez pas la propriété tags du fichier template.json avec la liste des balises classifications. Ce sont deux concepts différents qui portent malheureusement le même nom. Le schéma complet du fichier template.json se trouve dans le magasin de schémas JSON et est décrit dans Référence pour template.json. Pour plus d’informations sur le fichier template.json, consultez le Wiki de création de modèles dotnet.

La partie symbols de cet objet JSON est utilisée pour définir les paramètres qui peuvent être utilisés dans le modèle. Dans ce cas, un paramètre est défini, ClassName. Le paramètre défini contient les paramètres suivants :

  • type – Il s'agit d'un paramètre obligatoire et doit être défini sur parameter.
  • description – La description du paramètre, qui est imprimée dans l'aide du modèle.
  • datatype – Le type de données de la valeur du paramètre lorsque le paramètre est utilisé.
  • replaces – Spécifie une valeur de texte qui doit être remplacée dans tous les fichiers modèles par la valeur du paramètre.
  • fileRename – Semblable à replaces, ceci spécifie une valeur de texte qui est remplacée dans les noms de tous les fichiers modèles par la valeur du paramètre.
  • defaultValue – La valeur par défaut de ce paramètre lorsque le paramètre n'est pas spécifié par l'utilisateur.

Lorsque le modèle est utilisé, l'utilisateur peut fournir une valeur pour le paramètre ClassName, et cette valeur remplace toutes les occurrences de StringExtensions. Si aucune valeur n’est fournie, la valeur defaultValue est utilisée. Pour ce modèle, il existe deux occurrences de StringExtensions : le fichier StringExtensions.cs et la classe StringExtensions. Étant donné que le defaultValue du paramètre est StringExtensions, le nom du fichier et le nom de la classe restent inchangés si le paramètre n'est pas spécifié lors de l'utilisation du modèle. Lorsqu'une valeur est spécifiée, par exemple dotnet new stringext -ClassName MyExts, le fichier est renommé MyExts.cs et la classe est renommée MyExts.

Pour voir quels paramètres sont disponibles pour un modèle, utilisez le paramètre -? portant le nom du modèle :

dotnet new stringext -?

Ce qui génère la sortie suivante :

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

Maintenant que vous avez un fichier .template.config/template.json valide, votre modèle est prêt à être installé. Dans votre terminal, accédez au dossier extensions et exécutez la commande suivante pour installer le modèle situé dans le dossier actuel :

  • Sous Windows : dotnet new install .\
  • Sous Linux ou macOS : dotnet new install ./

Cette commande génère la liste des modèles installés, qui doivent inclure le vôtre.

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

Tester le modèle d’élément

Maintenant que vous avez un modèle d’élément installé, testez-le.

  1. Accédez au dossier de test.

  2. Créez une nouvelle application console avec dotnet new console, qui génère un projet fonctionnel que vous pouvez facilement tester avec la commande dotnet run.

    dotnet new console

    La sortie obtenue doit ressembler à ce qui suit.

    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. Exécutez le projet à l’aide de la commande suivante.

    dotnet run

    Vous obtenez la sortie suivante.

    Hello, World!

  4. Exécutez dotnet new stringext pour générer le fichier StringExtensions.cs à partir du modèle.

    dotnet new stringext

    Vous obtenez la sortie suivante.

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

  5. Modifiez le code dans Program.cs pour inverser la chaîne "Hello, World!" avec la méthode d’extension fournie par le modèle.

    Console.WriteLine("Hello, World!".Reverse());

    Exécutez à nouveau le programme et voyez que le résultat est inversé.

    dotnet run

    Vous obtenez la sortie suivante.

    !dlroW ,olleH

Félicitations ! Vous avez créé et déployé un modèle d’élément avec .NET. En préparation de la prochaine partie de cette série de didacticiels, désinstallez le modèle que vous avez créé. Assurez-vous également de supprimer tous les fichiers et dossiers du dossier de test. Cela vous ramène à un état propre, prêt pour la prochaine partie de cette série de didacticiels.

Désinstaller le modèle

Dans votre terminal, accédez au dossier extensions et exécutez la commande suivante pour désinstaller le modèle situé dans le dossier actuel :

  • Sous Windows : dotnet new uninstall .\
  • Sous Linux ou macOS : dotnet new uninstall ./

Cette commande génère une liste des modèles qui ont été désinstallés, qui devrait inclure le vôtre.

Success: <root path>\working\content\extensions was uninstalled.

Vous pouvez utiliser dotnet new uninstall à tout moment, afin d’afficher la liste des packages de modèles installés, y compris pour chaque package de modèle, la commande permettant de le désinstaller.

Étapes suivantes

Dans ce tutoriel, vous avez créé un modèle d’élément. Pour savoir comment créer un modèle de projet, poursuivez cette série de tutoriels.

Créer un modèle de projet