Zelfstudie: Een itemsjabloon maken

Met .NET kunt u sjablonen maken en implementeren waarmee projecten, bestanden en resources worden gegenereerd. Deze zelfstudie is deel één van een reeks waarin u leert hoe u sjablonen kunt maken, installeren en verwijderen voor gebruik met de dotnet new opdracht.

U kunt de voltooide sjabloon bekijken in de GitHub-opslagplaats .NET Samples.

Fooi

Itemsjablonen worden niet weergegeven in het dialoogvenster Nieuw item toevoegen>van Visual Studio.

In dit deel van de serie leert u het volgende:

• Maak een klasse voor een itemsjabloon.
• Maak de sjabloonconfiguratiemap en het bestand.
• Installeer een sjabloon vanuit een bestandspad.
• Test een itemsjabloon.
• Verwijder een itemsjabloon.

Vereisten

• .NET SDK 7.0.100 of een latere versie.

  In het naslagartikel worden de basisbeginselen van sjablonen uitgelegd en hoe deze worden samengesteld. Een deel van deze informatie wordt hier herhaald.

• Open een terminal en navigeer naar een map waarin u de sjablonen opslaat en test.

Belangrijk

Dit artikel is geschreven voor .NET 7. Het is echter ook van toepassing op .NET 6 en eerdere versies, met één verschil: de dotnet new syntaxis is anders. De listsubopdrachten , searchen uninstallinstallsubopdrachten moeten respectievelijk , --search--installen --uninstall opties zijn--list.

De opdracht in .NET 7 wordt dotnet new --install bijvoorbeeld dotnet new install in .NET 6. Gebruik de dotnet new --help opdracht om een lijst met alle opties en subopdrachten weer te geven.

De vereiste mappen maken

Deze reeks maakt gebruik van een 'werkmap' waarin uw sjabloonbron zich bevindt en een testmap die wordt gebruikt om uw sjablonen te testen. De werkmap en de testmap moeten zich onder dezelfde bovenliggende map bevinden.

Maak eerst de bovenliggende map, de naam maakt niet uit. Maak vervolgens twee submappen met de naam werken en testen. Maak in de werkmap een submap met de naam Inhoud.

De mapstructuur moet er als volgt uitzien.

parent_folder
├───test
└───working
    └───content

Een itemsjabloon maken

Een itemsjabloon is een specifiek type sjabloon dat een of meer bestanden bevat. Deze typen sjablonen zijn handig wanneer u al een project hebt en u een ander bestand wilt genereren, zoals een configuratiebestand of codebestand. In dit voorbeeld maakt u een klasse waarmee een extensiemethode wordt toegevoegd aan het tekenreekstype.

Navigeer in de terminal naar de map working\content en maak een nieuwe submap met de naam Extensions.

working
└───content
    └───extensions

Navigeer naar de map extensies en maak een nieuw bestand met de naam StringExtensions.cs. Open het bestand in een teksteditor. Deze klasse biedt een extensiemethode met de naam Reverse waarmee de inhoud van een tekenreeks wordt omgekeerd. Plak de volgende code en sla het bestand op:

namespace System;

public static class StringExtensions
{
    public static string Reverse(this string value)
    {
        char[] tempArray = value.ToCharArray();
        Array.Reverse(tempArray);
        return new string(tempArray);
    }
}

Nu de inhoud van de sjabloon is voltooid, is de volgende stap het maken van de sjabloonconfiguratie.

De sjabloonconfiguratie maken

In dit deel van de zelfstudie bevindt uw sjabloonmap zich in working\content\extensions.

Sjablonen worden herkend door .NET omdat ze een speciale map en een configuratiebestand hebben dat zich in de hoofdmap van de sjabloonmap bevindt.

Maak eerst een nieuwe submap met de naam .template.config en voer deze in. Maak vervolgens een nieuw bestand met de naam template.json. De mapstructuur moet er als volgt uitzien:

working
└───content
    └───extensions
        └───.template.config
                template.json

Open de template.json met uw favoriete teksteditor en plak de volgende JSON-code en sla deze op.

{
    "$schema": "http://json.schemastore.org/template",
    "author": "Me",
    "classifications": [ "Common", "Code" ],
    "identity": "ExampleTemplate.StringExtensions",
    "name": "Example templates: string extensions",
    "shortName": "stringext",
    "tags": {
      "language": "C#",
      "type": "item"
    },
    "symbols": {
      "ClassName":{
        "type": "parameter",
        "description": "The name of the code file and class.",
        "datatype": "text",
        "replaces": "StringExtensions",
        "fileRename": "StringExtensions",
        "defaultValue": "StringExtensions"
      }
    }
  }

Dit configuratiebestand bevat alle instellingen voor uw sjabloon. U kunt de basisinstellingen zien, zoals name en shortName, maar er is ook een tags/type waarde ingesteld op item. Hiermee categoriseert u uw sjabloon als een itemsjabloon. Er is geen beperking voor het type sjabloon dat u maakt. De item en project waarden zijn algemene namen die door .NET worden aanbevolen, zodat gebruikers eenvoudig het type sjabloon kunnen filteren waarnaar ze zoeken.

Het classifications item vertegenwoordigt de kolom met tags die u ziet wanneer u uitvoert dotnet new en een lijst met sjablonen opgeeft. Gebruikers kunnen ook zoeken op basis van classificatietags. Verwar de tags eigenschap in het bestand template.json niet met de classifications lijst met tags. Het zijn twee verschillende concepten die helaas hetzelfde worden genoemd. Het volledige schema voor het bestand template.json vindt u in het JSON-schemaarchief en wordt beschreven op Referentie voor template.json. Zie de sjabloonwiki dotnet voor meer informatie over het bestand template.json.

Het symbols deel van dit JSON-object wordt gebruikt om de parameters te definiëren die in de sjabloon kunnen worden gebruikt. In dit geval is er één parameter gedefinieerd, ClassName. De gedefinieerde parameter bevat de volgende instellingen:

• type - Dit is een verplichte instelling en moet worden ingesteld op parameter.
• description - De beschrijving van de parameter, die wordt afgedrukt in de help van de sjabloon.
• datatype - Het type gegevens van de parameterwaarde wanneer de parameter wordt gebruikt.
• replaces - Hiermee geeft u een tekstwaarde op die in alle sjabloonbestanden moet worden vervangen door de waarde van de parameter.
• fileRename - Vergelijkbaar met replaces, geeft dit een tekstwaarde die wordt vervangen in de namen van alle sjabloonbestanden door de waarde van de parameter.
• defaultValue - De standaardwaarde van deze parameter wanneer de parameter niet is opgegeven door de gebruiker.

Wanneer de sjabloon wordt gebruikt, kan de gebruiker een waarde voor de ClassName parameter opgeven en vervangt deze waarde alle exemplaren van StringExtensions. Als er geen waarde is opgegeven, wordt de defaultValue waarde gebruikt. Voor deze sjabloon zijn er twee exemplaren van StringExtensions: het bestand StringExtensions.cs en de klasse StringExtensions. Omdat de defaultValue parameter is StringExtensions, blijven de bestandsnaam en klassenaam ongewijzigd als de parameter niet is opgegeven bij het gebruik van de sjabloon. Wanneer bijvoorbeeld een waarde is opgegeven, dotnet new stringext -ClassName MyExtswordt de naam van het bestand MyExts.cs gewijzigd en wordt de naam van de klasse gewijzigd in MyExts.

Als u wilt zien welke parameters beschikbaar zijn voor een sjabloon, gebruikt u de -? parameter met de sjabloonnaam:

dotnet new stringext -?

Hiermee wordt de volgende uitvoer geproduceerd:

Example templates: string extensions (C#)
Author: Me

Usage:
  dotnet new stringext [options] [template options]

Options:
  -n, --name <name>       The name for the output being created. If no name is specified, the name of the output directory is used.
  -o, --output <output>   Location to place the generated output.
  --dry-run               Displays a summary of what would happen if the given command line were run if it would result in a template creation.
  --force                 Forces content to be generated even if it would change existing files.
  --no-update-check       Disables checking for the template package updates when instantiating a template.
  --project <project>     The project that should be used for context evaluation.
  -lang, --language <C#>  Specifies the template language to instantiate.
  --type <item>           Specifies the template type to instantiate.

Template options:
  -C, --ClassName <ClassName>  The name of the code file and class.
                               Type: text
                               Default: StringExtensions

Nu u een geldig .template.config/template.json-bestand hebt, kunt u de sjabloon installeren. Navigeer in de terminal naar de map extensies en voer de volgende opdracht uit om de sjabloon in de huidige map te installeren:

• In Windows: dotnet new install .\
• In Linux of macOS: dotnet new install ./

Met deze opdracht wordt de lijst met geïnstalleerde sjablonen uitgevoerd, waaronder die van u.

The following template packages will be installed:
   <root path>\working\content\extensions

Success: <root path>\working\content\extensions installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: string extensions              stringext                [C#]              Common/Code

De itemsjabloon testen

Nu u een itemsjabloon hebt geïnstalleerd, test u deze.

1. Navigeer naar de testmap .

2. Maak een nieuwe consoletoepassing met dotnet new console, waarmee u een werkend project genereert dat u eenvoudig kunt testen met de dotnet run opdracht.

   dotnet new console
   

   U krijgt uitvoer die er ongeveer als volgt uitziet.

   The template "Console Application" was created successfully.
   
   Processing post-creation actions...
   Running 'dotnet restore' on C:\test\test.csproj...
     Restore completed in 54.82 ms for C:\test\test.csproj.
   
   Restore succeeded.
   

3. Voer het project uit met behulp van de volgende opdracht.

   dotnet run
   

   U krijgt de volgende uitvoer.

   Hello, World!
   

4. Voer uit dotnet new stringext om het bestand StringExtensions.cs te genereren op basis van de sjabloon.

   dotnet new stringext
   

   U krijgt de volgende uitvoer.

   The template "Example templates: string extensions" was created successfully.
   

5. Wijzig de code in Program.cs om de "Hello, World!" tekenreeks om te draaien met de extensiemethode die door de sjabloon wordt geleverd.

   Console.WriteLine("Hello, World!".Reverse());
   

   Voer het programma opnieuw uit en zie dat het resultaat is omgekeerd.

   dotnet run
   

   U krijgt de volgende uitvoer.

   !dlroW ,olleH
   

Gefeliciteerd! U hebt een itemsjabloon gemaakt en geïmplementeerd met .NET. Verwijder de sjabloon die u hebt gemaakt ter voorbereiding op het volgende deel van deze reeks zelfstudies. Zorg ervoor dat u ook alle bestanden en mappen in de testmap verwijdert. Hiermee krijgt u weer een schone status voor het volgende deel van deze zelfstudiereeks.

De sjabloon verwijderen

Navigeer in de terminal naar de map extensies en voer de volgende opdracht uit om de sjablonen in de huidige map te verwijderen:

• In Windows: dotnet new uninstall .\
• In Linux of macOS: dotnet new uninstall ./

Met deze opdracht wordt een lijst uitgevoerd met de sjablonen die zijn verwijderd, waaronder die van u.

Success: <root path>\working\content\extensions was uninstalled.

U kunt dotnet new uninstall op elk gewenst moment een lijst met geïnstalleerde sjabloonpakketten bekijken, inclusief voor elk sjabloonpakket dat u wilt verwijderen.

Volgende stappen

In deze zelfstudie hebt u een itemsjabloon gemaakt. Als u wilt weten hoe u een projectsjabloon maakt, gaat u verder met deze reeks zelfstudies.

Een projectsjabloon maken