In this blog post I am going to share how you can add a document header of xml comments with code file automatically. This is going to be an very interesting and helpful for all of you who are using styleCop to maintain coding standard. Actually extensive using of StyleCop helped me to think to make it automate. There are many tools available which can helps us in this case to do this automatically. But I always prefer let’s Visual studio do the job for me. Here I am going to share with you two different approaches to deal with this issue. Now it’s up to you which one to use.
Problem : StyleCop warning due to file header missing or mismatch for any “.cs” file.
Warning Message : “The file has no header,the header xml is invalid or the header is not located at the top of the file.”
Error No : SA1633
What I used to do?
I used to follow a dumb approach to save my bit of time. I save the template text in toolbox. And for each file, drag and drop the content from tool box and change the file name.
But do you think it was really a bad approach ? :) Only problem was every time I need to update file name manually. Which makes me to think for automation. Once again, I am discussing all these approaches as I am not using any tool make it automate.
Two Different approaches to automatically add document header
Well, we have two different approaches to automate this stuff.
1. Using Templates
2. Using Macro
1. Using Templates :
we can rewrite the Visual Studio code templates to customize the templates as per requirements. below is the default template for visual studio classes.
You can customize it as
Which will be generate all of your class as per the template once you update the new template with Visual Studio. Below, I am referring two good article from where you can see how you can customize the Visual Studio default templates, using which you can add document header automatically.
Problem with the template Approach :
While we are using template, we need to modify the same thing for Class,Interface as well as Code file . And another thing, if you want to do it for already created files, template approach won’t help you. So I have decided to go with an macro approach.
2. Using Macro : Macro can do this job very well. If you are very new in this macro world, here is an good article which says How To Create and Run Macro in Visual Studio .NET .
What I did here is, I created small macro which will add the file header automatically with proper file name. What you need to is to, just “Right Click > Add document header” or Just click on “Toolbar” button.
Below I am describing the bit details of implementation
Step 1: Open the Macro IDE from Tools > Macros > Macros IDE
Click on Macros IDE. It will open the VS macros IDE.
Inside macro window, Right Click on MyMacro and add New module as shown in below
Give the name as “AddDocumentHeader” ( It can be anything ). Copy Paste below code block as it is.
Imports System Imports EnvDTE Imports EnvDTE80 Imports EnvDTE90 Imports EnvDTE90a Imports EnvDTE100 Imports System.Diagnostics Public Module AddDocumentHeader Sub AddDocumentHeader() Dim document As Document Dim companyName As String = "My Company" Dim copyrightInformation As String = "Copyright statement. All right reserved" document = DTE.ActiveDocument Dim Matching As String = "// <copyright file=""" + document.Name + """ company=""" + companyName + """>" document.Selection.StartOfDocument() document.Selection.LineDown(True, 2) Dim content As String = document.Selection.Text 'Check for already hedader exist or not. Here I am only checking with Copyright Text with in second line of code. Dim MatchFound = System.Text.RegularExpressions.Regex.IsMatch(content, Matching) If (Not MatchFound) Then document.Selection.StartOfDocument() document.Selection.LineUp() document.Selection.Text = "// ----------------------------------------------------------------------" document.Selection.NewLine() document.Selection.Text = "// <copyright file=""" + document.Name + """ company=""" + companyName + """>" document.Selection.NewLine() document.Selection.Text = "// " + copyrightInformation document.Selection.NewLine() document.Selection.Text = "// </copyright>" document.Selection.NewLine() document.Selection.Text = "//" document.Selection.NewLine() document.Selection.Text = "// ------------------------------------------------------------------------" document.Selection.NewLine() End If End Sub End Module
Build and Save the file. You are done.
Now open your Any Visual Studio Project. Go to Tools > Macros > Macro Explorer. You will find, your created macro is there.
If you now click on Run, it will automatically add an document header with in the file with proper file name. :) . which is well expected . Cool !!
Let’s make it more handy and useful by putting it in “Context Menu” and “Tool Bar”.
Too add this macro in context menu, Go to Tools > Customize. Moved to Commands Tab > Context Menu and then select “Editor Context Menu | Code Window” from drop down list.
Then Click on “Add New Command “. From where you have to move to ”Macros” categories where you will find your created macro listed in command window ( as shown in above image ). Click on OK.
Now, you can change the name from “Modify Selection” section.
Click on “Close”. You are done. Now you have an context menu in you code editor to add the file header.
Similarly from customize > Toolbar section, you can add a toolbar button as well.
Now more funniest part is that, you can also add Keyboard shortcut for the same. From Tool > options > Keyboard . Type macro in search command window, you will get your document header macro available. Assign a keyword which you like to give ( I gave Alt + H ) ( make sure it’s available :) ) . Click on ok.
Now what ? For any of your file, Press “Alt + H” , you will see your document header added automatically.
I was looking for some resource to do automatic update of file header during file rename , I found one intereseting article Macro Madness. This article may help you with some different problem as well.
Hope This will help you and save your some amount of time !