Delen via

Aangepaste sjablonen voor dotnet nieuw

  • Artikel

De .NET SDK wordt geleverd met veel sjablonen die al zijn geïnstalleerd en klaar zijn voor gebruik. De dotnet new opdracht is niet alleen de manier om een sjabloon te gebruiken, maar ook het installeren en verwijderen van sjablonen. U kunt uw eigen aangepaste sjablonen maken voor elk type project, zoals een app, service, hulpprogramma of klassebibliotheek. U kunt zelfs een sjabloon maken die een of meer onafhankelijke bestanden uitvoert, zoals een configuratiebestand.

U kunt aangepaste sjablonen installeren vanuit een NuGet-pakket op elke NuGet-feed door rechtstreeks te verwijzen naar een NuGet.nupkg-bestand of door een bestandssysteemmap op te geven die de sjabloon bevat. De sjabloonengine biedt functies waarmee u waarden kunt vervangen, bestanden kunt opnemen en uitsluiten en aangepaste verwerkingsbewerkingen kunt uitvoeren wanneer uw sjabloon wordt gebruikt.

De sjabloonengine is open source en de online codeopslagplaats bevindt zich op dotnet/templating op GitHub. Meer sjablonen, waaronder sjablonen van derden, zijn te vinden met behulp van dotnet new search. Zie How to create your own templates for dotnet new and the dotnet/templating GitHub repo Wiki voor meer informatie over het maken en gebruiken van aangepaste sjablonen.

Notitie

Sjabloonvoorbeelden zijn beschikbaar in de GitHub-opslagplaats dotnet/templating .

Als u een overzicht wilt volgen en een sjabloon wilt maken, raadpleegt u de zelfstudie Een aangepaste sjabloon maken voor dotnet.

Standaardsjablonen voor .NET

Wanneer u de .NET SDK installeert, ontvangt u meer dan tien ingebouwde sjablonen voor het maken van projecten en bestanden, waaronder console-apps, klassebibliotheken, eenheidstestprojecten, ASP.NET Core-apps (inclusief Angular - en React-projecten ) en configuratiebestanden. Voer de dotnet new list opdracht uit om de ingebouwde sjablonen weer te geven:

dotnet new list

Configuratie

Een sjabloon bestaat uit de volgende onderdelen:

  • Bronbestanden en -mappen.
  • Een configuratiebestand (template.json).

Bronbestanden en -mappen

De bronbestanden en -mappen bevatten alle bestanden en mappen die u wilt gebruiken door de sjabloonengine wanneer de dotnet new <TEMPLATE> opdracht wordt uitgevoerd. De sjabloonengine is ontworpen om runnable projecten als broncode te gebruiken om projecten te produceren. Dit heeft verschillende voordelen:

  • Voor de sjabloonengine hoeft u geen speciale tokens in de broncode van uw project in te voegen.
  • De codebestanden zijn geen speciale bestanden of zijn op geen enkele manier gewijzigd om met de sjabloonengine te werken. De hulpprogramma's die u normaal gesproken gebruikt bij het werken met projecten, werken dus ook met sjablooninhoud.
  • U kunt uw sjabloonprojecten bouwen, uitvoeren en er fouten in opsporen, net zoals u dat voor andere projecten doet.
  • U kunt snel een sjabloon maken op basis van een bestaand project door een configuratiebestand ./.template.config/template.json toe te voegen aan het project.

Bestanden en mappen die zijn opgeslagen in de sjabloon, zijn niet beperkt tot formele .NET-projecttypen. Bronbestanden en -mappen kunnen bestaan uit inhoud die u wilt maken wanneer de sjabloon wordt gebruikt, zelfs als de sjabloonengine slechts één bestand produceert als uitvoer.

Bestanden die door de sjabloon worden gegenereerd, kunnen worden gewijzigd op basis van logica en instellingen die u hebt opgegeven in het template.json configuratiebestand. De gebruiker kan deze instellingen overschrijven door opties door te geven aan de dotnet new <TEMPLATE> opdracht. Een veelvoorkomend voorbeeld van aangepaste logica is het opgeven van een naam voor een klasse of variabele in het codebestand dat door een sjabloon wordt geïmplementeerd.

template.json

Het bestand template.json wordt in een map .template.config in de hoofdmap van de sjabloon geplaatst. Het bestand bevat configuratiegegevens voor de sjabloonengine. Voor de minimale configuratie moeten de leden in de volgende tabel worden weergegeven. Dit is voldoende om een functionele sjabloon te maken.

Lid Type Description
$schema URI Het JSON-schema voor het template.json-bestand . Editors die JSON-schema's ondersteunen, maken JSON-bewerkingsfuncties mogelijk wanneer het schema is opgegeven. Visual Studio Code vereist bijvoorbeeld dat dit lid IntelliSense inschakelt. Gebruik een waarde van http://json.schemastore.org/template.
author tekenreeks De auteur van de sjabloon.
classifications matrix(tekenreeks) Nul of meer kenmerken van de sjabloon die een gebruiker kan gebruiken om de sjabloon te vinden bij het zoeken naar de sjabloon. De classificaties worden ook weergegeven in de kolom Tags wanneer deze wordt weergegeven in een lijst met sjablonen die worden geproduceerd met behulp van de dotnet new list opdracht.
identity tekenreeks Een unieke naam voor deze sjabloon.
name tekenreeks De naam van de sjabloon die gebruikers moeten zien.
shortName tekenreeks Een standaardnaam voor het selecteren van de sjabloon die van toepassing is op omgevingen waarin de sjabloonnaam wordt opgegeven door de gebruiker, niet via een GUI. De korte naam is bijvoorbeeld handig bij het gebruik van sjablonen vanaf een opdrachtprompt met CLI-opdrachten.
sourceName tekenreeks De naam in de bronstructuur die moet worden vervangen door de naam die de gebruiker opgeeft. De sjabloonengine zoekt naar een exemplaar van het sourceName config-bestand en vervangt het in bestandsnamen en bestandsinhoud. De te vervangen waarde kan worden opgegeven met behulp van de of --name opties tijdens het -n uitvoeren van een sjabloon. Als er geen naam is opgegeven, wordt de huidige map gebruikt.
preferNameDirectory Booleaanse waarde Hiermee wordt aangegeven of er een map voor de sjabloon moet worden gemaakt als de naam is opgegeven, maar dat er geen uitvoermap is ingesteld (in plaats van de inhoud rechtstreeks in de huidige map te maken). De standaardwaarde is false.

Het volledige schema voor het template.json-bestand vindt u in de JSON Schema Store. Zie de dotnet-sjabloonwiki voor meer informatie over het template.json-bestand. Bekijk de resources die Sayed Hashimi heeft gemaakt voor meer voorbeelden en informatie over het zichtbaar maken van uw sjablonen in Visual Studio.

Opmerking

Hier volgt bijvoorbeeld een sjabloonmap die twee inhoudsbestanden bevat: console.cs en readme.txt. Er is ook de vereiste map met de naam .template.config die het template.json-bestand bevat.

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

Het bestand template.json ziet er als volgt uit:

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

De map mytemplate is een installeerbaar sjabloonpakket. Zodra het pakket is geïnstalleerd, kan het shortName worden gebruikt met de dotnet new opdracht. Hiermee worden de console.cs bestanden readme.txt bijvoorbeeld dotnet new adatumconsole naar de huidige map uitgevoerd.

Lokalisatie van sjablonen

De .NET-sjablonen kunnen worden gelokaliseerd. Als een sjabloon is gelokaliseerd voor de taal die overeenkomt met de huidige landinstelling, worden de bijbehorende elementen weergegeven in dezelfde taal als de CLI. Lokalisatie is optioneel bij het maken van nieuwe sjablonen.

De lokaliseerbare elementen op een sjabloon zijn:

  • Naam
  • Auteur
  • Beschrijving
  • Symbolen
    • Beschrijving
    • Weergavenaam
    • Beschrijvingen en weergavenaam van keuzes voor keuzeparameters
  • Postacties
    • Beschrijving
    • Handmatige instructies

Lokalisatiebestanden hebben een JSON-indeling en slechts één bestand per cultuur moet bestaan. De naamconventie is: templatestrings.<lang code>.json, waar lang code komt overeen met een van de CultureInfo-opties . Alle lokalisatiebestanden moeten zich in de .template-config\localize map bevinden.

De lokalisatie-JSON bestaat uit sleutel-waardeparen:

  • De sleutel is de verwijzing naar een element dat template.json moet worden gelokaliseerd. Als het element een onderliggend element is, gebruikt u het volledige pad met een / scheidingsteken.
  • De waarde is de lokalisatietekenreeks van het element dat door de sleutel wordt gegeven.

Zie de lokalisatiepagina van de dotnet-wiki voor meer informatie over het lokaliseren van sjablonen.

Opmerking

Hier ziet u bijvoorbeeld template.json bestand met enkele lokaliseerbare velden:

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

En sommige velden moeten worden gelokaliseerd in Braziliaans Portugees. De bestandsnaam komt templatestrings.pt-BR.json overeen met de cultuur en 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."
}

Een sjabloon inpakken in een NuGet-pakket (nupkg-bestand)

Een aangepaste sjabloon is verpakt met de opdracht dotnet pack en een .csproj-bestand . U kunt NuGet ook gebruiken met de opdracht nuget pack, samen met een .nuspec-bestand. NuGet vereist echter het .NET Framework in Windows en Mono op Linux en macOS.

Het .csproj-bestand verschilt enigszins van een traditioneel .csproj-bestand met code-project. De volgende instellingen zijn van belang:

  1. De <PackageType> instelling wordt toegevoegd en ingesteld op Template.
  2. De <PackageVersion> instelling wordt toegevoegd en ingesteld op een geldig NuGet-versienummer.
  3. De <PackageId> instelling wordt toegevoegd en ingesteld op een unieke id. Deze id wordt gebruikt om het sjabloonpakket te verwijderen en wordt gebruikt door NuGet-feeds om uw sjabloonpakket te registreren.
  4. Algemene metagegevensinstellingen moeten worden ingesteld: <Title>, <Authors>, <Description>en <PackageTags>.
  5. De <TargetFramework> instelling moet worden ingesteld, ook al wordt het binaire bestand dat door het sjabloonproces wordt geproduceerd, niet gebruikt. In het onderstaande voorbeeld is dit ingesteld op netstandard2.0.

Voor een sjabloonpakket, in de vorm van een .nupkg NuGet-pakket, moeten alle sjablonen worden opgeslagen in de inhoudsmap binnen het pakket. Er zijn nog enkele instellingen om toe te voegen aan een .csproj-bestand om ervoor te zorgen dat de gegenereerde .nupkg kan worden geïnstalleerd als sjabloonpakket:

  1. De <IncludeContentInPack> instelling is ingesteld om true elk bestand op te nemen dat door het project als inhoud in het NuGet-pakket wordt ingesteld.
  2. De <IncludeBuildOutput> instelling is zo ingesteld dat false alle binaire bestanden die door de compiler zijn gegenereerd, worden uitgesloten van het NuGet-pakket.
  3. De <ContentTargetFolders> instelling is ingesteld op content. Dit zorgt ervoor dat de bestanden die zijn ingesteld als inhoud , worden opgeslagen in de inhoudsmap in het NuGet-pakket. Deze map in het NuGet-pakket wordt geparseerd door het dotnet-sjabloonsysteem.

Een eenvoudige manier om alle codebestanden uit te sluiten die door uw sjabloonproject worden gecompileerd, is door het <Compile Remove="**\*" /> item in uw projectbestand te gebruiken binnen een <ItemGroup> element.

Een eenvoudige manier om uw sjabloonpakket te structuren, is door alle sjablonen in afzonderlijke mappen te plaatsen en vervolgens elke sjabloonmap in een sjabloonmap die zich in dezelfde map bevindt als uw .csproj-bestand . Op deze manier kunt u één projectitem gebruiken om alle bestanden en mappen in de sjablonen als inhoud op te nemen. Maak een <Content Include="templates\**\*" Exclude="templates\**\bin\**;templates\**\obj\**" /> item in een <ItemGroup> element.

Hier volgt een voorbeeld van een .csproj-bestand dat aan al deze richtlijnen voldoet. De onderliggende sjablonenmap wordt in de map met inhoudspakketten verpakt en alle codebestanden worden niet gecompileerd.

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

In het volgende voorbeeld ziet u de bestands- en mapstructuur van het gebruik van een .csproj om een sjabloonpakket te maken. Het bestand MyDotnetTemplates.csproj en de map sjablonen bevinden zich beide in de hoofdmap van een map met de naam project_folder. De map met sjablonen bevat twee sjablonen, mytemplate1 en mytemplate2. Elke sjabloon bevat inhoudsbestanden en een map .template.config met een template.json configuratiebestand.

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

Notitie

Als u ervoor wilt zorgen dat het sjabloonpakket in dotnet new search het resultaat wordt weergegeven, stelt u het Type NuGet-pakket in op Template.

Een sjabloonpakket installeren

Gebruik de opdracht nieuwe dotnet-installatie om een sjabloonpakket te installeren.

Een sjabloonpakket installeren vanuit een NuGet-pakket dat is opgeslagen op nuget.org

Gebruik de NuGet-pakket-id om een sjabloonpakket te installeren.

dotnet new install <NUGET_PACKAGE_ID>

Een sjabloonpakket installeren vanuit een aangepaste NuGet-bron

Geef een aangepaste NuGet-bron op (bijvoorbeeld https://api.my-custom-nuget.com/v3/index.json).

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

Een sjabloonpakket installeren vanuit een lokaal nupkg-bestand

Geef het pad op naar een .nupkg NuGet-pakketbestand.

dotnet new install <PATH_TO_NUPKG_FILE>

Een sjabloonpakket installeren vanuit een bestandssysteemmap

Sjablonen kunnen worden geïnstalleerd vanuit een sjabloonmap, zoals de map mytemplate1 uit het vorige voorbeeld. Geef het mappad op van de map .template.config . Het pad naar de sjabloonmap hoeft niet absoluut te zijn.

dotnet new install <FILE_SYSTEM_DIRECTORY>

Een lijst met geïnstalleerde sjabloonpakketten ophalen

Met de opdracht verwijderen, zonder andere parameters, worden alle geïnstalleerde sjabloonpakketten en meegeleverde sjablonen weergegeven.

dotnet new uninstall

Deze opdracht retourneert iets dat vergelijkbaar is met de volgende uitvoer:

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

Het eerste niveau van items erna Currently installed items: zijn de id's die worden gebruikt bij het verwijderen van een sjabloonpakket. En in het vorige voorbeeld Microsoft.Azure.WebJobs.ProjectTemplates wordt vermeld. Als het sjabloonpakket is geïnstalleerd met behulp van een bestandssysteempad, is deze id het mappad van de map .template.config . Alleen de sjabloonpakketten die zijn geïnstalleerd via dotnet new install , worden weergegeven in de lijst. De sjabloonpakketten die zijn ingebouwd in de .NET SDK, worden niet weergegeven.

Een sjabloonpakket verwijderen

Gebruik de opdracht dotnet new uninstall om een sjabloonpakket te verwijderen.

Als het pakket is geïnstalleerd door een NuGet-feed of rechtstreeks door een .nupkg-bestand , geeft u de id op.

dotnet new uninstall <NUGET_PACKAGE_ID>

Als het pakket is geïnstalleerd door een pad naar de map .template.config op te geven, gebruikt u dat pad om het pakket te verwijderen. U kunt het absolute pad van het sjabloonpakket zien in de uitvoer van de dotnet new uninstall opdracht. Zie de sectie Een lijst met geïnstalleerde sjablonen ophalen voor meer informatie.

dotnet new uninstall <FILE_SYSTEM_DIRECTORY>

Een project maken met behulp van een aangepaste sjabloon

Nadat een sjabloon is geïnstalleerd, gebruikt u de sjabloon door de dotnet new <TEMPLATE> opdracht uit te voeren zoals u dat zou doen met een andere vooraf geïnstalleerde sjabloon. U kunt ook opties opgeven voor de dotnet new opdracht, inclusief sjabloonspecifieke opties die u hebt geconfigureerd in de sjablooninstellingen. Geef de korte naam van de sjabloon rechtstreeks op bij de opdracht:

dotnet new <TEMPLATE>

Zie ook