Úvodná stránka -> Visual Studio -> Tvoríme snippety pre Visual Studio (16.10.2019)

Tvoríme snippety pre Visual Studio

V článku si povieme niečo o code snippetoch pre Visual Studio a ukážeme si aj praktické úkažky ich tvorby.

Jednou z mnohých customizácii ktoré nám Visual Studio (VS) ponúka, sú aj tzv. snippety.

V podstate sa jedná o malé útržky opakovateľne použiteľného zdrojového kódu, ktoré je možné behom okamihu vložiť do existujúceho projektu, čím si zefektívniť prácu.

Podľa spôsobu ich použitia rozlišujeme dva druhy snippetov:

1. Expansion snippet - jeho obsah sa vloží na zvolené miesto v editore kódu.

2. Surround-with snippet - zapracuje zvolenú časť zdrojového kódu do svojho obsahu.

Základná konštrukcia

Bez ohľadu na druh snippetu ide vždy len o XML súbor v predpísanej štruktúre a príponou .snippet.
Základná štruktúra vyzerá nasledovne:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title></Title>
            <Author></Author>
            <Description></Description>
            <Shortcut></Shortcut>
        </Header>
        <Snippet>
            <Code Language="">
                <![CDATA[]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

Sami vidíte, že štruktúra je jednoduchá a ľahko pochopiteľná. Súbor obsahuje hlavičku, kde sa definujú základné informácie o snippete (povinný je len element Title) a kód snippetu. Element Shortcut je relevantný len pre expansion snippety, viac si o ňom povieme trochu neskôr.

V elemente Code vidíme atribút Language, označujúci programovací jazyk, pre ktorý je snippet určený. Podľa oficiálnej dokumentácie (viď. časť použité zdroje nižšie) môže obsahovať hodnoty: VB, CSharp, CPP, XML, JavaScript, TypeScript, SQL alebo HTML. Obsahom elementu je útržok zdrojového kódu, ktorý má náš snippet na zvolené miesto vkladať.

Tu je však dôležité myslieť na to, že zdrojový kód môže obsahovať aj znaky nepovolené v XML formáte, a preto ho budeme uvádzať pomocou <![CDATA[ ]]>.

Expansion snippets

Expansion snippety sa vkladajú priamo na zvolené miesto v už existujúcom kóde projektu. To je možné pomocou kontextového (rightclick) menu a voľbe "Insert Snippet" (prípadne "Snippet -> Insert Snippet"), alebo priamym zadaním jeho skratky a následným opakovaným stlačením tabulátora. Vyskúšať si to môžeme priamo vo VS na ľubovoľnej C# aplikácii, kde v tele ktorejkoľvek metódy napíšeme slovo „for“ a dva razy stlačíme tabulátor (bez medzery za slovom „for“).

VS nám aicky doplní nasledujúci kód:

for (int i = 0; i < length; i++)
{

}

V tomto prípade nejde len o jednoduché vloženie kódu. Kurzor editora sa aicky presunie do pridaného kódu, kde vyznačí identifikátor premennej. Akákoľvek zmena, ktorú v podobne vyznačenej časti kódu vykonáme, sa aicky premietne do zvyšku vloženého kódu a to ihneď po stlačení tabulátora.

Ak je k dispozícii ďalšia, podobne aktívna časť kódu (v našom prípade „length“), editor nás na ňu aicky presmeruje. Týmto spôsobom sa novovložený kód snippetu veľmi rýchlo prispôsobí našim potrebám. Okrem programového kódu (C#, VB.NET, JavaScript, ... ) nájdeme podobné snippety aj pre HTML, XML a SQL.

Podobne fungujúci snippet by sme mohli zadefinovať nasledovne:

Test.snippet

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>Môj testovací snippet</Title>
            <Author>Codeblog.sk</Author>
            <Description>Codeblog.sk test snippet</Description>
            <Shortcut>test</Shortcut>
        </Header>
        <Snippet>
            <Code Language="CSharp">
                <![CDATA[static void Test()
                {
                Console.WriteLine("Test!");
                Console.Read();
                }]]>
            </Code>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

Jedná sa o plne funkčný snippet a nič nám nebráni, aby sme si ho otestovali. Skopírujeme ho do priečinka %userprofile%\Documents\Visual Studio XXXX\Code Snippets\Visual C#\My Code Snippets (kde XXXX je verzia vášho VS), prípadne ho naimportujeme cez Code Snippets Manager, dostupný po stlačení klávesovej skratky Ctrl + K, Ctrl + B.

Zvyčajne nie je potrebný reštart VS a editor kódu nám ho začne ponúkať. Kdekoľvek v ňom napíšeme skratku (definovanú v elemente Shortcut) a dvakrát stlačíme tabulátor, dôjde k pridaniu nami zadefinovaného kódu (statickej metódy Test).

Zameniteľné časti

Snippet for, ktorý sme si v úvode ukázali, nebol len statickým kusom zdrojového kódu, ale umožňoval aj úpravu niektorých jeho častí. Túto vlastnosť môže mať aj náš snippet, postačí len pár zmien.

Prvým krokom bude označenie relevantných miest v kóde snippetu pomocou značky (alebo, ak chcete placeholdera) vytvorenej použitím $ (dolára) v tvare $identifikator$. Jednou značkou je možné označiť viac miest, kde sa má jej aktuálna hodnota premietnuť:

Test.snippet

...

<Code Language="CSharp">
<![CDATA[static void $Name$()
{
    Console.WriteLine("$Name$!");
    Console.Read();
}]]>
</Code>

...

Ďalej ju musíme deklarovať aj na vyššej úrovni, konkrétne v novo pridanej časti Declarations. Aby s ňou vedelo VS pracovať, potrebujeme zadať jej identifikátor(ID), stručnú nápovedu (ToolTip) a ideálne aj jej predvolenú hodnotu (Default).

Test.snippet

...

<Snippet>
    <Code Language="CSharp">
    ...
    </Code>
    <Declarations>
        <Literal>
            <ID>Name</ID>
            <ToolTip>Názov metódy.</ToolTip>
            <Default>Test</Default>
        </Literal>
    </Declarations>
</Snippet>

...

Import požadovaných závislostí

V prípade, ak by kód nášho snippetu pracoval s triedami, ktoré nepochádzajú zo štandardne importovaných namespace, mali by sme na túto skutočnost VS upozorniť.

Slúži na to časť Imports, kde vyžadované importy jednoducho vymenujeme.

Test.snippet

<Snippet>
    <Code Language="CSharp">
    ...
    </Code>
    <Declarations>
        ...
    </Declarations>
    <Imports>
        <Import>
            <Namespace>System.Data</Namespace>
        </Import>
        <Import>
            <Namespace>System.Net</Namespace>
        </Import>
    </Imports>
</Snippet>

Aj keď ich v našom prípade reálne nepotrebujeme, VS sa postará o ich aické vloženie do časti using, ak ich ešte cieľový kód neobsahuje.

Surround-with snippet

Spôsob fungovania ukážeme na zabudovanom snippete try. Označíme niekoľko riadkov kódu v ľubovoľnej metóde, stlačíme klávesovú skratku Ctrl + K, Ctrl + S a zo zoznamu Visual C# vyberieme voľbu try. Zvolený kód sa aicky zaobalí do try-catch bloku a kurzor sa presunie do zátvorky catch.

Po technickej stránke sa štruktúra surround-with snippetov od ich expansion náprotivkov veľmi nelíši. Hlavným rozdielom je použitie kľúčový slov (vo forme značiek) $selected$ a $end$ v jeho kóde.

Značkou $selected$ zvolíme miesto, kam sa má označený kód editora vložiť. Druhá spomenutá $end$ označuje miesto, kam sa má kurzor editora po vložení presunúť. Značku $end$ je možné použiť aj pri expansion snippete, avšak len v prípade, ak neobsahuje žiadne iné dynamické časti.

Ak by sme podobné správanie, ake má zabudovaný snippet, chceli dosiahnuť aj my, mohlo by to vyzerať nasledovne:

CustomTry.snippet

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <CodeSnippet Format="1.0.0">
        <Header>
            <Title>Custom try snippet</Title>
            <Author>Codeblog.sk</Author>
            <Description>Codeblog.sk custom try snippet</Description>
        </Header>
        <Snippet>
            <Code Language="CSharp">
                <![CDATA[try {
                    $selected$
                }
                catch (Exception e)
                {
                    Debug.WriteLine("Exception: " + e.Message);
                    $end$
                }
                ]]>
            </Code>
            <Imports>
                <Import>
                    <Namespace>System.Diagnostics</Namespace>
                </Import>
            </Imports>
        </Snippet>
    </CodeSnippet>
</CodeSnippets>

Náš vylepšený try snippet, popri klasickom zápise try-catch blokov, pridáva aj volanie Debug.WriteLine z namespace System.Diagnostics.

Záverom

Ak vás tvorba snippetov pre VS zaujala, určite sa pozrite aj na oficiálnu dokumentáciu (odkaz v časti Použité zdroje), kde získate podrobnejší prehľad o dostupných možnostiach. Ako inšpirácia vám určite poslúžia aj snippety štandardne dodávané spolu s VS. Nájdete ich priamo v inštalačnom priečinku VS, konkrétne v podpriečinku VC#\Snippets\1033\Visual C#.

Snippety vytvorené v tomto článku nájdete aj na našom > GitHube <.