How to Customize the XML Comments that are inserted by the Visual Basic Code Editor?

Article
05/24/2010

Visual Basic XML Comments were first introduced in Visual Studio 2005. They can be used to create documentation for your project, and to provide a rich IDE experience for others using your code. For more information on XML Comments, please read my full article in MSDN Magazine here. This blog post focuses on the specific steps necessary to customize Visual Basic XML Comments.

XML Comments are used to comment members. When you type three single-quotation marks ('") immediately above the member definition and press Enter, the Visual Basic editor inserts an XML skeleton for you.

Before:

'''
Function RegKeyExists(ByVal regKey As String) As Boolean
Dim exists As Boolean = False
Try
...

After:

''' <summary>
'''
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
Dim exists As Boolean = False
Try
...

There is a specific default XML skeleton that gets inserted for each kind of member. However you may want to change the default XML Comments to match your company’s guidelines, or your own personal preferences. In order to help with these scenarios, Visual Basic provides a way to customize the default XML skeleton. Here’s how.

Create a new XML file called VBXMLDoc.xml, and copy the following code into that file. You can also download this file as an attachment to this post.

XML text to copy into VBXMLDoc.xml:

<?xml version="1.0" encoding="utf-8" ?>
<XMLDocCommentSchema>

</XMLDocCommentSchema>

Save VBXMLDoc.xml to the appropriate location below, based on your version of Windows and Visual Studio. Please replace ‘<user>’ in the path with your own username.

Where to save VBXMLDoc.xml

VS 2005	VS 2008	VS 2010	Windows XP	Windows Vista or Windows 7	Path
X			X		C:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\8.0
X				X	C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\8.0
	X		X		C:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\9.0
	X			X	C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\9.0
		X	X		C:\Documents and Settings\<user>\Application Data\Microsoft\VisualStudio\10.0
		X		X	C:\Users\<user>\AppData\Roaming\Microsoft\VisualStudio\10.0

When VBXMLDoc.xml is present, Visual Studio will use the definitions from that file, instead of the built in defaults, when inserting the XML Comment skeletons into the IDE. The version of VBXMLDoc.xml above (and attached) contains the built in defaults. To change the defaults, find the code element type you are interested in, and edit that element in the file. In this example, let’s change the XML skeleton that gets inserted for Function.

Default XML tags for Function

The Template element’s children represent the XML elements that will be inserted in the XML skeleton for a Function. The CompletionList element’s children represent the suggestions that will appear in intelliSense upon typing a left angle bracket (<) above a Function.

Let’s make the following changes:

· Remove the remarks element from both the default skeleton and intelliSense.
· Add an author element to both the default skeleton and intelliSense.
· Add a history element to intelliSense.

Here’s what the Function element in VBXMLDoc.xml will look like when we’re done.

Customized XML tags for Function

At this point you need to close and re-open Visual Studio, in order for VBXMLDoc.xml to get picked up. After restarting, the XML Comments automatically inserted above Function will include an author element instead of remarks.

Customized XML Skeleton for Function

    ''' <summary>
    '''
    ''' </summary>
    ''' <param name="regKey"></param>
    ''' <returns></returns>
    ''' <author></author>
    Function RegKeyExists(ByVal regKey As String) As Boolean
        Dim exists As Boolean = False
        Try
            If My.Computer.Registry.CurrentUser.OpenSubKey(regKey) IsNot Nothing Then
                exists = True
            End If
        Finally
            My.Computer.Registry.CurrentUser.Close()
        End Try
    End Function

In the image below, we can also see that a history element now appears in the list of options XML intelliSense offers for a function. (Although we also added an author element to appear in intelliSense, it doesn’t here because there is already an author element in the XML.)

Customized XML IntelliSense for Function

Please also note that while it is possible to add XML elements to the template, it is not possible to add XML values. Thus, you can make the IDE insert <author></author> by default; however, it is not possible to make it insert <author>Microsoft Corporation</author>.

VBXMLDoc.xml

How to Customize the XML Comments that are inserted by the Visual Basic Code Editor?

Additional resources