VS 2005+

Visual Studio Code Snippet Types

by Richard Carr, published at http://www.blackwasp.co.uk/VSSnippetTypes.aspx

Visual Studio's code snippets feature allows the fast insertion of boilerplate code. Two styles of custom code snippet can be created. Expansion snippets insert code at the cursor position. SurroundsWith snippets add code before and after the selection.

Code Snippets

In a previous article I described how you can create your own basic code snippets to allow you to insert commonly used code at the current cursor position. This was followed by an article that explained how to improve those snippets with the use of replacements, which define placeholders to be replaced with Visual Studio's assistance.

Each of these articles showed an example snippet with a defined snippet type but did not describe the types from which you may choose. In this article we will investigate the two available styles, known as Expansion and SurroundsWith snippets.

Expansion Snippets

The previous code snippet articles provided examples of expansion snippets. These insert snippet code at the current text cursor, or caret, location. The type can be used alone or combined with the SurroundsWith style.

SurroundsWith Snippets

SurroundsWith code snippets allow code to be inserted before and after the current selection in the code editor. They are useful when you wish to introduce a code structure, such as a for loop, that surrounds existing code. To demonstrate a typical snippet, select some code in a C# editor. Right-click the highlighted code and choose "Insert Snippet", or press Ctrl-K,B to display the available snippets. Select "Visual C#" and then "for". This inserts a for loop around the selected code and provides placeholders that assist you in setting the name of the loop control variable and the length of the loop.

Creating a SurroundsWith Code Snippet

As the previous articles included expansion snippets we will not create a further example here. Instead, we will create a SurroundsWith snippet that can also be used as an expansion snippet. It will allow a section of code to be commented out, adding a task list comment and providing replacements for the date and the developer's name.

There are two key differences between this example and those we have seen before. Firstly, the SnippetTypes element includes two type definitions. One SnippetType element specifies that the snippet can be used to surround selected code and the other allows the code to be inserted at the caret position.

The second difference is the introduction of two new placeholders in the Code section. The $selected$ placeholder represents the code that is selected before the snippet is inserted. Code before this marker will appear before the original selection and code after the placeholder will be inserted after the selection. The second placeholder appears as $end$. This determines the position of the caret after the snippet is inserted and all replacements are made. In our snippet the caret will be placed below the comment header but above the original selection.

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippet Format="1.0.0"
    xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <Header>
        <Title>Comment Out Code</Title>
        <Author>BlackWasp</Author>
        <Shortcut>cout</Shortcut>
        <Description>Comments out a section of code</Description>
        <SnippetTypes>
            <SnippetType>SurroundsWith</SnippetType>
            <SnippetType>Expansion</SnippetType>
        </SnippetTypes>
    </Header>
    <Snippet>
        <Declarations>
            <Literal>
                <ID>RemovedDate</ID>
                <ToolTip>Enter date of removal</ToolTip>
                <Default>[Insert Date]</Default>
            </Literal>
            <Literal>
                <ID>Developer</ID>
                <ToolTip>Enter your name</ToolTip>
                <Default>[My Name]</Default>
            </Literal>
        </Declarations>
        <Code Language="CSharp">
            <![CDATA[// TODO: Review code below and consider for removal

    /*  Code removed on $RemovedDate$ by $Developer$
        $end$

        $selected$
    */]]>
        </Code>
    </Snippet>
</CodeSnippet>

Save and register the snippet in Visual Studio and try inserting it both with and without code selected. Note the position of selected code after insertion and the location of the caret when you press Enter after providing the date and the developer name.