Once you turn on the new spelling rules that we've added to Visual Studio 2008, you will want to start to customize the words that it fires on; this is where the new custom dictionary support comes in. A custom dictionary in its basic form, similar to the concept in Microsoft Word, allows you to silence the spell checker over the words that are not in the standard dictionary, such as company and product names.

Adding a custom dictionary to a project

To add a custom dictionary to a C# and Visual Basic project is simple:

1. In Solution Explorer, right-click on the project and choose Add -> New Item...
2. Under Templates, select XML File, enter a name for the dictionary, such as CodeAnalysisDictionary.xml and click Add
3. In Solution Explorer, right-click on the XML file and choose Properties
4. In the Properties tool window, under Build Action choose CodeAnalysisDictionary
5. In Solution Explorer, double-click on the newly created dictionary to open it
6. In the XML editor, paste the following, replacing [productname] and [companyname] with your team's equivalents:
   

   <?xml version="1.0" encoding="utf-8" ?>
   <Dictionary>
       <Words>
           <Recognized>
               <Word>[productname]</Word>
               <Word>[companyname]</Word>
           </Recognized>
       </Words>
   </Dictionary>

You are now ready to start entering your own custom words. Simply add a new <Word> element for each word in your project that does not exist in the dictionary. Each word is case-insensitive, so any casing of the word will be recognized. Code Analysis will automatically pick up the custom dictionary the next time it is run.

Sharing a custom dictionary between projects

Once you have worked through the above steps, the following will be added automatically to your MSBuild-based project (ie csproj or vbproj):

    <ItemGroup>
        <CodeAnalysisDictionary Include="CodeAnalysisDictionary.xml" />
    </ItemGroup>

This means that similar to other Code Analysis properties and items, this information can be placed a common targets file to be shared by multiple projects.

If you do not want to have all projects share a common MSBuild targets file, you can instead do the following:

1. Place the custom dictionary file created above in a shared location, such as alongside the solution
2. In Solution Explorer, right-click on a project and choose Add Item...
3. Browse to and click the custom dictionary to select it
4. On the Add button, click the down arrow to drop a menu and choose Add As Link
5. In Solution Explorer, right-click on the custom dictionary and choose Properties
6. In the Properties tool window, under Build Action choose CodeAnalysisDictionary
7. Repeat steps 2 - 6 for each project you want to share the custom dictionary

Advanced usage of a custom dictionary 

I have shown you above basic usage of the new dictionary support the Code Analysis team has added to Visual Studio 2008. Those that have previously used custom dictionaries with FxCop, will realize that there are more things that you can add to these files that will customize other naming-based rules. However, for now I will leave you with the above and talk about advanced usage of a custom dictionary in future posts.