Adding Custom Rule Settings

Custom StyleCop rules analyzers can define optional settings which the end-user can configure to control the behavior of rules.

This article describes how to add settable properties to your custom rules analyzer. To learn how to create a custom StyleCop rules analyzer, see the Writing Custom Rules for StyleCop article.

Creating Custom Properties

A custom rules property must be defined within the analyzer's Xml metadata file. Each property will be given a unique name, which can be used to get or set the value of the property within the rule analyzer code. The property can be exposed on the StyleCop settings dialog, allowing the end-user to set the value of the property. The value set by the user will be stored within a StyleCop settings file, and loaded by StyleCop when the tool is run.

To add a custom property for a rules analyzer, open the rule analyzer's Authoring Rules Metadata, and add a Properties section, as shown below:

Code
<SourceAnalyzer Name="MyCustomRules"> <Description> ... </Description> <Properties> <!-- Defines the settable properties for this rules analyzer --> </Properties> <Rules> ... </Rules> </SourceAnalyzer>

There are four types of properties which can be defined for a rules analyzer: BooleanProperty, IntegerProperty, StringProperty, and CollectionProperty. A property is defined using the following syntax:

Code
<PropertyType Name=value DefaultValue=value FriendlyName=value Description=value DisplaySettings=value Merge=value Aggregate=value />

The Name attribute defines the name of the property. This name will be used to access the property within the rules analyzer code. The DefaultValue attribute is optional, and defines the default value for the property. This value will be used if the property has not been set by the user. The FriendlyName attribute defines a short friendly name to display to the user. The Description attribute defines a longer description of the property. The DisplaySettings attribute indicates whether to display the property on the default StyleCop settings page. The DisplaySettings property is currently only valid for boolean properties, and will be ignored for other property types. The Merge property is also optional, and determines whether to merge the value of the property together if multiple StyleCop settings files are loaded for a project. If the value is set to false, the most local value of the property will be used, and all other values set for this property will be ignored. The Aggregate attribute is only valid for the CollectionProperty type. If this attribute is set to true and the property is set within multiple settings files which are loaded for a project, all of the values within each of the collections will be aggregated together. If the value is set to false, only the values from the most local settings file will be used, and all other values will be ignored.

For example, the following code defines each of the four types of properties.

Code

<Properties> <BooleanProperty Name="CheckPrivateMembers" DefaultValue="true" FriendlyName="Check Privates" Description="Indicates whether to enforce the rules on private members." /> <StringProperty Name="CompanyName" DefaultValue="" FriendlyName="Company Name" Description="The required company name which must appear in the file header." /> <IntegerProperty Name="ClassCount" DefaultValue="1" FriendlyName="Class Count" Description="The maximum number of classes which may appear in a single file." /> <CollectionProperty Name="Prefixes" Aggregate="True" FriendlyName="Valid prefixes" Description="The list of allowed prefixes for variable and field names."> </CollectionProperty> </Properties>

Once a property has been defined in the analyzer's Xml metadata file, the property must be exposed on the StyleCop settings dialog to allow the end-user to set the value of the property. For boolean properties, StyleCop will automatically display the property on the Rules page of the settings dialog when the analyzer node is selected, unless the DisplaySettings attribute on the property is set to false.

For non-boolean properties, or boolean properties with the DisplaySettings attribute set to false, custom UI must be written to expose the property to the end-user. To learn how to expose properties on a custom settings page, see the Adding a Custom StyleCop Settings Page page.

Once a property has been defined within an analyzer's metadata Xml file, the property value can be read within the rule analyzer code through the GetSetting(Settings, String) method. For example, to read the currently set value for the boolean CheckPrivateMembers property defined above, the rule analyzer could execute the following code:

Code
public override void AnalyzeDocument(CodeDocument document) { BooleanProperty checkPrivatesProperty = this.GetSetting(document.Settings, "CheckPrivateMembers") as BooleanProperty; if (value != null) { Console.WriteLine("The property value is set to: " + checkPrivatesProperty.Value); } }