Jim's Blog Ramblings about novels, comics, programming, and other geek topics

Visual Studio macro to add file headers

Microsoft's StyleCop analyzes C# source code to enforce a set of style and consistency rules. It can be run from inside of Visual Studio or integrated into an MSBuild project.

One of these rules is #SA1633. This rule requires that each of your files have a file header that contains a copyright XML element. Of course, you can disable this rule if you want through StyleCop settings. But just in case you have a similar rule at your work (or your own personal rule) or need to adhere to this rule, I'll describe the situation and provide the macro below.

SA1633: FileMustHaveHeader

Cause

A C# code file is missing a standard file header.

Rule Description

A violation of this rule occurs when a C# source file is missing a file header. The file header must begin on the first line of the file, and must be formatted as a block of comments containing Xml, as follows:

//-----------------------------------------------------------------------
// <copyright file="NameOfFile.cs" company="CompanyName">
//     Company copyright tag.
// </copyright>
//-----------------------------------------------------------------------

The rule means that you need a header that looks like the above XML comment code. I've made a simple Visual Studio Macro using VBA to perform the insertion of the code.

Adding the Macro:

1. Click "Tools" menu
2. Click "Macros" menu item
3. Click "Macros IDE..." menu choice
4. Right click on "My Macros"
5. Click "Add" menu item
6. Choose "Add Module..." (a module is a VB term for a static C# class with all static members)
7. Enter the name of "AddClassHeaderText" (or whatever you want to name your module)
8. Paste the code below and update any variables to match your organization or name

Sub FileHeader()
   Dim doc As Document
   Dim docName As String
   Dim companyName As String = "Company Name"
   Dim authorName As String = "My Name"
   Dim copyrightText As String = "Copyright statement"

   ' Get the name of this object from the file name
   doc = DTE.ActiveDocument

   ' Get the name of the current document
   docName = doc.Name

   ' Set selection to top of document
   DTE.ActiveDocument.Selection.StartOfDocument()
   DTE.ActiveDocument.Selection.NewLine()

   ' Write first line
   DTE.ActiveDocument.Selection.LineUp()
   DTE.ActiveDocument.Selection.Text = "// --------------------------------"
   DTE.ActiveDocument.Selection.NewLine()

   ' Write copyright tag
   DTE.ActiveDocument.Selection.Text = "// <copyright file=""" +
       docName + """ company=""" + companyName + """>"
   DTE.ActiveDocument.Selection.NewLine()
   DTE.ActiveDocument.Selection.Text = "//     " + copyrightText
   DTE.ActiveDocument.Selection.NewLine()
   DTE.ActiveDocument.Selection.Text = "// </copyright>"

   ' Write author name tag (optional)
   DTE.ActiveDocument.Selection.NewLine()
   DTE.ActiveDocument.Selection.Text = "// <author>" +
       authorName + "</author>"
   DTE.ActiveDocument.Selection.NewLine()

   ' Could write <email></email> tag
   ' Could write <date></date> tag
   ' Could write <summary></summary> tag

   ' Write last line
   DTE.ActiveDocument.Selection.Text = "// ---------------------------------"
   DTE.ActiveDocument.Selection.NewLine()
End Sub

* Note: You'll need to remove those two line wraps above. The code was given hard line breaks in the middle of the statements for better blog formatting.

Macro Results

This creates the following text inserted into the top of the source code document:

// ---------------------------------
// <copyright file="MyClass.cs" company="My Company">
//     Copyright statement
// </copyright>
// <author>My Name</author>
// ---------------------------------

Adding Macro to Toolbar

To add this to a toolbar in your IDE:

1. Click "Tools" menu
2. Click "Customize..." menu choice
3. Activate "Commands" tab
4. Choose "Macros" category
5. Select "MyMacros.AddClassHeaderText.FileHeader" (or whatever you named it)
6. Drag command to your toolbar.
7. You can customize the icon, text, visibility of text/icon, etc. by right clicking on the toolbar button
8. Close customization dialog

Improvements

You could further enhance this macro to get the currently logged in user name and company name without needing to hard code those values into the macro.