modèles .NET pour les auteurs

En tant qu’auteur de modèle, vous créez des modèles .NET : blueprints qui génèrent des projets, des fichiers ou d’autres ressources à partir d’une structure prédéfinie. Lorsque les utilisateurs s’exécutentdotnet new <shortName>, le moteur de modèle .NET lit le modèle et produit la sortie dans le répertoire actif. Visual Studio boîte de dialogue Créer un projet utilise également le moteur de modèle .NET pour .NET modèles de projet. Les modèles que vous créez pour l'interface CLI fonctionnent également dans Visual Studio.

Le sdk .NET est fourni avec des modèles intégrés pour des points de départ courants tels que les applications console, les bibliothèques de classes et les projets ASP.NET. Au-delà de ces modèles intégrés, vous pouvez créer vos propres modèles et les distribuer en tant que packages NuGet.

Cet article est une référence pour les auteurs de modèles. Il décrit la façon dont les modèles sont structurés, configurés et distribués. Pour obtenir des instructions pas à pas pour créer et empaqueter des modèles, consultez la section Contenu associé .

Types de modèles

Le moteur de modèle .NET prend en charge trois types de modèles : modèles d’élément, modèles de projet et modèles de solution.

  • Les modèles d’élément génèrent un ou plusieurs fichiers, tels qu’un fichier de code, un fichier de configuration ou une autre ressource, sans générer un projet entier autour d’eux. Par exemple, un modèle d’élément peut produire un fichier de classe qui ajoute un ensemble de méthodes d’extension ou un fichier de configuration JSON qui suit une disposition standard utilisée par votre équipe. Pour savoir comment créer un modèle d’élément, consultez Tutoriel : Créer un modèle d’élément.

  • Project modèles génèrent une structure de project complète. Le modèle de projet de console intégré, par exemple, produit un .csproj fichier, un Program.cs fichier et tous les autres fichiers qui composent le projet. Créez un modèle de projet lorsque vous souhaitez donner aux utilisateurs un point de départ de projet complet plutôt que des fichiers individuels. Pour savoir comment créer un modèle de projet, consultez Tutoriel : Créer un modèle de projet.

  • Les modèles de solution génèrent une solution avec un ou plusieurs projets. Par exemple, un modèle de solution peut créer un projet d’API associé à un projet de test en une seule étape.

Lorsque vous créez votre propre modèle, vous déclarez son type à l’aide du tags.type champ dans le template.json fichier de configuration. Les valeurs valides sont "project", "item"et "solution". Ces valeurs permettent aux utilisateurs de filtrer les résultats lorsqu’ils recherchent des modèles avec dotnet new search ou dotnet new list.

Tip

Project et les modèles de solution apparaissent dans la boîte de dialogue Visual Studio Créer un nouvel project, mais les modèles d'élément n'apparaissent pas dans la boîte de dialogue Ajouter>un nouvel élément. Les utilisateurs peuvent accéder aux modèles d’éléments à partir de l’interface dotnet new CLI.

Structure du modèle

Un modèle est un dossier sur le disque qui contient deux éléments : les fichiers sources du modèle et un sous-dossier spécial .template.config . Lorsqu’un utilisateur s’exécute dotnet new <shortName>, le moteur de modèle copie les fichiers sources à l’emplacement de sortie et applique toute configuration que vous avez définie pour le modèle.

mytemplate/
├── console.cs
├── readme.txt
└── .template.config/
    ├── template.json
    └── icon.png

Les fichiers sources peuvent être n’importe quel type de fichier. Le moteur de modèle ne vous oblige pas à injecter des jetons spéciaux ou des marqueurs dans le code source. Il utilise les fichiers as-is, ce qui signifie que vous pouvez générer, exécuter et déboguer le projet source d'un modèle exactement comme un projet de .NET normal. Pour transformer un projet existant en modèle, ajoutez un .template.config/template.json fichier à la racine du projet.

Vous pouvez éventuellement injecter des jetons de substitution liés à des paramètres de modèle (symboles) directement dans des fichiers sources de modèle et des noms de fichiers. Si les jetons ne sont pas du code source valide, vous ne pouvez pas générer, exécuter ou déboguer le projet source avant de le déployer en tant que modèle. Les jetons n’affectent pas les projets que les utilisateurs créent à partir du modèle déployé, car le moteur de modèle les remplace lors de la création du projet.

Le seul fichier requis à l’intérieur .template.config est template.json. Ce fichier indique au moteur de modèle tout ce dont il a besoin : le nom du modèle, le nom court, l’auteur, les classifications et tous les paramètres que les utilisateurs peuvent passer lorsqu’ils créent à partir du modèle. Vous pouvez également placer un icon.png fichier dans le .template.config dossier. Le terminal n'affiche pas d'icônes, mais Visual Studio affiche l'icône en regard du modèle dans la boîte de dialogue Créer un projet. Un PNG 128×128 fonctionne bien.

Fichier template.json

Le template.json fichier est le seul élément de configuration requis dans un modèle. Il réside dans le .template.config dossier et indique au moteur de modèle comment présenter et traiter votre modèle. Le tableau suivant décrit les champs obligatoires et facultatifs courants :

Champ Type Obligatoire Description
$schema URI Non Schéma JSON pour template.json. Définissez cette option pour https://json.schemastore.org/template activer IntelliSense dans les éditeurs comme Visual Studio Code.
author string Non Auteur du modèle.
classifications array(string) Non Les utilisateurs peuvent utiliser pour rechercher le modèle avec dotnet new search ou dotnet new list. Ces valeurs apparaissent dans la colonne Balises de la liste de modèles.
description string Non Description de ce que le modèle crée.
identity string Oui Identificateur unique pour le modèle.
name string Oui Nom complet du modèle affiché aux utilisateurs.
shortName string Oui Les utilisateurs de nom court passent à créer à dotnet new partir du modèle, par console exemple ou classlib.
sourceName string Non Chaîne dans vos fichiers sources et noms de fichiers que le moteur de modèle remplace par le nom fourni par l’utilisateur via -n ou --name. Si l’utilisateur ne fournit pas de nom, le moteur utilise le nom du répertoire actif.
preferNameDirectory booléen Non Quand true et l’utilisateur fournit un nom, mais aucun répertoire de sortie, le moteur de modèle crée un répertoire avec ce nom au lieu d’écrire des fichiers dans le répertoire actif. La valeur par défaut est false.
tags object Non Métadonnées qui identifient les propriétés telles que le langage et le type du modèle. Utiliser tags.language pour la langue et tags.type pour project, itemou solution.

Deux champs méritent une attention supplémentaire. Le sourceName champ est la façon dont les modèles gèrent le nommage : définissez-le sur une chaîne qui apparaît dans vos noms de fichiers et code source (par exemple MyTemplate), et le moteur de modèle remplace chaque occurrence par le nom que l’utilisateur passe lors de la création du modèle. Le champ contrôle la classifications détectabilité ; choisissez des balises qui décrivent avec précision l’objectif de votre modèle afin que les utilisateurs puissent le trouver lors de la recherche.

Voici un minimum template.json pour un modèle de console :

{
  "$schema": "https://json.schemastore.org/template",
  "author": "Your Name",
  "classifications": [ "Common", "Console" ],
  "description": "Creates a console application.",
  "identity": "MyCompany.ConsoleTemplate.CSharp",
  "name": "My Console App",
  "shortName": "myconsole",
  "sourceName": "MyConsoleApp",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

Le schéma complet est disponible dans le magasin de schémas JSON. Pour obtenir des options de configuration avancées telles que l’inclusion de fichiers conditionnels, les actions de post-création et les modèles multi-projets, consultez le wiki dotnet/templating GitHub.

Paramètres de modèle (symboles)

La symbols section dans template.json définit les paramètres que les utilisateurs peuvent passer lors de la création à partir de votre modèle. Chaque symbole devient une option CLI sur dotnet new <shortName>, de sorte qu’un symbole nommé ClassName devient --ClassName (ou -C si vous définissez un nom court).

Chaque entrée de symbole prend en charge les paramètres courants suivants :

Setting Description
type Doit être "parameter" destiné aux paramètres accessibles par l’utilisateur.
description Illustré dans la sortie de l’aide du modèle lorsque les utilisateurs s’exécutent dotnet new <shortName> -?.
datatype Type de données attendu, tel que "text", "bool"ou "choice".
replaces Chaîne dans le contenu de votre fichier source que le moteur de modèle remplace par la valeur du paramètre.
fileRename Chaîne dans les noms de fichiers sources que le moteur de modèle remplace par la valeur du paramètre.
defaultValue Valeur utilisée lorsque l’utilisateur ne fournit pas le paramètre.

Les replaces paramètres et fileRename les paramètres sont la façon dont les symboles remplacent le lecteur. Lorsqu’un utilisateur fournit une valeur, le moteur de modèle remplace chaque occurrence de la chaîne à l’intérieur replaces du contenu du fichier et chaque occurrence de la chaîne dans les fileRename noms de fichiers. Si l’utilisateur ne fournit pas de valeur, il est utilisé à la defaultValue place.

Par exemple, le symbole suivant permet aux utilisateurs de définir le nom de classe lorsqu’ils créent à partir du modèle. Le fichier est renommé et la classe à l’intérieur de celle-ci est mise à jour pour correspondre :

"symbols": {
  "ClassName": {
    "type": "parameter",
    "description": "The name of the code file and class.",
    "datatype": "text",
    "replaces": "StringExtensions",
    "fileRename": "StringExtensions",
    "defaultValue": "StringExtensions"
  }
}

Avec ce symbole défini, un utilisateur peut s’exécuter dotnet new <shortName> --ClassName MyHelpers pour produire un fichier nommé MyHelpers.cs contenant une classe nommée MyHelpers. Sans l’indicateur, le fichier et la classe conservent le nom StringExtensionspar défaut.

Pour vérifier les paramètres exposés -? par votre modèle, passez son nom court après l’avoir installé :

dotnet new <shortName> -?

Packages de modèles

Un package de modèle est un fichier NuGet (.nupkg) qui regroupe un ou plusieurs de vos modèles. Lorsqu’un utilisateur installe votre package de modèle, le moteur de modèle .NET inscrit chaque modèle à la fois. Les packages sont la méthode standard pour distribuer des modèles. Publiez un package unique pour NuGet.org ou un flux NuGet privé, ou partagez un fichier local .nupkg , et les utilisateurs obtiennent l’ensemble de la collection avec une seule commande.

Pour générer un package de modèle, utilisez un fichier projet C# (.csproj) configuré pour agir comme un projet d’empaquetage plutôt qu’un projet de compilation. Les paramètres clés qui rendent ce travail sont les suivants :

Setting Valeur Purpose
PackageType Template Marque le package en tant que package de modèle afin qu’il apparaisse dans les dotnet new search résultats.
IncludeContentInPack true Inclut des fichiers de contenu dans le package NuGet.
IncludeBuildOutput false Empêche l’ajout de fichiers binaires compilés au package.
ContentTargetFolders content Place vos dossiers de modèle dans le content dossier du package NuGet, qui est l’emplacement où le moteur de modèle s’attend à les trouver.

Le templatepack modèle de projet offre le moyen le plus simple de créer un projet d’empaquetage :

  1. Installez le Microsoft. Package NuGet TemplateEngine.Authoring.Templates :

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Créez le projet d’empaquetage :

    dotnet new templatepack -n <PackageName>

Le projet généré inclut les paramètres corrects .csproj , un content dossier pour vos modèles et les tâches MSBuild pour la validation de modèle et la localisation facultative.

Pour obtenir une procédure pas à pas complète de la création, de l’empaquetage et de la publication d’un package de modèle, consultez Tutoriel : Créer un package de modèle.

Tester votre modèle localement

Pendant le développement de modèles, installez votre modèle directement à partir de son dossier pour le tester sans générer d’abord de package. Transmettez le chemin d’accès au répertoire qui contient le .template.config dossier :

dotnet new install ./mytemplate/

Pour afficher tous les packages de modèles installés et la commande exacte à désinstaller, exécutez dotnet new uninstall sans argument :

dotnet new uninstall

Pour désinstaller un modèle installé à partir d’un répertoire, passez le même chemin d’accès de répertoire que celui que vous avez utilisé pour l’installer :

dotnet new uninstall ./mytemplate/

Une fois que vous êtes prêt à partager votre modèle, empaquetez-le en tant que package NuGet (voir Packages de modèles) et distribuez-le. Les utilisateurs installent votre modèle publié avec dotnet new install et l’un des arguments sources suivants :

  • ID de package NuGet, qui installe la dernière version stable à partir des sources NuGet configurées pour le répertoire actif :

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • ID de package NuGet avec une URL de flux personnalisée. L’option --nuget-source utilise le flux spécifié, en plus des sources NuGet configurées, pour cette installation uniquement :

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp --nuget-source https://mynugetfeed.example.com/v3/index.json

  • Chemin d’accès à un fichier local .nupkg :

    dotnet new install ./AdatumCorporation.ConsoleTemplate.CSharp.1.0.0.nupkg

Warning

Les modèles peuvent exécuter des tâches MSBuild et du code arbitraire pendant la création du projet. Installez uniquement des modèles à partir de sources approuvées.

Pour désinstaller un package installé à partir d’une source NuGet ou d’un fichier local .nupkg , utilisez l’ID de package NuGet :

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

Les modèles sdk intégrés n’apparaissent pas dans la liste des désinstallations et ne peuvent pas être supprimés avec dotnet new uninstall.

Localisation de modèle

Le moteur de modèle .NET prend en charge la localisation facultative des métadonnées de modèle. Lorsque vous fournissez des fichiers de localisation, les hôtes tels que dotnet new et la boîte de dialogue Visual Studio Nouvelle Project affichent le nom, la description et les informations de symbole du modèle dans la langue de l'utilisateur au lieu de la langue créée d'origine.

Les champs de modèle suivants prennent en charge la localisation :

  • name
  • author
  • description
  • Symbole description et displayName
  • Description et nom d’affichage pour chaque choix dans un paramètre de choix
  • Publier l’action description et manualInstructions

Pour ajouter la localisation, créez un localize sous-dossier à l’intérieur .template.config et ajoutez un fichier JSON par langue. Nommez chaque fichiertemplatestrings.<lang-code>.json, où <lang-code> correspond un nom valideCultureInfo, tel que pt-BR, ou .dezh-Hans Chaque fichier contient des paires clé-valeur dans lesquelles la clé est un chemin d’accès à l’élément template.json, à l’aide / d’un délimiteur pour les champs imbriqués.

Par exemple, avec template.json le contenu suivant :

{
  "$schema": "https://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."
    }
  }
}

Un fichier de localisation portugais brésilien nommé templatestrings.pt-BR.json ressemblerait à ceci :

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

Le moteur de modèle analyse ces fichiers lorsqu’il charge des informations de modèle et retourne automatiquement des valeurs localisées en fonction de la culture actuelle de l’interface utilisateur. Aucune étape supplémentaire n’est nécessaire de la part de l’utilisateur.

La localisation est facultative. Si vous n’incluez pas de fichiers de localisation, le modèle fonctionne normalement et affiche toujours les valeurs à partir de template.json. Pour plus d’informations, consultez la page de localisation wiki dotnet/templating.

Intégration de Visual Studio

Visual Studio la boîte de dialogue Créer un projet utilise le moteur de modèle .NET pour .NET modèles de projet. Les modèles que vous créez pour dotnet new travailler dans Visual Studio également, sans aucune configuration supplémentaire. Lorsqu’un utilisateur installe votre package de modèle avec dotnet new install, Visual Studio détecte et affiche automatiquement ces modèles dans la boîte de dialogue.

Project et les modèles de solution s’affichent dans la boîte de dialogue Créer une nouvelle project en même temps que les modèles sdk intégrés. Les utilisateurs peuvent trouver des modèles par nom, langue ou balises à partir du classifications champ dans le fichier du template.json modèle. Les classifications précises aident votre modèle à s’afficher dans les catégories de filtre appropriées, donc choisissez-les soigneusement. Pour donner à votre modèle une apparence polie dans la boîte de dialogue, ajoutez un icon.png dossier .template.config , Visual Studio l'affiche en regard du nom de votre modèle.

Les modèles d’élément n’apparaissent pas actuellement dans la boîte de dialogue Ajouter un>nouvel élément . Les utilisateurs peuvent toujours utiliser des modèles d’élément avec la dotnet new commande dans le terminal.

Pour rendre votre modèle détectable pour Visual Studio utilisateurs qui ne l'ont pas encore installé, publiez votre package de modèle sur nuget.org. La boîte de dialogue Créer un projet inclut un plus grand nombre de modèles à partir de l’option de recherche en ligne qui recherche nuget.org pour les packages de modèles. Lorsqu’un utilisateur installe votre package via cette option, Visual Studio utilise le même mécanisme d’installation que dotnet new install.

Pour obtenir des conseils plus approfondis sur l'intégration spécifique à Visual Studio, telles que le contrôle de l'ordre de tri du modèle et la configuration d'options supplémentaires spécifiques à l'IDE, consultez le référentiel template-sample de Sayed Hashimi.

Contenu connexe

  • Last updated on