Modèles personnalisés pour dotnet new

Article
08/18/2023

Le SDK .NET est fourni avec de nombreux modèles déjà installés et prêts à l’emploi. La commande dotnet new n’est pas simplement une façon d’utiliser un modèle, mais montre aussi comment installer et désinstaller des modèles. Vous pouvez créer vos propres modèles personnalisés pour tout type de projet, tel qu’une application, un service, un outil ou une bibliothèque de classes. Vous pouvez même créer un modèle qui génère un ou plusieurs fichiers indépendants, comme un fichier de configuration.

Vous pouvez installer des modèles personnalisés à partir d’un package NuGet sur tout flux NuGet, en référençant un fichier nupkg NuGet directement ou en spécifiant un répertoire de système de fichiers qui contient le modèle. Le moteur de modèle offre des fonctionnalités qui vous permettent de remplacer des valeurs, d’inclure et d’exclure des fichiers, ainsi que d’exécuter des opérations de traitement personnalisées quand votre modèle est utilisé.

Le moteur de modèle est open source et le dépôt de code en ligne se trouve à l’adresse dotnet/templating sur GitHub. Vous trouverez d’autres modèles, y compris des modèles de tiers, à l’aide de dotnet new search. Pour plus d’informations sur la création et l’utilisation de modèles personnalisés, consultez Guide pratique pour créer vos propres modèles pour dotnet new et le Wiki du dépôt GitHub dotnet/templating GitHub.

Notes

Les exemples de modèles sont disponibles dans le dotnet/templating référentiel GitHub.

Pour suivre une procédure pas à pas et créer un modèle, consultez le didacticiel Créer un modèle personnalisé pour dotnet new.

Modèles par défaut .NET

Quand vous installez le SDK .NET, vous obtenez plus d’une dizaine de modèles intégrés pour la création de projets et de fichiers, notamment des applications de console, des bibliothèques de classes, des projets de test unitaire, des applications ASP.NET Core (dont les projets Angular et React) et des fichiers de configuration. Pour répertorier les modèles intégrés, exécutez la commande dotnet new list :

dotnet new list

Configuration

Un modèle est constitué des éléments suivants :

Dossiers et fichiers sources.
Un fichier de configuration (template.json).

Dossiers et fichiers sources

Les dossiers et fichiers sources incluent tous les fichiers et dossiers que le modèle doit utiliser quand la commande dotnet new <TEMPLATE> est exécutée. Le moteur de modèle est conçu pour utiliser des projets exécutables comme code source pour générer des projets. Cela a plusieurs avantages :

Vous n’avez pas besoin d’injecter des jetons spéciaux dans le code source de votre projet.
Les fichiers de code ne sont pas des fichiers spéciaux ou des fichiers modifiés de quelque manière pour fonctionner avec le moteur de modèle. Ainsi, les outils que vous utilisez normalement avec des projets fonctionnent également avec le contenu du modèle.
Vous générez, exécutez et déboguez vos projets de modèle comme vous le feriez pour tout autre projet.
Vous pouvez rapidement créer un modèle à partir d’un projet existant en ajoutant simplement un fichier de configuration ./.template.config/template.json au projet.

Les fichiers et dossiers stockés dans le modèle ne sont pas limités aux types de projet .NET formels. Les dossiers et fichiers sources peuvent comporter tout contenu que vous souhaitez créer quand vous utilisez le modèle, même si le moteur de modèle produit un seul fichier en guise de sortie.

Les fichiers générés par le modèle peuvent être modifiés en fonction de la logique et des paramètres que vous avez fournis dans le fichier de configuration template.json. L’utilisateur peut remplacer ces paramètres en passant des options à la commande dotnet new <TEMPLATE>. Un exemple courant de logique personnalisée est la fourniture d’un nom pour une classe ou une variable dans le fichier de code qui est déployé par un modèle.

template.json

Le fichier template.json est placé dans un dossier .template.config dans le répertoire racine du modèle. Le fichier fournit des informations de configuration au moteur de modèle. La configuration minimale requiert les membres affichés dans le tableau suivant, qui suffisent pour créer un modèle fonctionnel.

Membre	Type	Description
`$schema`	URI	Schéma JSON pour le fichier template.json. Les éditeurs qui prennent en charge les schémas JSON activent les fonctionnalités d’édition JSON quand le schéma est spécifié. Par exemple, Visual Studio Code exige ce membre pour activer IntelliSense. Utilisez la valeur de `http://json.schemastore.org/template`.
`author`	string	Auteur du modèle.
`classifications`	tableau(chaîne)	Zéro ou plusieurs caractéristiques du modèle qu’un utilisateur peut utiliser pour rechercher le modèle. Les classifications apparaissent également dans la colonne Balises quand il apparaît dans une liste de modèles produite à l’aide de la commande `dotnet new list`.
`identity`	string	Nom unique pour ce modèle.
`name`	string	Nom de modèle que les utilisateurs doivent voir.
`shortName`	string	Nom de raccourci par défaut pour sélectionner le modèle qui s’applique aux environnements où le nom du modèle est spécifié par l’utilisateur (non sélectionné par le biais d’une interface graphique utilisateur). Par exemple, le nom court est utile si les modèles sont utilisés à partir d’une invite de commandes avec des commandes CLI.
`sourceName`	string	Nom dans l’arborescence source à remplacer par le nom spécifié par l’utilisateur. Le moteur de modèle recherche toute occurrence de `sourceName` mentionnée dans le fichier de configuration et la remplace dans les noms de fichiers et le contenu des fichiers. La valeur à remplacer peut être donnée à l’aide des options `-n` ou `--name` options lors de l’exécution d’un modèle. Si aucun nom n’est spécifié, le répertoire actif est utilisé.
`preferNameDirectory`	Boolean	Indique s’il faut créer un répertoire pour le modèle si le nom est spécifié, mais qu’un répertoire de sortie n’est pas défini (au lieu de créer le contenu directement dans le répertoire actif). La valeur par défaut est false.

Le schéma complet pour le fichier template.json se trouve dans le magasin de schémas JSON. Pour plus d’informations sur le fichier template.json, consultez le Wiki de création de modèles dotnet. Pour obtenir des exemples et des informations plus approfondis sur la façon de rendre vos modèles visibles dans Visual Studio, consultez les ressources créées par Sayed Hashimi.

Exemple

Par exemple, voici un dossier de modèle qui contient deux fichiers de contenu : console.cs et readme.txt. Notez la présence du dossier requis nommé .template.config, qui contient le fichier template.json.

└───mytemplate
    │   console.cs
    │   readme.txt
    │
    └───.template.config
            template.json

Le fichier template.json ressemble à ceci :

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Travis Chau",
  "classifications": [ "Common", "Console" ],
  "identity": "AdatumCorporation.ConsoleTemplate.CSharp",
  "name": "Adatum Corporation Console Application",
  "shortName": "adatumconsole"
}

Le dossier mytemplate est un package de modèle installable. Une fois le package installé, shortName peut être utilisé avec la commande dotnet new. Par exemple, dotnet new adatumconsole devrait produire les fichiers console.cs et readme.txt dans le dossier actuel.

Localisation de modèle

Les modèles .NET sont localisables. Si un modèle est localisé pour la langue correspondant aux paramètres régionaux actuels, ses éléments apparaissent dans la même langue que l’interface CLI. La localisation est facultative lors de la création de modèles.

Les éléments localisables sur un modèle sont les suivants :

Nom
Auteur
Description
Symboles
- Description
- Nom d’affichage
- Descriptions et nom d’affichage des choix pour les paramètres de choix
Actions en lien avec la publication
- Description
- Instructions manuelles

Les fichiers de localisation ont un format JSON et un seul fichier par culture doit exister. La convention d’affectation de noms est la suivante : templatestrings.<lang code>.json, où lang code correspond à l’une des options CultureInfo. Tous les fichiers de localisation doivent se trouver dans le dossier .template-config\localize.

Le JSON de localisation se compose de paires clé-valeur :

La clé est la référence à un élément de template.json à localiser. Si l’élément est un enfant, utilisez le chemin d’accès complet avec un délimiteur /.
La valeur est la chaîne de localisation de l’élément donné par la clé.

Pour plus d’informations sur la localisation des modèles, consultez la page de localisation du wiki sur les modèles dotnet.

Exemple

Par exemple, voici le fichier template.json avec certains champs localisables :

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Microsoft",
  "classifications": "Config",
  "name": "EditorConfig file",
  "description": "Creates an .editorconfig file for configuring code style preferences.",
  "symbols": {
    "Empty": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "displayName": "Empty",
      "description": "Creates empty .editorconfig instead of the defaults for .NET."
    }
  }
}

Et certains champs doivent être localisés vers le portugais brésilien. Le nom de fichier doit être templatestrings.pt-BR.json pour correspondre à la culture, et il se présente comme suit :

{
  "author": "Microsoft",
  "name": "Arquivo EditorConfig",
  "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.",
  "symbols/Empty/displayName": "Vazio",
  "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET."
}

Empaqueter un modèle dans un package NuGet (fichier nupkg)

Un modèle personnalisé est empaqueté avec la commande dotnet pack et un fichier .csproj. Vous pouvez également utiliser NuGet avec la commande nuget pack et un fichier .nuspec. Toutefois, NuGet nécessite .NET Framework sur Windows et Mono sur Linux et macOS.

Le fichier .csproj est légèrement différent d’un fichier de projet de code .csproj traditionnel. Notez les points suivants :

Le paramètre <PackageType> est ajouté et défini sur Template.
Le paramètre <PackageVersion> est ajouté et défini sur un numéro de version de NuGet valide.
Le paramètre <PackageId> est ajouté et la valeur est définie sur un identificateur unique. Cet identificateur est utilisé pour désinstaller le pack de modèle et est utilisé par les flux NuGet pour inscrire votre pack de modèle.
Les paramètres de métadonnées génériques doivent être définis : <Title>, <Authors>, <Description> et <PackageTags>.
Le paramètre <TargetFramework> doit être défini, même si le fichier binaire généré par le processus de modèle n’est pas utilisé. Dans l’exemple ci-dessous, il est défini sur netstandard2.0.

Un package de modèle, sous la forme d’un package NuGet .nupkg, requiert que tous les modèles soient stockés dans le dossier content du package. Il existe quelques paramètres supplémentaires à ajouter à un fichier .csproj pour vous assurer que le .nupkg généré peut être installé en tant que pack de modèle :

Le paramètre <IncludeContentInPack> est défini sur true pour inclure n’importe quel fichier que le projet définit comme contenu dans le package NuGet.
Le paramètre <IncludeBuildOutput> est défini sur false pour exclure tous les fichiers binaires générés par le compilateur à partir du package NuGet.
Le paramètre <ContentTargetFolders> est défini sur content. Cela permet de s’assurer que les fichiers définis comme contenu sont stockés dans le dossier content du package NuGet. Ce dossier dans le package NuGet est analysé par le système de modèle dotnet.

Un moyen simple d’empêcher tous les fichiers de code d’être compilés par votre projet de modèle est d’utiliser l’élément <Compile Remove="**\*" /> dans votre fichier projet, dans un élément <ItemGroup>.

Un moyen simple de structurer votre pack de modèle consiste à placer tous les modèles dans des dossiers individuels, puis chaque dossier de modèle à l’intérieur d’un dossier templates qui se trouve dans le même répertoire que votre fichier .csproj. De cette façon, vous pouvez utiliser un élément de projet unique pour inclure tous les fichiers et dossiers dans les modèles en tant que contenu. À l’intérieur d’un élément <ItemGroup>, créez un élément <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" />.

Voici un exemple de fichier .csproj respectant toutes ces instructions. Il compresse le dossier enfant templates dans le dossier de package content et exclut tout fichier de code en cours de compilation.

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

  <PropertyGroup>
    <PackageType>Template</PackageType>
    <PackageVersion>1.0</PackageVersion>
    <PackageId>AdatumCorporation.Utility.Templates</PackageId>
    <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>
    <TargetFramework>netstandard2.0</TargetFramework>

    <IncludeContentInPack>true</IncludeContentInPack>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <ContentTargetFolders>content</ContentTargetFolders>
  </PropertyGroup>

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

</Project>

L’exemple suivant illustre la structure de fichiers et de dossiers lors de l’utilisation d’un .csproj pour créer un package de modèle. Le fichier MyDotnetTemplates.csproj et le dossier templates se trouvent à la racine d’un répertoire nommé project_folder. Le dossier templates contient deux modèles, mytemplate1 et mytemplate2. Chaque modèle a des fichiers de contenu et un dossier .template.config avec un fichier de configuration template.json.

project_folder
│   MyDotnetTemplates.csproj
│
└───templates
    ├───mytemplate1
    │   │   console.cs
    │   │   readme.txt
    │   │
    │   └───.template.config
    │           template.json
    │
    └───mytemplate2
        │   otherfile.cs
        │
        └───.template.config
                template.json

Notes

Pour vous assurer que le package de modèle apparaît dans le résultat dotnet new search, définissez le type de package NuGet sur Template.

Installer un package de modèle

Utilisez la commande dotnet new install pour installer un package de modèle.

Pour installer un package de modèle à partir d’un package NuGet stocké à la page nuget.org

Utilisez l’identificateur de package NuGet pour installer un package de modèle.

dotnet new install <NUGET_PACKAGE_ID>

Pour installer un package de modèle à partir d’une source NuGet personnalisée

Fournissez une source NuGet personnalisée (par exemple, https://api.my-custom-nuget.com/v3/index.json).

dotnet new --install <NUGET_PACKAGE_ID> --nuget-source <SOURCE>

Pour installer un package de modèle à partir d’un fichier nupkg local

Fournissez le chemin d’accès à un fichier de package NuGet .nupkg.

dotnet new install <PATH_TO_NUPKG_FILE>

Pour installer un package de modèle à partir d’un répertoire de système de fichiers

Les modèles peuvent être installés à partir d’un dossier de modèles, comme le dossier mytemplate1 dans l’exemple ci-dessus. Spécifiez le chemin du dossier .template.config. Le chemin d’accès au répertoire du modèle n’a pas besoin d’être absolu.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Obtenir la liste des packages de modèles installés

La commande de désinstallation, sans autres paramètres, répertorie tous les packages de modèles installés et les modèles inclus.

dotnet new uninstall

Cette commande renvoie quelque chose de similaire à la sortie suivante :

Currently installed items:
   Microsoft.Azure.WebJobs.ProjectTemplates
      Version: 4.0.1942
      Details:
         Author: Microsoft
         NuGetSource: https://api.nuget.org/v3/index.json
      Templates:
         Azure Functions (func) C#
         Azure Functions (func) F#
      Uninstall Command:
         dotnet new uninstall Microsoft.Azure.WebJobs.ProjectTemplates
...

Le premier niveau d’éléments après Currently installed items: est composé des identificateurs utilisés dans la désinstallation d’un package de modèle. Dans l’exemple précédent, Microsoft.Azure.WebJobs.ProjectTemplates est répertorié. Si le package du modèle a été installé à l’aide d’un chemin d’accès du système de fichiers, cet identificateur est le chemin du dossier .template.config. Seuls les packages de modèles installés via dotnet new install sont affichés dans la liste. Les packages de modèles intégrés au SDK .NET ne sont pas affichés.

Désinstaller un package de modèle

Utilisez la commande dotnet new uninstall pour désinstaller un package de modèle.

Si le package a été installé par un flux NuGet ou par un fichier .nupkg directement, fournissez l’identificateur.

dotnet new uninstall <NUGET_PACKAGE_ID>

Si le package a été installé en spécifiant un chemin d’accès au dossier .template.config, utilisez ce chemin pour désinstaller le package. Vous pouvez voir le chemin d’accès absolu du package de modèle dans la sortie fournie par la commande dotnet new uninstall. Pour plus d’informations, consultez la section Obtenir la liste des modèles installés.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Créer un projet à l’aide d’un modèle personnalisé

Une fois un modèle installé, utilisez-le en exécutant la commande dotnet new <TEMPLATE> comme vous le feriez avec tout autre modèle préinstallé. Vous pouvez également spécifier des options dans la commande dotnet new, notamment des options de modèle que vous avez configurées dans les paramètres de modèle. Indiquez le nom court du modèle directement dans la commande :

dotnet new <TEMPLATE>

Modèles personnalisés pour dotnet new

Modèles par défaut .NET

Configuration

Dossiers et fichiers sources

template.json

Exemple

Localisation de modèle

Exemple

Empaqueter un modèle dans un package NuGet (fichier nupkg)

Installer un package de modèle

Pour installer un package de modèle à partir d’un package NuGet stocké à la page nuget.org

Pour installer un package de modèle à partir d’une source NuGet personnalisée

Pour installer un package de modèle à partir d’un fichier nupkg local

Pour installer un package de modèle à partir d’un répertoire de système de fichiers

Obtenir la liste des packages de modèles installés

Désinstaller un package de modèle

Créer un projet à l’aide d’un modèle personnalisé

Voir aussi

Commentaires

Ressources supplémentaires