Code Snippet – Schema Description


I’m working on posting the XSD and will update this post to link to it once I’ve found a place that I can put it. 


CodeSnippet


The <CodeSnippet> tag is the root element for the schema.  It has a format attribute which specifies the schema version/format of the codesnippet.  Whidbey will attempt to process any codesnippet block with a 1.x.x format, ignoring tags it doesn’t explicitly understand.  Future versions will contain logic to support down-level formats with the same major version, degrading gracefully in the absence of new tags.  This tag was ignored in Beta 1 but is required for Beta 2.


The <Code Snippet> tag must contain a <Header> tag and a <Snippet> tag.


Header


This tag contains general information about the snippet which is surfaced in the UI. This tag is required.  This tag must contain a Title tag and may contain Author, Description, HelpUrl, SnippetTypes and Keyword tags.


Title


The <Title> tag contains the friendly name of the code snippet.  It is used when displaying a list of snippets to the user(Intellisense, Code Snippet Manager, etc).  This is a required tag.


Author


Optional string indicating the name/company that authored the snippet.  This is displayed in the Code Snippet Manager and may be used by online content providers.


Description


Optional value containing additional descriptive information about the contents of the snippet.  It is used to provide the tooltip for the Code Snippet when selected in Intellisense and in the Code Snippet Manager.


HelpUrl


Optional value containing a URL for more information about the Code Snippet.  This will be inserted the following comment in the code: “For more information see: http://”.  Currently this tag is only supported by VB.


Snippet Types


Determines how the Code Snippet may be inserted. SurroundsWith allows the Code Snippet to be placed around a selection.  Expansion allows the snippet to be inserted at the cursor. E.g.
<SnippetTypes>
<SnippetType>SurroundsWith</SnippetType>
<SnippetType>Expansion</SnippetType>
</SnippetTypes>



If this section is omitted, a Code Snippet is valid in all cases.


Keywords


Represents a set of keyword.  Although this is currently used by Visual Studio, it represents a standard way of keywording Code Snippets for Online Content Providers.  E.g. To add the keywords Text Files and My Documents to the Code Snippet use the following syntax:


    <Keywords>


        <Keyword>Text Files</Keyword>


      <Keyword>My Documents</Keyword>


    </Keywords>


Snippet


The <Snippet> tag contains the code that will be inserted, any changes necessary to the project and describes the replaceable elements.


References


Some Code Snippets make use of classes and members located in other dlls such as the .NET Framework this tag will automatically add the reference to the given assembly when the Code Snippet is inserted.  Currently, this feature is only supported by Visual Basic. E.g.


    <References>


      <Reference>


        <Assembly>System.dll</Assembly>


        <Url />


      </Reference>


      <Reference>


            <Assembly>System,Version=1.0.0.1,Culture=neutral,PublicKeyToken=9b35aa32c18d4fb1</Assembly>


            <Url>http://www.microsoft.com</Url>


      </Reference>


     </References>




Imports


Code Snippets often will assume that certain types have been imported from namespaces.  This tag will automatically add the using or import statements to the current file when the Code Snippet is inserted.


Declarations


The declarations tag is the container for all of the literals and objects which make up the fields inside of a Code Snippet.


Literal


The literal defines the fields inside of the code block.  The ID is the identifier used to identify the literal inside of the code block.  The tooltip is the text which is shown when the user invokes a tooltip on that field.  Default is the text that is inserted into the field by default.  E.g.


            <Literal>


                <ID>name</ID>


                <ToolTip>Class name</ToolTip>


                <Default>MyClass</Default>


            </Literal>


 


 The C# and J# implementations of Code Snippets support the concept of functions which can execute pre-defined actions when users navigate to the fields.  In the following example, the cases literal calls into the C# function which generates all of the cases for a switch statement based on the value of the expression literal.  The Editable attribute determines whether users edit the field as a regular code snippet field.


 


            <Literal>


                <ID>expression</ID>


                <ToolTip>Expression to switch on</ToolTip>


                <Function>ListEnumVariables()</Function>


                <Default>enum_to_switch_on</Default>


            </Literal>


            <Literal Editable=false>


                <ID>cases</ID>


                <Function>GenerateSwitchCases($expression$)</Function>


                <Default>default:</Default>


            </Literal>


 


The current list of functions is: GenerateSwitchCases, ListVariablesOfType, ListEnumVariables, ClassName, SimpleTypeName.


 


Code



The code block contains the actual text that gets inserted into the editor.  The “Language” attribute determines what programming language the code snippet is valid for.  Currently the following languages are supported: “CSharp”, “JSharp”, “VB”.



The format tag defines how the literals are described in the code block.  If the format is “CData”, the literals are delimited using $.  E.g.
<![CDATA[for (int $index$ = 0; $index$ < $max$; $index$++)
{
$selected$ $end$
}]]>
The user may change the $ to another single character delimiter by specifying a delimiter attribute. E.g <code language=”csharp” format=”CData” delimiter=”@”>


If the format is “XML” the literals are delimited by XML tags. E.g.
for (int <Literal ID=index/>=0; <Literal ID=index/> &lt; <Literal ID=max/>; <Literal ID=index/>++)
{
<Literal ID=selected/> <Literal ID=end/>
}


If you have any questions/comments about the schema, please let me know.


Thanks,
-Sean Laberee


Comments (9)

  1. Keith Hill says:

    Just make sure we can put multiple <Code Language=""> elements in the same file. Also it would be nice if we could insert code for other languages like say <Code Language="Python"> … </Code> and not have VB or C# puke on it.

  2. Hi,

    CodeSnippets are really cool stuff! I’m using them here: http://blog.dotnetwiki.org/archive/2004/08/07/740.aspx

    Is there anyway to provide our own functions?

  3. One of the big new features of the Visual Studio 2005 release for the Editor team and for the language…

  4. Stan Kitsis says:

    IntroductionHow many times in your coding life have you had to write or copy-paste code that was almost…

  5. Stan Kitsis says:

    VS2005 introduced a new and very powerful feature called Code Snippets. A code snippet is an XML file (with a .snippet extension) that contains a chunk of code in which you can configure different parameters, reference assemblies, and use references and import statements. Think of them as templates that you can configure to meet your needs. The XML Editor supports this feature and also adds dynamically generated code snippets based on your XML Schemas.

  6. Stan Kitsis says:

    VS2005 introduced a new and very powerful feature called Code Snippets. A code snippet is an XML file (with a .snippet extension) that contains a chunk of code in which you can configure different parameters, reference assemblies, and use references and import statements. Think of them as templates that you can configure to meet your needs. The XML Editor supports this feature and also adds dynamically generated code snippets based on your XML Schemas.

  7. Articles says:

    XML Tools in Visual Studio 2008 Originally published in CoDe Focus 2007 – Vol. 4 – Issue 3 – Data Programmability