Samouczek: tworzenie szablonu elementu

  • Artykuł

Za pomocą platformy .NET można tworzyć i wdrażać szablony, które generują projekty, pliki i zasoby. Ten samouczek jest częścią jednej z serii, która uczy, jak tworzyć, instalować i odinstalowywać szablony do użycia z poleceniem dotnet new .

Ukończony szablon można wyświetlić w repozytorium GitHub przykłady platformy .NET.

Napiwek

Szablony elementów nie są wyświetlane w oknie dialogowym Dodawanie>nowego elementu programu Visual Studio.

W tej części serii dowiesz się, jak wykonywać następujące działania:

  • Utwórz klasę dla szablonu elementu.
  • Utwórz folder konfiguracji szablonu i plik.
  • Zainstaluj szablon ze ścieżki pliku.
  • Testowanie szablonu elementu.
  • Odinstaluj szablon elementu.

Wymagania wstępne

  • Zestaw .NET SDK 7.0.100 lub nowsza wersja.

    W artykule referencyjnym wyjaśniono podstawowe informacje o szablonach i sposobie ich łączenia. Niektóre z tych informacji są powtarzane tutaj.

  • Otwórz terminal i przejdź do folderu, w którym będziesz przechowywać i testować szablony.

Ważne

Ten artykuł jest napisany dla platformy .NET 7. Dotyczy to jednak również platformy .NET 6 i poprzednich wersji z jedną różnicą: Składnia dotnet new jest inna. Polecenia list, search, installi uninstall podrzędne powinny być --listodpowiednio opcjami , --search, --installi --uninstall .

Na przykład dotnet new install polecenie na platformie .NET 7 staje dotnet new --install się w programie .NET 6. dotnet new --help Użyj polecenia , aby wyświetlić listę wszystkich opcji i podpolecenia.

Tworzenie wymaganych folderów

Ta seria używa "folderu roboczego", w którym znajduje się źródło szablonu i "folder testowy" używany do testowania szablonów. Folder roboczy i folder testowy powinny znajdować się w tym samym folderze nadrzędnym.

Najpierw utwórz folder nadrzędny, nazwa nie ma znaczenia. Następnie utwórz dwa podfoldery o nazwie working i test. Wewnątrz folderu roboczego utwórz podfolder o nazwie content.

Struktura folderów powinna wyglądać podobnie do poniższej.

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

Tworzenie szablonu elementu

Szablon elementu jest określonym typem szablonu, który zawiera co najmniej jeden plik. Te typy szablonów są przydatne, gdy masz już projekt i chcesz wygenerować inny plik, taki jak plik konfiguracji lub plik kodu. W tym przykładzie utworzysz klasę, która dodaje metodę rozszerzenia do typu ciągu.

W terminalu przejdź do folderu working\content i utwórz nowy podfolder o nazwie extensions.

working
└───content
    └───extensions

Przejdź do folderu extensions i utwórz nowy plik o nazwie StringExtensions.cs. Otwórz plik w edytorze tekstów. Ta klasa udostępnia metodę rozszerzenia o nazwie Reverse , która odwraca zawartość ciągu. Wklej następujący kod i zapisz plik:

namespace System;

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

Po zakończeniu zawartości szablonu następnym krokiem jest utworzenie konfiguracji szablonu.

Tworzenie konfiguracji szablonu

W tej części samouczka folder szablonu znajduje się w folderze working\content\extensions.

Szablony są rozpoznawane przez platformę .NET, ponieważ mają specjalny folder i plik konfiguracji, który istnieje w folderze głównym folderu szablonu.

Najpierw utwórz nowy podfolder o nazwie .template.config i wprowadź go. Następnie utwórz nowy plik o nazwie template.json. Struktura folderów powinna wyglądać następująco:

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

Otwórz plik template.json przy użyciu ulubionego edytora tekstów i wklej następujący kod JSON i zapisz go.

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

Ten plik konfiguracji zawiera wszystkie ustawienia szablonu. Możesz zobaczyć podstawowe ustawienia, takie jak name i shortName, ale istnieje również tags/type wartość ustawiona na itemwartość . Spowoduje to kategoryzowanie szablonu jako szablonu "elementu". Nie ma żadnych ograniczeń dotyczących typu tworzonego szablonu. Wartości item i project to nazwy pospolite zalecane przez platformę .NET, aby użytkownicy mogli łatwo filtrować typ szukanego szablonu.

Element classifications reprezentuje kolumnę tagów widoczną po uruchomieniu dotnet newi pobraniu listy szablonów. Użytkownicy mogą również wyszukiwać na podstawie tagów klasyfikacji. Nie należy mylić tags właściwości w pliku template.json z listą classifications tagów. Są to dwa różne pojęcia, które są niestety takie same. Pełny schemat pliku template.json znajduje się w magazynie schematów JSON i jest opisany w artykule Reference for template.json (Dokumentacja pliku template.json). Aby uzyskać więcej informacji na temat pliku template.json , zobacz witrynę typu wiki dotnet templating.

Część symbols tego obiektu JSON służy do definiowania parametrów, które mogą być używane w szablonie. W tym przypadku istnieje jeden zdefiniowany parametr : ClassName. Zdefiniowany parametr zawiera następujące ustawienia:

  • type — Jest to ustawienie obowiązkowe i musi być ustawione na parameterwartość .
  • description — Opis parametru, który jest drukowany w pomocy szablonu.
  • datatype - Typ danych wartości parametru, gdy parametr jest używany.
  • replaces - Określa wartość tekstową, którą należy zastąpić we wszystkich plikach szablonu przez wartość parametru.
  • fileRename - Podobnie jak replaces, określa wartość tekstową, która jest zastępowana w nazwach wszystkich plików szablonu przez wartość parametru.
  • defaultValue - Wartość domyślna tego parametru, gdy parametr nie jest określony przez użytkownika.

Gdy szablon jest używany, użytkownik może podać wartość parametru ClassName , a ta wartość zastępuje wszystkie wystąpienia elementu StringExtensions. Jeśli wartość nie zostanie podana, zostanie użyta defaultValue wartość . W przypadku tego szablonu istnieją dwa wystąpienia StringExtensionspliku StringExtensions.cs i klasy StringExtensions. defaultValue Ponieważ parametr ma StringExtensionswartość , nazwa pliku i nazwa klasy pozostają niezmienione, jeśli parametr nie zostanie określony podczas korzystania z szablonu. Gdy zostanie określona wartość, na przykład dotnet new stringext -ClassName MyExts, nazwa pliku zostanie zmieniona na MyExts.cs , a nazwa klasy zostanie zmieniona na MyExts.

Aby zobaczyć, jakie parametry są dostępne dla szablonu, użyj -? parametru o nazwie szablonu:

dotnet new stringext -?

Spowoduje to wygenerowanie następujących danych wyjściowych:

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

Teraz, gdy masz prawidłowy plik .template.config/template.json , szablon jest gotowy do zainstalowania. W terminalu przejdź do folderu extensions i uruchom następujące polecenie, aby zainstalować szablon znajdujący się w bieżącym folderze:

  • W systemie Windows: dotnet new install .\
  • W systemie Linux lub macOS: dotnet new install ./

To polecenie zwraca listę zainstalowanych szablonów, które powinny zawierać Twoje.

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

Testowanie szablonu elementu

Po zainstalowaniu szablonu elementu przetestuj go.

  1. Przejdź do folderu testowego.

  2. Utwórz nową aplikację konsolową za pomocą dotnet new consolepolecenia , która generuje projekt roboczy, który można łatwo przetestować za dotnet run pomocą polecenia .

    dotnet new console

    Dane wyjściowe są podobne do poniższych.

    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. Uruchom projekt przy użyciu następującego polecenia.

    dotnet run

    Uzyskasz następujące dane wyjściowe.

    Hello, World!

  4. Uruchom polecenie dotnet new stringext , aby wygenerować plik StringExtensions.cs na podstawie szablonu.

    dotnet new stringext

    Uzyskasz następujące dane wyjściowe.

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

  5. Zmień kod w pliku Program.cs , aby odwrócić "Hello, World!" ciąg za pomocą metody rozszerzenia dostarczonej przez szablon.

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

    Uruchom ponownie program i sprawdź, czy wynik jest odwrócony.

    dotnet run

    Uzyskasz następujące dane wyjściowe.

    !dlroW ,olleH

Gratulacje! Utworzono i wdrożono szablon elementu przy użyciu platformy .NET. W ramach przygotowań do następnej części tej serii samouczków odinstaluj utworzony szablon. Pamiętaj, aby usunąć wszystkie pliki i foldery w folderze testowym. Spowoduje to powrót do czystego stanu gotowego do następnej części tej serii samouczków.

Odinstalowywanie szablonu

W terminalu przejdź do folderu rozszerzeń i uruchom następujące polecenie, aby odinstalować szablony znajdujące się w bieżącym folderze:

  • W systemie Windows: dotnet new uninstall .\
  • W systemie Linux lub macOS: dotnet new uninstall ./

To polecenie zwraca listę odinstalowanych szablonów, które powinny zawierać Twoje.

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

W dowolnym momencie możesz użyć dotnet new uninstall polecenia , aby wyświetlić listę zainstalowanych pakietów szablonów, w tym dla każdego pakietu szablonu polecenie , aby je odinstalować.

Następne kroki

W tym samouczku utworzono szablon elementu. Aby dowiedzieć się, jak utworzyć szablon projektu, kontynuuj tę serię samouczków.

Tworzenie szablonu projektu