Dissecting Snippets (Matt Gertz)

The snippet feature is one of the features that I’m fondest of in Visual Basic.  It was another one of a handful of features that got discussed in a series of “What if…” meetings that Sam & I had during the “Whidbey” planning stages.  As I recall, the things that motivated it for Sam was demos, and for me it was macros.  Visual Studio already had the capability to allow users to drag text to the toolbox to be reused elsewhere in the code, a time-saver frequently used by program managers during demos, but the code would often need to be modified for different situations, often in ways that weren’t always so obvious.  Macros, which I was using quite a lot in my coding, could be a bit more flexible but harder to get to (unless you spent time setting up menus or buttons or whatnot), and their flexibility was totally dependent on how much time you wanted to put into the macro.  Distribution in either case was quite problematic.  Neither option was satisfactory to either of us, and we although we had some idea of how a UI to address this might look, we weren’t making much progress on it.  At the same time, however, Amanda had moved ahead with a concept called “ExStencil” which involved shared code templates, and it became very clear that Amanda’s direction was the right way to solve this problem.  We merged the different scenarios into her feature in which lines of text that could be saved with “variables” which could be filled in by the user when the snippet was inserted, and thus snippets were born. 

[Edit: I rewrote that last paragraph somewhat after the first posting — my brain had clearly been malfunctioning by forgetting the ExStencil work first time around.]

Using snippets is pretty easy.  You can access them in a couple of ways, by either right-clicking in code and choosing “Insert Snippets” to bring up the snippet menu, or just type “?” + “TAB” as a shortcut.  It’s then just a matter of navigating to the snippet you’re interested in.  Also, each snippet has a shortcut associated with it, so if you know that shortcut, you can just type it and press “TAB” to have it inserted.  (You can find out a snippet’s shortcut for “future information” by selecting it in the snippet menu – it’ll show up in the resulting tooltip.) Once the snippet is in, you can tab around the highlighted fields and fill in the information that’s specific to your application.

At the time we were working on developing snippets, we’d planned on having a built-in snippet editor as well (it even shipped as part of the first beta of VS2005), but the UI for it was pretty buggy and awkward, and so time constraints forced us to pull it from the product rather than fix it up.  (That was probably my most painful moment during that product cycle.)  Fortunately, the community stepped up, and a shared source snippet editor is available at http://msdn2.microsoft.com/en-us/vbasic/ms789085.aspx — check it out!

Even without the snippet editor, snippets aren’t too hard to understand or to build.  They use a fairly simple schema that can be found at http://msdn2.microsoft.com/en-us/library/ms171418(VS.80).aspx, and are stored in *.snippet files.  Let’s dissect one of the VS2005 snippets here.  The VB snippets live in your installation at c:Program FilesMicrosoft Visual Studio 8VBSnippets (your drive letter may vary).  Let’s take a look at the “appLog” snippet (formally called “Write to a Text File using ‘My’”), which adds the following code:

        My.Computer.FileSystem.WriteAllText( “TheFile.txt”, “TextContents”, False)


Opening it up in (for example) Notepad, you’ll note that it’s all written in XML, and starts out with typical XML goo which points the application back to our schema:

<?xml version=1.0?>

<CodeSnippets xmlns=http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet>

  <CodeSnippet Format=1.0.0>


The most interesting part in that section is the Format attribute.  The intention is that future versions of Visual Studio should be able to respond correctly for older snippets if the format for snippets ever changes.  

Having opened the CodeSnippet tag, we then move on to the basic information:


      <Title>Write to a Text file</Title>

      <Author>Microsoft Corporation</Author>

      <Description>Writes a message to the application event log.</Description>




This is all fairly self-explanatory.  The title will show up in the snippet menu, the description will show up in the tooltip, and “appLog” is the shortcut used when you want to insert the snippet without going through a menu (it will also show up in the tooltip).

We now progress to the actual snippet block:



which includes a number of parts such as these:
















The goal here is for the application to add the specified references and imports if they don’t already exist in the code.  (The ones shown above are going to be implied in the project already, but that won’t be the general case.)

The snippet block also contains a “Declarations” block, which is how the replaceable fields are defined.  In this snippet, there are three replaceable fields, contained as “Literals”:






          <ToolTip>The String variable that stores the filename to be written to.</ToolTip>







          <ToolTip>The text to be written to the file.</ToolTip>