Kurz: Vytvoření šablony položky

  • Článek

Pomocí .NET můžete vytvářet a nasazovat šablony, které generují projekty, soubory a prostředky. Tento kurz je součástí série, která vás naučí, jak vytvořit, nainstalovat a odinstalovat šablony pro použití s příkazem dotnet new .

Dokončenou šablonu si můžete prohlédnout v úložišti .NET Samples Na GitHubu.

Tip

Šablony položek se nezobrazují v dialogovém okně Přidat>novou položku v sadě Visual Studio.

V této části série se naučíte:

  • Vytvořte třídu pro šablonu položky.
  • Vytvořte složku a soubor konfigurace šablony.
  • Nainstalujte šablonu z cesty k souboru.
  • Otestujte šablonu položky.
  • Odinstalujte šablonu položky.

Požadavky

  • .NET SDK 7.0.100 nebo novější verze.

    Referenční článek vysvětluje základy šablon a jejich sestavení. Některé z těchto informací se zde opakují.

  • Otevřete terminál a přejděte do složky, do které budete šablony ukládat a testovat.

Důležité

Tento článek je napsán pro .NET 7. Platí ale také pro .NET 6 a předchozí verze s jedním rozdílem: dotnet new Syntaxe se liší. Příkazy list, , installsearcha uninstall dílčí příkazy by měly být --list, --search--install, a --uninstall možnosti, v uvedeném pořadí.

Například příkaz dotnet new install v .NET 7 se stane dotnet new --install v .NET 6. dotnet new --help Pomocí příkazu zobrazíte seznam všech možností a dílčích příkazů.

Vytvoření požadovaných složek

Tato série používá "pracovní složku", ve které je zdroj šablony obsažen a "testovací složka" použitá k otestování šablon. Pracovní složka a testovací složka by měly být ve stejné nadřazené složce.

Nejprve vytvořte nadřazenou složku, na názvu nezáleží. Pak vytvořte dvě podsložky pojmenované jako pracovní a testovací. Uvnitř pracovní složky vytvořte podsložku s názvem obsah.

Struktura složek by měla vypadat takto.

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

Vytvoření šablony položky

Šablona položky je konkrétní typ šablony, která obsahuje jeden nebo více souborů. Tyto typy šablon jsou užitečné, když už projekt máte a chcete vygenerovat jiný soubor, například konfigurační soubor nebo soubor kódu. V tomto příkladu vytvoříte třídu, která do typu řetězce přidá rozšiřující metodu.

V terminálu přejděte do složky working\content a vytvořte novou podsložku s názvem rozšíření.

working
└───content
    └───extensions

Přejděte do složky rozšíření a vytvořte nový soubor s názvem StringExtensions.cs. Otevřete soubor v textovém editoru. Tato třída poskytne rozšiřující metodu s názvem Reverse , která obrátí obsah řetězce. Vložte následující kód a soubor uložte:

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 dokončení obsahu šablony je dalším krokem vytvoření konfigurace šablony.

Vytvoření konfigurace šablony

V této části kurzu se složka šablony nachází v pracovní\content\extensions.

Šablony jsou rozpoznány rozhraním .NET, protože mají speciální složku a konfigurační soubor, který existuje v kořenové složce šablony.

Nejprve vytvořte novou podsložku s názvem .template.config a zadejte ji. Pak vytvořte nový soubor s názvem template.json. Struktura složek by měla vypadat takto:

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

Otevřete soubor template.json pomocí svého oblíbeného textového editoru a vložte následující kód JSON a uložte ho.

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

Tento konfigurační soubor obsahuje všechna nastavení šablony. Můžete vidět základní nastavení, například name a shortName, ale existuje také tags/type hodnota, která je nastavena na item. Tím se šablona kategorizuje jako šablona "item". Typ šablony, kterou vytvoříte, není nijak omezen. Tyto item hodnoty project jsou běžné názvy, které .NET doporučuje, aby uživatelé mohli snadno filtrovat typ šablony, kterou hledají.

Položka classifications představuje sloupec značek , který vidíte při spuštění dotnet new a získání seznamu šablon. Uživatelé také můžou vyhledávat na základě značek klasifikace. Nezaměňujte tags vlastnost v souboru template.json se seznamem classifications značek. Jsou to dva různé koncepty, které jsou bohužel pojmenovány stejně. Úplné schéma pro soubor template.json se nachází v úložišti schémat JSON a je popsáno v referenčních informacích pro template.json. Další informace o souboru template.json najdete na wikiwebu šablon dotnet.

Část symbols tohoto objektu JSON slouží k definování parametrů, které lze použít v šabloně. V tomto případě je definovaný jeden parametr . ClassName Definovaný parametr obsahuje následující nastavení:

  • type - Toto je povinné nastavení a musí být nastaveno na parameter.
  • description - Popis parametru, který se vytiskne v nápovědě k šabloně.
  • datatype – Typ dat hodnoty parametru při použití parametru.
  • replaces – Určuje textovou hodnotu, která by se měla nahradit ve všech souborech šablony hodnotou parametru.
  • fileRename - Podobně jako replacestato hodnota určuje textovou hodnotu, která se nahradí v názvech všech souborů šablony hodnotou parametru.
  • defaultValue – Výchozí hodnota tohoto parametru, pokud uživatel parametr nezadá.

Při použití šablony může uživatel zadat hodnotu parametru ClassName a tato hodnota nahradí všechny výskyty StringExtensions. Pokud není zadaná hodnota, použije se defaultValue . Pro tuto šablonu existují dva výskyty StringExtensions: soubor StringExtensions.cs a třída StringExtensions. Vzhledem k tomu, že defaultValue parametr je StringExtensions, název souboru a název třídy zůstávají beze změny, pokud parametr není zadán při použití šablony. Pokud je zadána hodnota, například dotnet new stringext -ClassName MyExts, soubor je přejmenován MyExts.cs a třída je přejmenována na MyExts.

Pokud chcete zjistit, jaké parametry jsou pro šablonu k dispozici, použijte -? parametr s názvem šablony:

dotnet new stringext -?

Výsledkem je následující výstup:

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

Teď, když máte platný soubor .template.config/template.json , je vaše šablona připravená k instalaci. V terminálu přejděte do složky rozšíření a spuštěním následujícího příkazu nainstalujte šablonu umístěnou v aktuální složce:

  • Ve Windows: dotnet new install .\
  • V Linuxu nebo macOS: dotnet new install ./

Tento příkaz vypíše seznam nainstalovaných šablon, které by měly zahrnovat vaše.

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

Otestování šablony položky

Teď, když máte nainstalovanou šablonu položky, ji otestujte.

  1. Přejděte do testovací složky.

  2. Vytvořte novou konzolovou aplikaci, dotnet new consolekterá vygeneruje pracovní projekt, který můžete snadno testovat pomocí dotnet run příkazu.

    dotnet new console

    Zobrazí se výstup podobný následujícímu.

    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. Spusťte projekt pomocí následujícího příkazu.

    dotnet run

    Zobrazí se následující výstup.

    Hello, World!

  4. Spuštěním dotnet new stringext vygenerujte ze šablony soubor StringExtensions.cs .

    dotnet new stringext

    Zobrazí se následující výstup.

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

  5. Změňte kód v souboru Program.cs tak, aby se řetězec převrácel "Hello, World!" metodou rozšíření poskytovanou šablonou.

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

    Spusťte program znovu a podívejte se, že je výsledek obrácený.

    dotnet run

    Zobrazí se následující výstup.

    !dlroW ,olleH

Blahopřejeme. Vytvořili jste a nasadili šablonu položky pomocí .NET. V rámci přípravy na další část této série kurzů odinstalujte šablonu, kterou jste vytvořili. Nezapomeňte také odstranit všechny soubory a složky v testovací složce. Tím se vrátíte k čistému stavu připravenému na další část této série kurzů.

Odinstalace šablony

V terminálu přejděte do složky rozšíření a spuštěním následujícího příkazu odinstalujte šablony umístěné v aktuální složce:

  • Ve Windows: dotnet new uninstall .\
  • V Linuxu nebo macOS: dotnet new uninstall ./

Tento příkaz zobrazí seznam odinstalovaných šablon, které by měly zahrnovat vaše.

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

Kdykoli můžete použít dotnet new uninstall seznam nainstalovaných balíčků šablon, včetně každého balíčku šablony, který příkaz odinstaluje.

Další kroky

V tomto kurzu jste vytvořili šablonu položky. Pokud chcete zjistit, jak vytvořit šablonu projektu, pokračujte v této sérii kurzů.

Vytvoření šablony projektu