.NET sjablonen voor auteurs

Als auteur van een sjabloon maakt u .NET sjablonen: blauwdrukken waarmee projecten, bestanden of andere resources worden gegenereerd op basis van een vooraf gedefinieerde structuur. Wanneer gebruikers worden uitgevoerddotnet new <shortName>, leest de .NET sjabloonengine de sjabloon en produceert de uitvoer in de huidige map. Visual Studio het dialoogvenster Een nieuw project maken maakt ook gebruik van de .NET sjabloonengine voor .NET projectsjablonen, zodat sjablonen die u voor de CLI in Visual Studio ontwerpt, ook worden gebruikt.

De .NET SDK wordt geleverd met ingebouwde sjablonen voor algemene uitgangspunten, zoals console-apps, klassebibliotheken en ASP.NET projecten. Naast deze ingebouwde sjablonen kunt u uw eigen sjablonen ontwerpen en distribueren als NuGet-pakketten.

Dit artikel is een verwijzing voor sjabloonauteurs. Hierin wordt beschreven hoe sjablonen zijn gestructureerd, geconfigureerd en gedistribueerd. Zie de sectie Gerelateerde inhoud voor stapsgewijze instructies voor het maken en verpakken van sjablonen.

Sjabloontypen

De .NET sjabloonengine ondersteunt drie typen sjablonen: itemsjablonen, projectsjablonen en oplossingssjablonen.

  • Itemsjablonen genereren een of meer bestanden, zoals een codebestand, configuratiebestand of andere resource, zonder dat er een heel project rondom wordt gegenereerd. Een itemsjabloon kan bijvoorbeeld een klassebestand produceren dat een set extensiemethoden toevoegt of een JSON-configuratiebestand dat volgt op een standaardindeling die uw team gebruikt. Zie Zelfstudie: Een itemsjabloon maken voor meer informatie over het maken van een itemsjabloon.

  • Project sjablonen genereren een volledige project structuur. De ingebouwde consoleprojectsjabloon produceert bijvoorbeeld een .csproj bestand, een Program.cs bestand en eventuele andere bestanden waaruit het project bestaat. Maak een projectsjabloon als u gebruikers een volledig beginpunt wilt geven in plaats van afzonderlijke bestanden. Zie Zelfstudie: Een projectsjabloon maken voor meer informatie over het bouwen van een projectsjabloon.

  • Oplossingssjablonen genereren een oplossing met een of meer projecten. Een oplossingssjabloon kan bijvoorbeeld in één stap een API-project maken dat is gekoppeld aan een testproject.

Wanneer u uw eigen sjabloon maakt, declareert u het bijbehorende type met behulp van het tags.type veld in het template.json configuratiebestand. De geldige waarden zijn "project", "item"en "solution". Met deze waarden kunnen gebruikers resultaten filteren wanneer ze zoeken naar sjablonen met dotnet new search of dotnet new list.

Tip

Project en oplossingssjablonen worden weergegeven in het dialoogvenster Visual Studio Een nieuw project maken, maar itemsjablonen worden niet weergegeven in het dialoogvensterNieuw itemtoevoegen>. Gebruikers hebben toegang tot itemsjablonen vanuit de dotnet new CLI.

Sjabloonstructuur

Een sjabloon is een map op schijf die twee dingen bevat: de bronbestanden van de sjabloon en een speciale .template.config submap. Wanneer een gebruiker wordt uitgevoerd dotnet new <shortName>, kopieert de sjabloonengine de bronbestanden naar de uitvoerlocatie en past de configuratie toe die u voor de sjabloon hebt gedefinieerd.

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

De bronbestanden kunnen elk type bestand zijn. Voor de sjabloonengine hoeft u geen speciale tokens of markeringen in de broncode te injecteren. Het maakt gebruik van de bestanden as-is, wat betekent dat u het bronproject van een sjabloon precies zoals een normaal .NET project kunt bouwen, uitvoeren en er fouten in kunt opsporen. Als u een bestaand project wilt omzetten in een sjabloon, voegt u een .template.config/template.json bestand toe aan de hoofdmap van het project.

U kunt optioneel vervangingstokens injecteren die zijn gekoppeld aan sjabloonparameters (symbolen) rechtstreeks in sjabloonbronbestanden en bestandsnamen. Als de tokens geen geldige broncode zijn, kunt u het bronproject niet bouwen, uitvoeren of fouten opsporen voordat u het als sjabloon implementeert. De tokens zijn niet van invloed op projecten die gebruikers maken op basis van de geïmplementeerde sjabloon, omdat de sjabloonengine deze vervangt tijdens het maken van het project.

Het enige vereiste bestand binnen .template.config is template.json. Dit bestand vertelt de sjabloonengine alles wat nodig is: de naam van de sjabloon, de korte naam, de auteur, de classificaties en alle parameters die gebruikers kunnen doorgeven wanneer ze een sjabloon maken. U kunt ook een icon.png bestand in de .template.config map plaatsen. In de terminal worden geen pictogrammen weergegeven, maar Visual Studio het pictogram naast de sjabloon in het dialoogvenster Een nieuw project maken weergegeven. Een 128×128 PNG werkt goed.

Het template.json-bestand

Het template.json bestand is het enige vereiste onderdeel van de configuratie in een sjabloon. Het bevindt zich in de .template.config map en vertelt de sjabloonengine hoe u uw sjabloon presenteert en verwerkt. In de volgende tabel worden algemene vereiste en optionele velden beschreven:

Veld Typologie Verplicht Description
$schema URI Nee. Het JSON-schema voor template.json. Ingesteld om https://json.schemastore.org/template IntelliSense in te schakelen in editors zoals Visual Studio Code.
author touw Nee. De auteur van de sjabloon.
classifications array(tekenreeks) Nee. Tags die gebruikers kunnen gebruiken om de sjabloon te vinden met dotnet new search of dotnet new list. Deze waarden worden weergegeven in de kolom Tags van de sjabloonlijst.
description touw Nee. Een beschrijving van wat de sjabloon maakt.
identity touw Ja Een unieke id voor de sjabloon.
name touw Ja De weergavenaam van de sjabloon die wordt weergegeven aan gebruikers.
shortName touw Ja De korte naam die gebruikers doorgeven om te dotnet new maken op basis van de sjabloon, zoals console of classlib.
sourceName touw Nee. Een tekenreeks in de bronbestanden en bestandsnamen die de sjabloonengine vervangt door de naam die de gebruiker via -n of --name. Als de gebruiker geen naam opgeeft, gebruikt de engine de naam van de huidige map.
preferNameDirectory boolean Nee. Wanneer true en de gebruiker een naam maar geen uitvoermap biedt, maakt de sjabloonengine een nieuwe map met die naam in plaats van bestanden naar de huidige map te schrijven. De standaardwaarde is false.
tags object Nee. Metagegevens die eigenschappen identificeren, zoals de taal en het type van de sjabloon. Gebruiken tags.language voor de taal en tags.type voor project, itemof solution.

Twee velden verdienen extra aandacht. Het sourceName veld is de manier waarop sjablonen naamgeving verwerken: stel deze in op een tekenreeks die wordt weergegeven in de bestandsnamen en broncode (zoals MyTemplate) en de sjabloonengine vervangt elk exemplaar door elke naam die de gebruiker doorgeeft bij het maken van de sjabloon. Het classifications veld bepaalt de detectiebaarheid; kies tags die het doel van uw sjabloon nauwkeurig beschrijven, zodat gebruikers deze kunnen vinden tijdens het zoeken.

Dit is minimaal template.json voor een consolesjabloon:

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

Het volledige schema is beschikbaar in JSON Schema Store. Zie de dotnet/templating GitHub wiki voor geavanceerde configuratieopties, zoals voorwaardelijke bestandsopname, acties na het maken en sjablonen voor meerdere projecten.

Sjabloonparameters (symbolen)

De symbols sectie in template.json definieert de parameters die gebruikers kunnen doorgeven wanneer ze een sjabloon maken. Elk symbool wordt een CLI-optie ingeschakeld dotnet new <shortName>, dus een symbool met de naam ClassName wordt --ClassName (of -C als u een korte naam definieert).

Elke symboolvermelding ondersteunt de volgende algemene instellingen:

Configuratie Description
type Moet voor gebruikersgerichte parameters zijn "parameter" .
description Weergegeven in de sjabloon help-uitvoer wanneer gebruikers worden uitgevoerd dotnet new <shortName> -?.
datatype Het verwachte gegevenstype, zoals "text", "bool"of "choice".
replaces Een tekenreeks in de inhoud van het bronbestand die door de sjabloonengine wordt vervangen door de parameterwaarde.
fileRename Een tekenreeks in de bronbestandsnamen die door de sjabloonengine worden vervangen door de parameterwaarde.
defaultValue De waarde die wordt gebruikt wanneer de gebruiker de parameter niet opgeeft.

De replaces en fileRename instellingen zijn de wijze waarop symbolen vervangen. Wanneer een gebruiker een waarde levert, vervangt de sjabloonengine elk exemplaar van de tekenreeks in bestandsinhoud replaces en elk exemplaar van de fileRename tekenreeks in bestandsnamen. Als de gebruiker geen waarde opgeeft, wordt de defaultValue waarde gebruikt.

Met het volgende symbool kunnen gebruikers bijvoorbeeld de klassenaam instellen wanneer ze een sjabloon maken. De naam van het bestand wordt gewijzigd en de klasse in het bestand wordt bijgewerkt zodat het overeenkomt met:

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

Als dit symbool is gedefinieerd, kan een gebruiker een dotnet new <shortName> --ClassName MyHelpers bestand maken met de naam MyHelpers.cs van een klasse MyHelpers. Zonder de vlag behouden het bestand en de klasse de standaardnaam StringExtensions.

Als u wilt controleren of de parameters die uw sjabloon beschikbaar maakt, geeft -? u de korte naam door nadat u deze hebt geïnstalleerd:

dotnet new <shortName> -?

Sjabloonpakketten

Een sjabloonpakket is een NuGet-bestand (.nupkg) dat een of meer van uw sjablonen samen bundelt. Wanneer een gebruiker uw sjabloonpakket installeert, registreert de .NET sjabloonengine elke sjabloon in één keer. Pakketten zijn de standaardmethode voor het distribueren van sjablonen. Publiceer één pakket naar NuGet.org of een persoonlijke NuGet-feed of deel een lokaal .nupkg bestand en gebruikers krijgen de hele verzameling met één opdracht.

Als u een sjabloonpakket wilt maken, gebruikt u een C#-projectbestand (.csproj) dat is geconfigureerd om te fungeren als een pakketproject in plaats van een compilatieproject. De belangrijkste instellingen die dit werk maken, zijn:

Configuratie Value Purpose
PackageType Template Markeert het pakket als een sjabloonpakket, zodat het in dotnet new search de resultaten wordt weergegeven.
IncludeContentInPack true Bevat inhoudsbestanden in het NuGet-pakket.
IncludeBuildOutput false Hiermee voorkomt u dat gecompileerde binaire bestanden aan het pakket worden toegevoegd.
ContentTargetFolders content Plaats uw sjabloonmappen in de content map van het NuGet-pakket, waar de sjabloonengine ze verwacht te vinden.

De templatepack projectsjabloon biedt de eenvoudigste manier om een verpakkingsproject te maken:

  1. Installeer de Microsoft. NuGet-pakket TemplateEngine.Authoring.Templates:

    dotnet new install Microsoft.TemplateEngine.Authoring.Templates

  2. Maak het verpakkingsproject:

    dotnet new templatepack -n <PackageName>

Het gegenereerde project bevat de juiste .csproj instellingen, een content map voor uw sjablonen en MSBuild-taken voor sjabloonvalidatie en optionele lokalisatie.

Zie Zelfstudie: Een sjabloonpakket maken voor een volledig overzicht van het maken, verpakken en publiceren van een sjabloonpakket.

Uw sjabloon lokaal testen

Tijdens het ontwikkelen van sjablonen installeert u de sjabloon rechtstreeks vanuit de map om deze te testen zonder eerst een pakket te bouwen. Geef het pad door naar de map die de .template.config map bevat:

dotnet new install ./mytemplate/

Als u alle geïnstalleerde sjabloonpakketten en de exacte opdracht wilt zien om elk sjabloon te verwijderen, voert dotnet new uninstall u zonder argumenten uit:

dotnet new uninstall

Als u een sjabloon wilt verwijderen die is geïnstalleerd vanuit een map, geeft u hetzelfde mappad door dat u hebt gebruikt om deze te installeren:

dotnet new uninstall ./mytemplate/

Zodra u klaar bent om uw sjabloon te delen, moet u deze inpakken als een NuGet-pakket (zie sjabloonpakketten) en deze distribueren. Gebruikers installeren uw gepubliceerde sjabloon met dotnet new install een van de volgende bronargumenten:

  • Een NuGet-pakket-id, waarmee de meest recente stabiele versie van de NuGet-bronnen wordt geïnstalleerd die zijn geconfigureerd voor de huidige map:

    dotnet new install AdatumCorporation.ConsoleTemplate.CSharp

  • Een NuGet-pakket-id met een aangepaste feed-URL. De --nuget-source optie maakt gebruik van de opgegeven feed, naast de geconfigureerde NuGet-bronnen, alleen voor die installatie:

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

  • Een pad naar een lokaal .nupkg bestand:

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

Warning

Sjablonen kunnen MSBuild-taken en willekeurige code uitvoeren tijdens het maken van het project. Installeer alleen sjablonen van bronnen die u vertrouwt.

Als u een pakket wilt verwijderen dat is geïnstalleerd vanuit een NuGet-bron of een lokaal .nupkg bestand, gebruikt u de NuGet-pakket-id:

dotnet new uninstall AdatumCorporation.ConsoleTemplate.CSharp

De ingebouwde SDK-sjablonen worden niet weergegeven in de lijst met verwijderingen en kunnen niet worden verwijderd met dotnet new uninstall.

Lokalisatie van sjablonen

De .NET sjabloonengine ondersteunt optionele lokalisatie van sjabloonmetagegevens. Wanneer u lokalisatiebestanden opgeeft, worden hosts zoals dotnet new en het dialoogvenster Visual Studio Nieuw Project de naam, beschrijving en symboolgegevens van de sjabloon weergegeven in de taal van de gebruiker in plaats van de oorspronkelijke geschreven taal.

De volgende sjabloonvelden ondersteunen lokalisatie:

  • name
  • author
  • description
  • Symbool description en displayName
  • Beschrijving en weergavenaam voor elke keuze in een keuzeparameter
  • description Actie plaatsen enmanualInstructions

Als u lokalisatie wilt toevoegen, maakt u een localize submap binnen .template.config en voegt u één JSON-bestand per taal toe. Geef elk bestand templatestrings.<lang-code>.jsoneen naam, waarbij <lang-code> deze overeenkomt met een geldige CultureInfo naam, zoals pt-BR, zh-Hansof de. Elk bestand bevat sleutel-waardeparen waarbij de sleutel een pad naar het element in template.jsonis, met als / scheidingsteken voor geneste velden.

Bijvoorbeeld, gegeven een template.json met de volgende inhoud:

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

Een Braziliaans Portugees lokalisatiebestand met de naam templatestrings.pt-BR.json ziet er als volgt uit:

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

De sjabloonengine parseert deze bestanden wanneer de sjabloongegevens worden geladen en retourneert automatisch gelokaliseerde waarden op basis van de huidige UI-cultuur. Er zijn geen extra stappen van de gebruiker vereist.

Lokalisatie is optioneel. Als u geen lokalisatiebestanden opneemt, werkt de sjabloon normaal en worden altijd de waarden van template.json. Zie de pagina dotnet/templating wiki lokalisatie voor meer informatie.

Integratie met Visual Studio

Visual Studio het dialoogvenster Een nieuw project maken maakt gebruik van de .NET sjabloonengine voor .NET projectsjablonen. Sjablonen die u ontwerpt voor dotnet new werk in Visual Studio, zonder extra configuratie. Wanneer een gebruiker uw sjabloonpakket installeert, dotnet new installVisual Studio deze sjablonen automatisch detecteert en weerkeert in het dialoogvenster.

Project en oplossingssjablonen worden weergegeven in het dialoogvenster Een nieuwe project maken naast de ingebouwde SDK-sjablonen. Gebruikers kunnen sjablonen vinden op naam, taal of de tags in het classifications veld in het bestand van template.json de sjabloon. Nauwkeurige classificaties helpen uw sjabloonoppervlak in de juiste filtercategorieën, dus kies ze zorgvuldig. Als u uw sjabloon een professioneel uiterlijk wilt geven in het dialoogvenster, voegt u een icon.png toe aan de .template.config map, Visual Studio deze weergeeft naast de naam van uw sjabloon.

Itemsjablonen worden momenteel niet weergegeven in het dialoogvensterNieuw itemtoevoegen>. Gebruikers kunnen nog steeds itemsjablonen gebruiken met de dotnet new opdracht in de terminal.

Als u uw sjabloon detecteerbaar wilt maken voor Visual Studio gebruikers die deze nog niet hebben geïnstalleerd, publiceert u het sjabloonpakket naar nuget.org. Het dialoogvenster Een nieuw project maken bevat een optie Meer sjablonen installeren op basis van de onlinezoekoptie waarmee nuget.org naar sjabloonpakketten wordt gezocht. Wanneer een gebruiker uw pakket via die optie installeert, gebruikt Visual Studio hetzelfde installatiemechanisme als dotnet new install.

Zie de sjabloonvoorbeeldopslagplaats van Sayed Hashimi voor meer informatie over Visual Studio-specifieke integratie, zoals het beheren van de sorteervolgorde van sjablonen en het configureren van aanvullende IDE-specifieke opties.

Verwante onderwerpen

  • Last updated on