Oktatóanyag: Elemsablon létrehozása

A .NET használatával projekteket, fájlokat és erőforrásokat létrehozó sablonokat hozhat létre és helyezhet üzembe. Ez az oktatóanyag egy sorozat első része, amely bemutatja, hogyan hozhat létre, telepíthet és távolíthat el sablonokat a dotnet new parancshoz való használatra.

A kész sablont a .NET-minták GitHub-adattárában tekintheti meg.

Tipp.

Az elemsablonok nem jelennek meg a Visual Studio Új elem hozzáadása>párbeszédpanelén.

A sorozat ezen részében megtanulhatja, hogyan:

• Hozzon létre egy osztályt egy elemsablonhoz.
• Hozza létre a sablon konfigurációs mappája és fájlja.
• Sablon telepítése egy fájl elérési útjáról.
• Elemsablon tesztelése.
• Elemsablon eltávolítása.

Előfeltételek

• .NET SDK 7.0.100 vagy újabb verzió.

  A referenciacikk ismerteti a sablonok alapjait és azok összeállításának módját. Ezen információk némelyikét itt ismételjük meg.

• Nyisson meg egy terminált, és keresse meg azt a mappát, amelyben tárolni és tesztelni fogja a sablonokat.

Fontos

Ez a cikk a .NET 7-hez készült. Ez azonban a .NET 6 és az előző verziókra is vonatkozik, egyetlen különbséggel: A dotnet new szintaxis eltérő. A list, search, install, és uninstall alparancsoknak, illetve a beállításoknak kell lenniük --uninstall--search--list--install.

A .NET 7 parancsa például dotnet new install a .NET 6-ban lesz dotnet new --install . A parancs használatával megtekintheti az dotnet new --help összes beállítás és alparancs listáját.

A szükséges mappák létrehozása

Ez a sorozat egy "munkamappát" használ, amelyben a sablonforrás található, és egy "tesztelési mappát" a sablonok teszteléséhez. A munkamappának és a tesztelési mappának ugyanabban a szülőmappában kell lennie.

Először hozza létre a szülőmappát, a név nem számít. Ezután hozzon létre két munka és tesztelés nevűalmappát. A munkamappában hozzon létre egy almappát, amelyet tartalomnak hívnak.

A mappaszerkezetnek az alábbihoz hasonlóan kell kinéznie.

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

Elemsablon létrehozása

Az elemsablonok olyan sablontípusok, amelyek egy vagy több fájlt tartalmaznak. Az ilyen típusú sablonok akkor hasznosak, ha már rendelkezik projektel, és egy másik fájlt szeretne létrehozni, például egy konfigurációs fájlt vagy egy kódfájlt. Ebben a példában egy olyan osztályt fog létrehozni, amely bővítménymetódust ad hozzá a sztringtípushoz.

A terminálban lépjen a munka\tartalom mappába, és hozzon létre egy új, bővítmények nevű almappát.

working
└───content
    └───extensions

Lépjen a bővítmények mappájába, és hozzon létre egy StringExtensions.cs nevű új fájlt. Nyissa meg a fájlt egy szövegszerkesztőben. Ez az osztály egy olyan bővítménymetódust Reverse fog biztosítani, amely megfordítja egy sztring tartalmát. Illessze be a következő kódot, és mentse a fájlt:

namespace System;

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

Most, hogy a sablon tartalma elkészült, a következő lépés a sablonkonfiguráció létrehozása.

A sablonkonfiguráció létrehozása

Az oktatóanyag ezen részében a sablonmappa a working\content\extensions helyen található.

A .NET azért ismeri fel a sablonokat, mert egy speciális mappával és konfigurációs fájllal rendelkeznek, amely a sablonmappa gyökerében található.

Először hozzon létre egy .template.config nevű új almappát, és adja meg. Ezután hozzon létre egy sablon.json nevű új fájlt. A mappaszerkezetnek így kell kinéznie:

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

Nyissa meg a template.json fájlt a kedvenc szövegszerkesztőjével, és illessze be a következő JSON-kódba, és mentse.

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

Ez a konfigurációs fájl tartalmazza a sablon összes beállítását. Megtekintheti az alapbeállításokat, például name az és shortName, de van egy tags/type érték is, amely a következőre itemvan állítva. Ez "elem" sablonként kategorizálja a sablont. Nincs korlátozás a létrehozott sablon típusára. A item .NET által javasolt általános nevek és project értékek, hogy a felhasználók egyszerűen szűrhessenek a keresett sablon típusára.

Az classifications elem a futtatáskor dotnet new és a sablonok listájának lekérésekor megjelenő címkék oszlopát jelöli. A felhasználók besorolási címkék alapján is kereshetnek. Ne keverje össze a tags template.json fájl tulajdonságát a classifications címkék listájával. Két különböző fogalom, amelyek sajnos ugyanazt a nevet viselik. A template.json fájl teljes sémája a JSON sématárolóban található, és a template.json referenciafájljában található. További információ a template.json fájlról: dotnet templating wiki.

Ennek symbols a JSON-objektumnak a része határozza meg a sablonban használható paramétereket. Ebben az esetben egy paraméter van definiálva. ClassName A megadott paraméter a következő beállításokat tartalmazza:

• type - Ez egy kötelező beállítás, amelyet be kell állítani parameter.
• description - A sablon súgójában kinyomtatott paraméter leírása.
• datatype - A paraméterérték adattípusa a paraméter használatakor.
• replaces – Olyan szöveges értéket ad meg, amelyet minden sablonfájlban le kell cserélni a paraméter értékével.
• fileRename – Ehhez hasonlóan replacesez egy szöveges értéket ad meg, amelyet az összes sablonfájl nevére cserél a paraméter értéke.
• defaultValue – A paraméter alapértelmezett értéke, ha a paramétert nem a felhasználó adja meg.

A sablon használata esetén a felhasználó megadhat egy értéket a ClassName paraméterhez, és ez az érték felülírja a paraméter összes előfordulását StringExtensions. Ha nincs megadva érték, a rendszer ezt defaultValue használja. Ebben a sablonban a StringExtensions.cs fájlnak és a StringExtensions osztálynak két előfordulása StringExtensionsvan. Mivel a defaultValue paraméter értéke az StringExtensions, a fájlnév és az osztálynév változatlan marad, ha a paraméter nincs megadva a sablon használatakor. Ha egy érték meg van adva, például dotnet new stringext -ClassName MyExtsa fájl neve MyExts.cs, az osztály pedig MyExts névre lesz átnevezve.

A sablonhoz elérhető paraméterek megtekintéséhez használja a -? paramétert a sablon nevével:

dotnet new stringext -?

Ez a következő kimenetet hozza létre:

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

Most, hogy rendelkezik egy érvényes .template.config/template.json fájllal, a sablon készen áll a telepítésre. A terminálban keresse meg a bővítmények mappát, és futtassa a következő parancsot az aktuális mappában található sablon telepítéséhez:

• Windows rendszeren: dotnet new install .\
• Linux vagy macOS rendszeren: dotnet new install ./

Ez a parancs megjeleníti a telepített sablonok listáját, amelynek tartalmaznia kell az Önét is.

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

Az elemsablon tesztelése

Most, hogy telepített egy elemsablont, tesztelje.

1. Nyissa meg a tesztmappát .

2. Hozzon létre egy új konzolalkalmazást dotnet new console, amely egy olyan működő projektet hoz létre, amelyet egyszerűen tesztelhet a dotnet run paranccsal.

   dotnet new console
   

   A kimenet az alábbiakhoz hasonlóan jelenik meg.

   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. Futtassa a projektet az alábbi paranccsal.

   dotnet run
   

   A következő kimenetet kapja.

   Hello, World!
   

4. Futtassa dotnet new stringext a StringExtensions.cs fájl sablonból való létrehozásához.

   dotnet new stringext
   

   A következő kimenetet kapja.

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

5. Módosítsa a Program.cs kódját a "Hello, World!" sztring megfordításához a sablon által biztosított bővítménymetódussal.

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

   Futtassa újra a programot, és ellenőrizze, hogy az eredmény vissza van-e fordítva.

   dotnet run
   

   A következő kimenetet kapja.

   !dlroW ,olleH
   

Gratulálunk! Létrehozott és üzembe helyezett egy elemsablont a .NET-tel. Az oktatóanyag-sorozat következő részének előkészítésekor távolítsa el a létrehozott sablont. A tesztmappában lévő összes fájlt és mappát is törölje. Ezzel visszakerül egy tiszta állapotba, amely készen áll az oktatóanyag-sorozat következő részére.

A sablon eltávolítása

A terminálban keresse meg a bővítmények mappát, és futtassa a következő parancsot az aktuális mappában található sablonok eltávolításához:

• Windows rendszeren: dotnet new uninstall .\
• Linux vagy macOS rendszeren: dotnet new uninstall ./

Ez a parancs megjeleníti az eltávolított sablonok listáját, amelynek tartalmaznia kell az Önét is.

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

dotnet new uninstall Bármikor megtekintheti a telepített sabloncsomagok listáját, beleértve az egyes sabloncsomagok esetében az eltávolításhoz szükséges parancsot is.

Következő lépések

Ebben az oktatóanyagban létrehozott egy elemsablont. Ha meg szeretné tudni, hogyan hozhat létre projektsablont, folytassa ezt az oktatóanyag-sorozatot.

Projektsablon létrehozása