Walkthrough: Implementing Code Snippets
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at Walkthrough: Implementing Code Snippets.
You can create code snippets and include them in an editor extension so that users of the extension can add them to their own code.
A code snippet is a fragment of code or other text that can be incorporated in a file. To view all snippets that have been registered for particular programming languages, on the Tools menu, click Code Snippet Manager. To insert a snippet in a file, right-click where you want the snippet, click Insert Snippet or Surround With, locate the snippet you want, and then double-click it. Press TAB or SHIFT+TAB to modify the relevant parts of the snippet and then press ENTER or ESC to accept it. For more information, see Code Snippets.
A code snippet is contained in an XML file that has the .snippet file name extension. A snippet can contain fields that are highlighted after the snippet is inserted so that the user can find and change them. A snippet file also provides information for the Code Snippet Manager so that it can display the snippet name in the correct category. For information about the snippet schema, see Code Snippets Schema Reference.
This walkthrough teaches how to accomplish these tasks:
Create and register code snippets for a specific language.
Add the Insert Snippet command to a shortcut menu.
Implement snippet expansion.
This walkthrough is based on Walkthrough: Displaying Statement Completion.
Starting in Visual Studio 2015, you do not install the Visual Studio SDK from the download center. It is included as an optional feature in Visual Studio setup. You can also install the VS SDK later on. For more information, see Installing the Visual Studio SDK.
Typically, code snippets are associated with a registered language service. However, you do not have to implement a LanguageService to register code snippets. Instead, just specify a GUID in the snippet index file and then use the same GUID in the ProvideLanguageCodeExpansionAttribute that you add to your project.
The following steps demonstrate how to create code snippets and associate them with a specific GUID.
Create the following directory structure:
%InstallDir%\TestSnippets\Snippets\1033\
where %InstallDir% is the Visual Studio installation folder. (Although this path is typically used to install code snippets, you can specify any path.)
In the \1033\ folder, create an .xml file and name it TestSnippets.xml. (Although this name is typically used for a snippet index file, you can specify any name as long as it has an .xml file name extension.) Add the following text, and then delete the placeholder GUID and add your own.
<?xml version="1.0" encoding="utf-8" ?> <SnippetCollection> <Language Lang="TestSnippets" Guid="{00000000-0000-0000-0000-000000000000}"> <SnippetDir> <OnOff>On</OnOff> <Installed>true</Installed> <Locale>1033</Locale> <DirPath>%InstallRoot%\TestSnippets\Snippets\%LCID%\</DirPath> <LocalizedName>Snippets</LocalizedName> </SnippetDir> </Language> </SnippetCollection>
Create a file in the snippet folder, name it test
.snippet, and then add the following text:<?xml version="1.0" encoding="utf-8" ?> <CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet"> <CodeSnippet Format="1.0.0"> <Header> <Title>Test replacement fields</Title> <Shortcut>test</Shortcut> <Description>Code snippet for testing replacement fields</Description> <Author>MSIT</Author> <SnippetTypes> <SnippetType>Expansion</SnippetType> </SnippetTypes> </Header> <Snippet> <Declarations> <Literal> <ID>param1</ID> <ToolTip>First field</ToolTip> <Default>first</Default> </Literal> <Literal> <ID>param2</ID> <ToolTip>Second field</ToolTip> <Default>second</Default> </Literal> </Declarations> <References> <Reference> <Assembly>System.Windows.Forms.dll</Assembly> </Reference> </References> <Code Language="TestSnippets"> <![CDATA[MessageBox.Show("$param1$"); MessageBox.Show("$param2$");]]> </Code> </Snippet> </CodeSnippet> </CodeSnippets>
The following steps show how to register the code snippets.
To register code snippets for a specific GUID
Open the CompletionTest project. For information about how to create this project, see Walkthrough: Displaying Statement Completion.
In the project, add references to the following assemblies:
Microsoft.VisualStudio.TextManager.Interop
Microsoft.VisualStudio.TextManager.Interop.8.0
microsoft.msxml
In the project, open the source.extension.vsixmanifest file.
Make sure that the Assets tab contains a VsPackage content type and that Project is set to the name of the project.
Select the CompletionTest project and in the Properties window set Generate Pkgdef File to true. Save the project.
Add a static
SnippetUtilitiesclass to the project.In the SnippetUtilities class, define a GUID and give it the value that you used in the SnippetsIndex.xml file.
Add the ProvideLanguageCodeExpansionAttribute to the
TestCompletionHandlerclass. This attribute can be added to any public or internal (non-static) class in the project. (You may have to add ausingstatement for the Microsoft.VisualStudio.Shell namespace.)Build and run the project. In the experimental instance of Visual Studio that starts when the project is run, the snippet you just registered should be displayed in the Code Snippets Manager under the TestSnippets language.
The Insert Snippet command is not included on the shortcut menu for a text file. Therefore, you must enable the command.
To add the Insert Snippet command to the shortcut menu
Open the
TestCompletionCommandHandlerclass file.Because this class implements IOleCommandTarget, you can activate the Insert Snippet command in the QueryStatus method. Before you enable the command, check that this method is not being called inside an automation function because when the Insert Snippet command is clicked, it will display the snippet picker user interface (UI).
Build and run the project. In the experimental instance, open a file that has the .zzz file name extension and then right-click anywhere in it. The Insert Snippet command should appear on the shortcut menu.
This section shows how to implement code snippet expansion so that the snippet picker UI is displayed when Insert Snippet is clicked on the shortcut menu. A code snippet is also expanded when a user types the code-snippet shortcut and then presses TAB.
To display the snippet picker UI and to enable navigation and post-insertion snippet acceptance, use the M:Microsoft.VisualStudio.OLE.Interop.IOleCommandTarget.Exec(System.Guid,System.UInt32,System.UInt32,System.IntPtr,System.IntPtr) method. The insertion itself is handled by the OnItemChosen method.
The implementation of code snippet expansion uses legacy Microsoft.VisualStudio.TextManager.Interop interfaces. When you translate from the current editor classes to the legacy code, remember that the legacy interfaces use a combination of line numbers and column numbers to specify locations in a text buffer, but the current classes use one index. Therefore, if a buffer has three lines each of which has ten characters (plus a newline, which counts as 1 character), the fourth character on the third line is at position 27 in the current implementation, but it is at line 2, position 3 in the old implementation.
To implement snippet expansion
To the file that contains the
TestCompletionCommandHandlerclass, add the followingusingstatements.Make the
TestCompletionCommandHandlerclass implement the IVsExpansionClient interface.In the
TestCompletionCommandHandlerProviderclass, import the ITextStructureNavigatorSelectorService.Add some private fields for the code expansion interfaces and the IVsTextView.
In the constructor of the
TestCompletionCommandHandlerclass, set the following fields.To display the snippet picker when the user clicks the Insert Snippet command, add the following code to the Exec method. (To make this explanation more readable, the Exec() code that is used for statement completion is not shown; instead, blocks of code are added to the existing method.) Add the following block of code after the code that checks for a character.
If a snippet has fields that can be navigated, the expansion session is kept open until the expansion is explicitly accepted; if the snippet has no fields, the session is closed and is returned as
nullby the InvokeInsertionUI method. In the Exec method, after the snippet picker UI code that you added in the previous step, add the following code to handle snippet navigation (when the user presses TAB or SHIFT+TAB after snippet insertion).To insert the code snippet when the user types the corresponding shortcut and then presses TAB, add code to the Exec method. The private method that inserts the snippet will be shown in a later step. Add the following code after the navigation code that you added in the previous step.
Implement the methods of the IVsExpansionClient interface. In this implementation, the only methods of interest are EndExpansion and OnItemChosen. The other methods should just return S_OK.
Implement the OnItemChosen method. The helper method that actually inserts the expansions will be covered in a later step. The TextSpan provides line and column information, which you can get from the IVsTextView.
The following private method inserts a code snippet, based either on the shortcut or on the title and path. It then calls the InsertNamedExpansion method with the snippet.
You can test whether snippet expansion works in your project.
Build the solution. When you run this project in the debugger, a second instance of Visual Studio is instantiated.
Open a text file and type some text.
Right-click somewhere in the text and then click Insert Snippet.
The snippet picker UI should appear with a pop-up that says Test replacement fields. Double-click the pop-up.
The following snippet should be inserted.
MessageBox.Show("first"); MessageBox.Show("second");Do not press ENTER or ESC.
Press TAB and SHIFT+TAB to toggle between "first" and "second".
Accept the insertion by pressing either ENTER or ESC.
In a different part of the text, type "test" and then press TAB. Because "test" is the code-snippet shortcut, the snippet should be inserted again.