Partager via

Modèles personnalisés pour dotnet new

Le Kit de développement logiciel (SDK) .NET est fourni avec de nombreux modèles déjà installés et prêts à être utilisés. La dotnet new commande n’est pas seulement la façon d’utiliser un modèle, mais également comment installer et désinstaller des modèles. Vous pouvez créer vos propres modèles personnalisés pour n’importe quel 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, tels qu’un fichier de configuration.

Vous pouvez installer des modèles personnalisés à partir d’un package NuGet sur n’importe quel flux NuGet, en référençant directement un fichier NuGet .nupkg 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, et d’exécuter des opérations de traitement personnalisées lorsque votre modèle est utilisé.

Le moteur de modèle est open source et le référentiel de code en ligne se trouve à dotnet/templating sur GitHub. D’autres modèles, y compris des modèles provenant de tiers, sont disponibles à l’aide de dotnet new search. Pour plus d’informations sur la création et l’utilisation de modèles personnalisés, consultez Comment créer vos propres modèles pour dotnet new et dotnet/templating GitHub Wiki.

Remarque

Les exemples de modèles sont disponibles dans le dépôt GitHub dotnet/templating .

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

Modèles par défaut .NET

Quand vous installez le SDK .NET Core, vous obtenez plus d’une dizaine de modèles intégrés pour créer des projets et des 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

Paramétrage

Un modèle est composé des parties suivantes :

  • Fichiers et dossiers sources.
  • Fichier de configuration (template.json).

Fichiers et dossiers sources

Les fichiers et dossiers sources incluent les fichiers et dossiers que vous souhaitez que le moteur de modèle utilise lors de l’exécution de la dotnet new <TEMPLATE> commande. Le moteur de modèle est conçu pour utiliser des projets exécutables en tant que code source pour produire des projets. Cela a plusieurs avantages :

  • Le moteur de modèle ne vous oblige pas à injecter des jetons spéciaux dans le code source de votre projet.
  • Les fichiers de code ne sont pas des fichiers spéciaux ni modifiés d’une manière quelconque pour fonctionner avec le moteur de modèle. Par conséquent, les outils que vous utilisez normalement lors de l’utilisation de projets fonctionnent également avec du contenu de modèle.
  • Vous générez, exécutez et déboguez vos projets de modèle comme vous le faites pour l’un de vos autres projets.
  • Vous pouvez rapidement créer un modèle à partir d’un projet existant en ajoutant 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 projets .NET formels. Les fichiers et dossiers sources peuvent être constitués de tout contenu que vous souhaitez créer lorsque le modèle est utilisé, même si le moteur de modèle produit un seul fichier comme 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 configurationtemplate.json . L’utilisateur peut remplacer ces paramètres en passant des options à la dotnet new <TEMPLATE> commande. Un exemple courant de logique personnalisée fournit un nom pour une classe ou une variable dans le fichier de code 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 nécessite les membres indiqués dans le tableau suivant, ce qui suffit pour créer un modèle fonctionnel.

Membre Catégorie Descriptif
$schema URI Schéma JSON du fichier template.json . Les éditeurs qui prennent en charge les schémas JSON activent les fonctionnalités d’édition JSON lorsque le schéma est spécifié. Par exemple, Visual Studio Code nécessite que ce membre active IntelliSense. Utilisez une valeur de http://json.schemastore.org/template.
author ficelle Auteur du modèle.
classifications array(string) Zéro ou plusieurs caractéristiques du modèle qu’un utilisateur peut utiliser pour trouver le modèle lors de sa recherche. Les classifications apparaissent également dans la colonne Balises lorsqu’elles apparaissent dans une liste de modèles produits à l’aide de la dotnet new list commande.
identity ficelle Nom unique pour ce modèle.
name ficelle Nom du modèle que les utilisateurs doivent voir.
shortName ficelle Nom abrégé 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, et non sélectionné via une interface utilisateur graphique. Par exemple, le nom court est utile lors de l’utilisation de modèles à partir d’une invite de commandes avec des commandes CLI.
sourceName ficelle Nom dans l’arborescence source à remplacer par le nom spécifié par l’utilisateur. Le moteur de modèle recherchera toute occurrence de sourceName mentionnée dans le fichier de configuration et la remplacera dans les noms et contenus des fichiers. La valeur à remplacer peut être donnée en utilisant les options -n ou --name lors de l'exécution d'un modèle. Si aucun nom n’est spécifié, le répertoire actif est utilisé.
preferNameDirectory Booléen 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 du 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. Il existe également le 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 à ce qui suit :

{
  "$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 paquet installé, shortName peut être utilisé avec la commande dotnet new. Par exemple, dotnet new adatumconsole exporterait 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
  • Descriptif
  • Symboles
    • Descriptif
    • Nom d’affichage
    • Descriptions et nom d’affichage des choix pour les paramètres de choix
  • Actions en lien avec la publication
    • Descriptif
    • 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 .template-config\localize dossier.

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 complet en utilisant 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 dotnet.

Exemple :

Par exemple, voici template.json fichier 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 templatestrings.pt-BR.json 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 emballé avec la commande dotnet pack et un fichier .csproj . Vous pouvez également utiliser NuGet avec la commande nuget pack avec un fichier .nuspec . Toutefois, NuGet nécessite le .NET Framework sur Windows et Mono sur Linux et macOS.

Le fichier .csproj est légèrement différent d’un fichier .csproj code-project traditionnel. Notez les paramètres suivants :

  1. Le <PackageType> paramètre est ajouté et défini sur Template.
  2. Le <PackageVersion> paramètre est ajouté et défini sur un numéro de version NuGet valide.
  3. Le <PackageId> paramètre est ajouté et défini sur un identificateur unique. Cet identificateur est utilisé pour désinstaller le pack de modèles et est utilisé par les flux NuGet pour inscrire votre pack de modèles.
  4. Les paramètres de métadonnées génériques doivent être définis : <Title>, , <Authors><Description>, et <PackageTags>.
  5. Le <TargetFramework> paramètre doit être défini, même si le fichier binaire produit 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 , nécessite que tous les modèles soient stockés dans le dossier de contenu du package. Il existe quelques paramètres supplémentaires à ajouter à un fichier .csproj pour vous assurer que le fichier .nupkg généré peut être installé en tant que pack de modèles :

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

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

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

Voici un exemple de fichier .csproj qui suit toutes ces instructions. Il emballe le sous-dossier modèles dans le dossier du package de contenu et exclut tout fichier code afin qu'il ne soit pas compilé.

<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 d’utilisation d’un fichier .csproj pour créer un package de modèle. Le fichier et le dossier modèlesMyDotnetTemplates.csproj se trouvent à la racine d’un répertoire nommé project_folder. Le dossier modèles contient deux modèles, mytemplate1 et mytemplate2. Chaque modèle possède 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

Remarque

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é à 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èle, tel que le dossier mytemplate1 de l’exemple précédent. 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 uninstall, sans aucun autre paramètre, répertorie tous les packages de modèles installés et les modèles inclus.

dotnet new uninstall

Cette commande retourne 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 les identificateurs utilisés lors de 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 de modèle a été installé à l’aide d’un chemin d’accès au système de fichiers, cet identificateur est le chemin du dossier .template.config . Seuls les packages de modèle installés via dotnet new install sont affichés dans la liste. Les packages de modèles intégrés au Kit de développement logiciel (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é directement par un flux NuGet ou par un fichier .nupkg , indiquez 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 absolu du package de modèle dans la sortie fournie par la dotnet new uninstall commande. 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 qu’un modèle est installé, utilisez le modèle en exécutant la dotnet new <TEMPLATE> commande comme vous le feriez avec n’importe quel autre modèle préinstallé. Vous pouvez également spécifier des options pour la dotnet new commande, notamment des options spécifiques au modèle que vous avez configurées dans les paramètres du modèle. Fournissez directement le nom court du modèle à la commande :

dotnet new <TEMPLATE>

Voir aussi