Creating a custom dictionary for code analysis in VS2008

There seems to be a few posts out there asking where to put a custom dictionary to be used by FxCop (code analysis). In Visual Studio 2008, you can add a dictionary xml file to the solution and then tell the solution to use this as the dictionary for FxCop. Here's how.

Create your dictionary file
Add a new XML file to your project or solution and call it what you want. It doesn't need to be called CustomDictionary.xml.
The dictionary file must follow the correct schema, but unfortunately, there does not appear to be an .xsd schema file available (that I can find). As a starting point, copy the XML from the CustomDictionary.xml that comes with FxCop which is in the default FxCop install directory which on my machine is C:\Program Files\Microsoft Visual Studio 9.0\Team Tools\Static Analysis Tools\FxCop\CustomDictionary.xml. You can then edit this file to include your own words. However, the schema is pretty simple:


Making FxCop use your dictionary
In the properties for the XML file you've created (right-click, properties), change the Build Action to 'CodeAnalysisDictionary'.
Recompile your project and FxCop should no longer complain about those words. If you examine the build output window, Visual Studio makes a call to FxCop.exe with a whole load of parameters. Setting the build action property of the xml file to CodeAnalysisDictionary, makes VS include the switch /dictionary:"" to the FxCop command.
You can also just amened the CustomDictionaryl.xml file in the FxCop default installation directory but this obviously only takes effect on that machine. I like being able to check this dictionary file into source control so that other team members can benefit from it and this also includes the build server.

Reusing the dictionary across assemblies
Another common situation is that you have more than one assembly and you want to share the same dictionary across them. One way of doing this is to add your dictionary file to the solution rather than a specific project. Then, add an existing item to your project, browse to the dictionary file in your solution, and select add as link. This add the dictionary file to your project and makes the link act like a shortcut to the dictionary file in your solution. This means you only physically create one dictionary file which is then easily shared across all your assemblies. Remember, you must still set the build action property on the link file in order for it to be recognised as a code analysis dictionary.
Note: You don't actually need to add the dictionary.xml file to the solution, but it obviously must be checked into your source control system and it should be referenced relatively, not absolutely.

The reason
In most projects I've seen, the code analysis rule CA1704 - Identifiers should be spelled correctly is all too easily ignored by adding a rule to the global suppression file. Personally, I don't like this because I think the global suppression file should not be used as a custom dictionary, especially when there is an alternative. The custom dictionary method is much more portable across projects and it preserves the separation of spelling against genuine code analysis errors.

Setting up .NET Development Trees in Visual Studio

I had the intention of talking about best practice ways of setting up a Visual Studio solution including which are the best tools followed by a step by step guide of how to do it. Well, it looks like someone beat me to it! This pdf from Mike Roberts does exactly that. What was interesting is that we set up our VS solutions very similarly and use most, if not all of the same tools. But then again, Mike Robert's is from ThoughtWorks and our Development Manager is ex ThoughtWorks - Amazing how the information flows between companies! ;)

Talking of development tree structures, there is a tool on CodePlex that generates your solution tree for you in line with how Mike Robert's document suggests. It's called Tree Surgeon. It's very simple but it provides a good start.

Get latest before checkout

One difference between Visual Source Safe (VSS) and the version control in Team Foundation Server (TFS) is that VSS performed a get latest operation before checking out a file but TFS does not offer this functionality. This caused an issue for a few of my colleagues and until now, I didn't know of a way around this problem. For those that are interested, Greg found an article here that describes how to alter this behavior and you can download the file from CodePlex. However, the add in doesn't do it for me because IMHO, you should NOT perform a get latest before you checkout and file and here is why.

Microsoft have lulled us into a bad head space when it comes to source control. No source control system should manage state, but VSS and TFS both manage state on the server. This just causes no end of problems and doesn't represent what source control is all about. The topography of source control should be a hub & spoke situation - once a client performs a get latest on the server, the server does whatever it needs to to provide the information to the client and then severs the connection. The server should not maintain that Joe Bloggs just checked out file x because it makes absolutely no difference. What if that person kept file x checked out forever? Would it matter? No, not at all. What matters is what goes into the repository, not what comes out of it. In fact, the whole concept of check out is flawed. It's not that you are checking out the file, it more that you want to make changes to a file. In TFS land, check out means "update the server with a record saying that I'm maybe going to edit a file" and undo checkout removes the record. What's the point of maintaining that you might do something? Ultimately, once you have the latest source on your machine, you shouldn't need to contact the repository again until you want to commit the files.

Take this scenario:

• there are two developers, Bill and Ben
  
• Bill makes changes to the customer code file
• Ben makes changes to the customer code file
• Bill checks in his changes
• Ben checks in his changes

What happens here? Whose changes are accepted? What actually happens is the server performs a merge on every check in and if the code can be merged without conflicts, the changes are merged and accepted into the repository. So in this case, as long as Bill and Ben's changes merge successfully, there will be no issues and their changes will be merged together.

However, there is a fundamental step missing from this scenario which causes the most headaches. Before you check in, you should always perform a get latest. If you don't, the version control system will attempt to merge your changes together but it's a horrible position to be in to be caught short when your trying to update the repository. A much better approach is to perform a get latest on the entire solution before you check in. This way, any files that have changed are brought to your machine locally and you can merge/diff/rebuild the project and run your tests before checking in.

Lastly, and my main point about why get latest is bad before checkout, imagine this scenario:

• There are two developers Bill and Ben
• Ben makes changes to the customer file and these changes require changes to several other files file to complete the change successfully
• Bill wants to edit the customer file and he does a get latest before he starts. When he tries to compile, it will fail because he did not get the related files that Ben changed, only the customer file. Therefore, Bill also has to get all the other necessary files to make the solution compile. He doesn't know which files these are and so ends up having to get latest on the entire project
  

This scenario is bad because you haven't completed doing what coding changes you were working on and yet you've had to mix changes from other people. Basically, you should not perform a get latest on a individual file otherwise you are only getting a partial get latest when it comes to building the entire solution. Also, before performing a get latest, you should finish your own changes first and ensure it compiles and passes all the tests before introducing changes from other member of the team through a get latest. Remember, get latest cannot be undone, so if you have your IDE perform a get latest before you check out a file and you end up in the above situation, you could spend a lot of time putting things back together before you are ready to.

In general, when you are working with source control, you should follow this procedure:

• Make changes to the source
• Build the solution and run your tests
• Perform a get latest on the entire solution
• Build the solution and run your tests
• If it builds and all the tests pass, check in

Get latest on an individual file is fine if you understand the repercussions of what you are doing, but having your IDE automatically get the latest copy of a file before you check out defeats the purpose of having a source control system there at all. Assuming it were possible, why not just have all team members working from a central file resource so they alway have the latest files? Can you imagine what this would be like? This is exactly what is recreated if you get the latest version of a file before you make changes to it.

Using Team Foundation Server Power Tools

There are lots of useful tools in the Microsoft Team Foundation Server Powertools, most of which should have been included in the the Visual Studio IDE. The tools that I find most useful are:

Annotate
The annotate command downloads all versions of the specified files and shows information about when and who changed each line in the file. To access the annotate command, right-click on the file you want to annotate in the solution explorer (or Source Control explorer) and select annotate. The annotate command is also accessible from the File, Source Control menu.

When working on a multiuser project, this is a very useful interrogation tool. Along the left hand side of the annotate window, is also displays a hyperlink to the change set which included the code change you are looking for. You can click on this hyperlink to see the other files that were included in the change set. The hyperlink also includes a tooltip which shows the check in comment - very useful. and treediff

Treediff



The treediff command displays a visual representation of the differences between files in two server folders, in a server folder and a local folder, or in two local folders. Treediff can be used from both the command line and inside Visual Studio. The command line version creates the same GUI representation as presented by Visual Studio. The command version is accessed using TFPT Treediff.
Treediff has 4 filtering options:

• Items that exist exclusively on the server tree
• Items that exist exclusively on the local tree
• Items that exist in both trees that have different contents
• Items that exist in both trees that have the same contents

Each of these options can be selected individually or combined to produce a comprehensive report on the differences between what you have on your local machine workspace vs what is on the server. From the output, you can compare, view, get latest version, add missing files and delete each of the files as necessary which makes this tools a good way of keeping your file system tidy. It can be particularly useful if you want to prune all the files in your local workspace that don't exist on the server.
Take care with the delete option - it changes between "Delete" and "Delete Local Files" depending on your selection. Fortunately, all the changes you make inside the treediff become part of your pending changes list and you have to check in for the changes to be accepted.

Process Template Editor



Team Foundation Server Power Tool installs Microsoft Visual Studio Team System Process Editor, which is a process template editor for editing Team Foundation Server process templates inside the Visual Studio IDE. The installation media includes separate documentation for the Microsoft Visual Studio Team System Process Editor, which includes a User Guide and a Readme file that includes known issues.

Although this tools is still pretty raw, it can save you a lot of XML editing and makes editing a process template a lot easier.


Undo Unchanged:
The undo unchanged command undoes redundant pending changes. This means that is the state of an item with a pending changes is the same as on the server, then the change is undone. This command is very useful if you have Visual Studio setup to check out files automatically. It helps prevent files being check in the have had no changes made to them and have been checked out unnecessarily. During the undo unchanged operation, any files that have not been checked out but are not up to date on your local workspace are retrieved from the server. This feature can be suppressed using the /noget command line options.

I'd like to see the undo unchanged command being run before every check in to freshen the pending changes and integrate your changes with the server before you start your check in procedure. This coupled with the tfpt review command which show a window of all your pending changes and allows you to go through each change doing a diff against the sever. As you diff each file, it is ticked on the review window which is a nice way of working though and validating each of your changes and helping you track where you are up to.

For a list of other command available on the team foundation server power tools, type TFPT at the command prompt. Note: depending on your path setup, you may need to change to the team foundation server power tools directory to get access to the TFPT command. I've added the default installation directory for this tools to my environmental path statement which makes more useful as it can be accessed more easily. The default installation directory is C:\Program Files\Microsoft Team Foundation Server Power Tools.

Download the Microsoft Team Foundation Server Power Tools

Microsoft released Enterprise Libraries 3.1 - May 2007

Microsoft have release Enterprise Library 3.1 which contains a few updates from the previous January 06 version. I've installed it and I much prefer the cleaner start menu options which just take you to the source folder and let you browse away.
Note: If you already have the Enterprise Library 3.0 installed, you must uninstall it before installing the Enterprise Library 3.1. However, you can install the Enterprise Library 3.0 or the Enterprise Library 3.1 when 2.0 is already installed.

The patterns & practices Enterprise Library is a library of application blocks designed to assist developers with common enterprise development challenges. Application blocks are a type of guidance, provided as source code that can be used "as is," extended, or modified by developers to use on enterprise development projects. This release of Enterprise Library includes application blocks for Caching, Cryptography, Data Access, Exception Handling, Logging, Policy Injection, Security and Validation.

ClearType Font for Visual Studio 2005

If you use ClearType then you may find the Consolas Font Pack for Microsoft Visual Studio 2005 useful.

Optimized for Microsoft ClearType
The Microsoft Consolas Font Family is a set of highly legible fonts designed for ClearType. It is intended for use in programming environments and other circumstances where a monospaced font is specified. This installation package will set the default font for Visual Studio to Consolas.

Ok, it does look a bit typewriterish, but that's the point. However, you do get slightly more text on the screen than you do with the standard Courier New font both vertically and horizontally. It's worth a try anyway. It's easy to switch off if you don't like it. In Studio, goto Tools, Options, Environment, Fonts and Colors and click the use defaults button.

Download Consolas Font Pack for Microsoft Visual Studio 2005