Delen via

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.

Aanbeveling

Itemsjablonen worden niet weergegeven in het dialoogvensterNieuw item> van Visual Studio.

In dit deel van de serie leert u het volgende:

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

Vereiste voorwaarden

  • .NET 9 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.

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, maakt u 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.configen 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 template.json bestand niet met de classifications lijst met tags. Het zijn twee verschillende concepten die helaas hetzelfde worden genoemd. Het volledige schema voor het template.json-bestand vindt u in de JSON-schemaopslag en wordt beschreven in Naslaginformatie voor template.json. Zie de dotnet-sjabloonwiki voor meer informatie over het template.json-bestand.

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 weergegeven in de sjabloonhandleiding.
  • 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 een waarde is opgegeven, bijvoorbeeld dotnet new stringext -ClassName MyExts, wordt de naam van het bestand gewijzigd naar MyExts.cs 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

Test een itemsjabloon

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

  1. Navigeer naar de test-map.

  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 dotnet new stringext uit om het StringExtensions.cs-bestand 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 keert u terug naar een schone staat, klaar voor het volgende deel van deze handleidingreeks.

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 op elk gewenst moment dotnet new uninstall gebruiken om een lijst met geïnstalleerde sjabloonpakketten te zien, inclusief voor elk sjabloonpakket het commando om het te 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

  • Last updated on