How to: Customize the Code Analysis Dictionary
Applies to: 
Visual Studio 
Visual Studio for Mac
Note
This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
Code Analysis uses a built-in dictionary to check identifiers in your code for errors in spelling, grammatical case, and other naming conventions of the .NET design guidelines. You can create a custom dictionary Xml file to add, remove, or modify terms, abbreviations, and acronyms to the built-in dictionary.
For example, suppose your code contained a class named DoorKnokker. Code Analysis would identify the name as a compound of two words: door and knokker. It would then raise a warning that knokker was not spelled correctly. To force code analysis to recognize the spelling, you can add the term knokker to the custom dictionary.
To create a custom dictionary
Create a file that is named CustomDictionary.xml.
Define your custom words by using the following XML structure:
<Dictionary>
<Words>
<Unrecognized>
<Word>knokker</Word>
</Unrecognized>
<Recognized>
<Word></Word>
</Recognized>
<Deprecated>
<Term PreferredAlternate=""></Term>
</Deprecated>
<Compound>
<Term CompoundAlternate=""></Term>
</Compound>
<DiscreteExceptions>
<Term></Term>
</DiscreteExceptions>
</Words>
<Acronyms>
<CasingExceptions>
<Acronym></Acronym>
</CasingExceptions>
</Acronyms>
</Dictionary>
Custom Dictionary Elements
You can modify the behavior of the Code Analysis dictionary by adding terms as the inner text of the following elements in the custom dictionary:
Dictionary/Words/Recognized/Word
To include a term in the list of terms that code analysis identifies as correctly spelled, add the term as the inner text of a Dictionary/Words/Recognized/Word element. Terms in Dictionary/Words/Recognized/Word elements are not case-sensitive.
Example
<Dictionary>
<Words>
<Recognized>
<Word>knokker</Word>
...
</Recognized>
...
</Words>
...
</Dictionary>
Terms in Dictionary/Words/Recognized nodes are applied to the following code analysis rules:
Dictionary/Words/Unrecognized/Word
To exclude a term from the list of terms that code analysis identifies as correctly spelled, add the term to exclude as the inner text of a Dictionary/Words/Unrecognized/Word element. Terms in Dictionary/Words/Unrecognized/Word elements are not case-sensitive.
Example
<Dictionary>
<Words>
<Unrecognized>
<Word>meth</Word>
...
</Unrecognized>
...
</Words>
...
</Dictionary>
Terms in the Dictionary/Words/Unrecognized node are applied to the following code analysis rules:
Dictionary/Words/Deprecated/Term[@PreferredAlternate]
To include a term in the list of terms that code analysis identifies as deprecated, add the term as the inner text of a Dictionary/Words/Deprecated/Term element. A deprecated term is a word that is spelled correctly but should not be used.
To include a suggested alternate term in the warning, specify the alternate in the PreferredAlternate attribute of the Term element. You can leave the attribute value empty if you do not want to suggest an alternate.
The deprecated term in Dictionary/Words/Deprecated/Term element is not case-sensitive.
The PreferredAlternate attribute value is case-sensitive. Use Pascal case for compound alternates.
Example
<Dictionary>
<Words>
<Deprecated>
<Term PreferredAlternate="LogOn">login</Term>
...
</Deprecated>
...
</Words>
...
</Dictionary>
Terms in the Dictionary/Words/Deprecated node are applied to the following code analysis rules:
Dictionary/Words/Compound/Term[@CompoundAlternate]
The built-in dictionary identifies some terms as single, discrete terms rather than a compound term. To include a term in the list of terms that code analysis identifies as a compound word and to specify the correct casing of the term, add the term as the inner text of a Dictionary/Words/Compound/Term element. In the CompoundAlternate attribute of the Term element, specify the individual words that make up the compound term by capitalizing the first letter of the individual words (Pascal case). Note that the term specified in the inner text is automatically added to the Dictionary/Words/DiscreteExceptions list.
The compound term in Dictionary/Words/Compound/Term element is not case-sensitive.
The CompoundAlternate attribute value is case-sensitive. Use Pascal case for compound alternates.
Example
<Dictionary>
<Words>
<Compound>
<Term CompoundAlternate="CheckBox">checkbox</Term>
...
</Compound>
...
</Words>
...
</Dictionary>
Terms in the Dictionary/Words/Compound node are applied to the following code analysis rules:
Dictionary/Words/DiscreteExceptions/Term
To exclude a term in the list of terms that code analysis identifies as a single, discrete word when the term is checked by the casing rules for compound words, add the term as the inner text of a Dictionary/Words/DiscreteExceptions/Term element. The term in Dictionary/Words/DiscreteExceptions/Term element is not case-sensitive.
Example
<Dictionary>
<Words>
<DiscreteExceptions>
<Term>checkbox</Term>
...
</DiscreteExceptions>
...
</Words>
...
</Dictionary>
Terms in the Dictionary/Words/DiscreteExceptions node are applied to the following code analysis rules:
Dictionary/Acronyms/CasingExceptions/Acronym
To include an acronym in the list of terms that code analysis identifies as correctly spelled and to indicate how the acronym when the term is checked by the casing rules for compound words, add the term as the inner text of a Dictionary/Acronyms/CasingExceptions/Acronym element. The acronym in the Dictionary/Acronyms/CasingExceptions/Acronym element is case-sensitive.
Example
<Dictionary>
<Acronyms>
<CasingExceptions>
<Acronym>NESW</Acronym> <!-- North East South West -->
...
</CasingExceptions>
...
</Acronyms>
...
</Dictionary>
Terms in the Dictionary/Acronyms/CasingExceptions node are applied to the following code analysis rules:
To apply a custom dictionary to a project
In Solution Explorer, use one of the following procedures:
To add a dictionary to a single project, right-click the project name and then click Add Existing Item. Specify the file in the Add Existing Item dialog box.
To add a dictionary that is shared among two or more projects, locate the file to share in the Add Existing Item dialog box, click the down arrow on the Add button and then click Add As Link.
In Solution Explorer, right-click the CustomDictionary.xml file name and click Properties.
From the Build Action list, select CodeAnalysisDictionary.
From the Copy to Output Directory list, select Do not copy.