Authoring Rules Metadata

A custom StyleCop rules analyzer must be accompanied by an Xml metadata file describing the list of rules enforced by the analyzer, as well as any user settings exposed by the analyzer. This topic describes the format of a custom rules analyzer Xml metadata file.

To learn how to author a custom StyleCop rules analyzer, see the Writing Custom Rules for StyleCop topic.

Authoring rules metadata

Every StyleCop rules analyzer class must have an associated rules metadata file, which is an Xml document located within the same project as the rules analyzer class, with the same name. To create a rules metadata file, open the Visual Studio project containing your custom StyleCop rules analyzer (or create a new one). Right-click on the project node, select Add->New Item, and select Xml File from the list of available item types. Ensure that the Xml file has the same name as custom rules class. For example, if the custom rules class is named CustomRules, and is located within a file called CustomRules.cs, the rules metadata Xml file should be named CustomRules.xml, and should be placed within the same directory as the CustomRules.cs file. Once the Xml document is created, right-click on the file in Solution Explorer and select Properties. Change the Build Action property for the file to Embedded Resource.

The contents of the rules metadata file provide a friendly name and description for the rules class, as well as the list of rules enforced and any optional properties which can be set for the rule. For example:

Code

<SourceAnalyzer Name="My Custom Rules"> <Description> Custom rules enforcing blah blah blah. </Description> <Rules> <RuleGroup Name="Fun Rules You Will Love"> <Rule Name="BlockStatementsShouldNotBeEmpty" CheckId="MY1000"> <Context>A block statement should always contain child statements.</Context> <Description>Validates that the code does not contain any empty block statements.</Description> </Rule> <Rule Name="CodeMustNotContainHardcodedStrings" CheckId="MY1001"> <Context>The code should not contain any hard-coded strings.</Context> <Description>Validates that the code does not contain any hard-coded strings.</Description> </Rule> </RuleGroup> </Rules> </SourceAnalyzer>

The RuleGroup node may be ommitted completely if the list of rules is short and does not need to be sub-categorized into groups. Each rule must have a unique rule name, and a unique CheckId. The CheckId value must consist of six characters, beginning with a unique two-letter code idenfying your organization, followed by a unique four-digit number. The context string for a rule will appear in the Visual Studio error list when a violation of the rule is discovered. The rule description appears within the StyleCop settings dialog, to provide more detail about the rule.

To expose custom settings which the end-user can configure to control the behavior of your custom rules, see the Adding Custom Rule Settings page.