Partager via

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

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

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

Conseil / Astuce

Les modèles d’élément 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 allez apprendre à :

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

Prerequisites

  • .NET 9 ou une version ultérieure.

  • L’article de référence explique les notions de base sur les modèles et leur mise en place. Certaines de ces informations sont répétées ici.

  • Ouvrez un terminal et accédez à un dossier dans lequel vous allez stocker et tester les modèles.

Créer les dossiers requis

Cette série utilise un « dossier de travail » dans lequel votre source de modèle est contenue 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 working and test. À l’intérieur du dossier de travail , créez un sous-dossier nommé contenu.

La structure de 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, tel qu’un fichier de configuration ou un fichier de code. Dans cet exemple, vous créez une classe qui ajoute une méthode d’extension au type de chaîne.

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

working
└───content
    └───extensions

Accédez au dossier des extensions et créez un 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é, créez la configuration du modèle.

Créer la configuration du modèle

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

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

Tout d’abord, créez un sous-dossier nommé .template.config, puis entrez-le. Ensuite, créez un fichier nommé template.json. Votre structure de dossiers doit ressembler à ceci :

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

Ouvrez le template.json avec votre éditeur de texte favori et collez-le dans 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 tags/type valeur définie sur item. Cela catégorise votre modèle en tant que 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 pour permettre aux utilisateurs de filtrer facilement le type de gabarit qu'ils recherchent.

L’élément classifications représente la colonne de balises que vous voyez lorsque vous exécutez dotnet new et obtenez une liste de modèles. Les utilisateurs peuvent également effectuer des recherches basées sur des étiquettes de classification. Ne confondez pas la tags propriété dans le fichier template.json avec la classifications liste des balises. Il s’agit de 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 symbols partie 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, il existe un paramètre 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 - Description du paramètre, qui est affichée dans l'aide du gabarit.
  • datatype - 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 de modèle par la valeur du paramètre.
  • fileRename - Similaire à replaces, cela spécifie une valeur de texte qui est remplacée dans les noms de tous les fichiers de modèle par la valeur du paramètre.
  • defaultValue - 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 ClassName paramètre et cette valeur remplace toutes les occurrences de StringExtensions. Si aucune valeur n’est fournie, elle defaultValue est utilisée. Pour ce modèle, il existe deux occurrences : StringExtensionsle fichier StringExtensions.cs et la classe StringExtensions. Étant donné que le defaultValue paramètre est StringExtensions, le nom de fichier et le nom de 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 en MyExts.

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

dotnet new stringext -?

Ce qui produit 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 disposez d’un fichier .template.config/template.json valide, votre modèle est prêt à être installé. Dans votre terminal, accédez au dossier des extensions et exécutez la commande suivante pour installer le modèle situé dans le dossier actif :

  • Sur Windows : dotnet new install .\
  • Sur 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 installé un modèle d’élément, testez-le.

  1. Accédez au dossier de test .

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

    dotnet new console

    Vous obtenez une sortie similaire à 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 de Program.cs pour inverser la "Hello, World!" chaîne avec la méthode d’extension fournie par le modèle.

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

    Réexécutez 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 tutoriels, désinstallez le modèle que vous avez créé. Veillez également à supprimer tous les fichiers et dossiers du dossier de test . Cela vous permet de revenir à un état propre prêt pour la prochaine partie de cette série de tutoriels.

Désinstaller le modèle

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

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

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

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

À tout moment, vous pouvez utiliser dotnet new uninstall pour afficher la liste des packages de modèles installés, y compris pour chaque package de modèle, la commande à 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

  • Last updated on