Authoring a Custom StyleCop Rule

StyleCop provides an extensible framework for plugging in custom rules. A custom rules analyzer checks the contents of a source code file for adherence to one or more rules which are not already covered by the default set of rules shipping with the tool. Custom StyleCop rules will typically cover style and consistency guidelines, similar to the default rules.

StyleCop provides a mechanism for custom rules analyzers to flag violations found within the source code. When flagging a rules violation, the analyzer will provide the location in the code where the violation occurs, as well as a description of the problem. This allows the user to browse to the code and fix the issue.

Building a Custom StyleCop Rules Analyzer

To create a custom StyleCop rule, create a new ClassLibrary project in Visual Studio, and set up references to StyleCop.dll and StyleCop.CSharp.dll. Next, create a new C# class within the project. The class must inherit from SourceAnalyzer, and contain an instance of the SourceAnalyzerAttribute attribute which specifies the code parser that the analyzer will be associated with. For C# code, the analyzer will always be associated with the CsParser type. For example:

Code
[SourceAnalyzer(typeof(CsParser))] public class MyCustomRules : SourceAnalyzer { // Implements one or more custom rules. }

Next, implement an override of the AnalyzeDocument(CodeDocument) method. This method will be called by StyleCop whenever the custom analyzer should run its rules against a code document. The AnalyzeDocument method receives an instance of a CodeDocument class. For C# code, this should be casted to CsDocument. This object will contain an object model representing the C# code to be analyzed.

Code
[SourceAnalyzer(typeof(CsParser))] public class CustomRules : SourceAnalyzer { public override void AnalyzeDocument(CodeDocument document) { CsDocument csharpDocument = (CsDocument)document; if (csharpDocument.RootElement != null && !csharpDocument.RootElement.Generated) { // Run the custom rules against the code. } } }

As shown in the code example above, the custom rules analyzer should first check to ensure that the RootElement property is not null, indicating that the code file is empty. In most cases the code should also verify that the contents of the file have not been auto-generated by a tool, which is done by checking the value of the CsDocument.RootElement.Generated property. Generally, auto-generated code should not be checked for style errors, as it was generated by a tool and not written manually.

There are two common ways for a custom rules analyzer to iterate through the code object model and discover rules violations. The first method uses the built-in code walkers. A code walker can be instantiated from the root of any document, element, statement, expression, or clause, by calling WalkDocument, WalkElement, WalkStatement, WalkExpression, or WalkQueryClause. In each case, the walker method takes a series of delegate callbacks, which will be called each time the walker discovers an element, statement, expression, or query clause in the code. For example:

Code

public override void AnalyzeDocument(CodeDocument document) { CsDocument csharpDocument = (CsDocument)document; if (csharpDocument.RootElement != null && !csharpDocument.RootElement.Generated) { csharpDocument.WalkDocument( new CodeWalkerElementVisitor<object>(this.VisitElement), new CodeWalkerStatementVisitor<object>(this.VisitStatement), new CodeWalkerExpressionVisitor<object>(this.VisitExpression)); } }

In the previous example, the VisitElement method will be called for every element discovered in the code, VisitStatement will be called for every statement, and VisitExpression will be called for every expression. This provides a simple way for the custom rules analyzer to iterate through all of the code within the document. It is also possible to pass null to any of these arguments, if the rules analyzer is not interested in visiting code units of that type.

Whenever the walker discovers an element, statement, or expression within the code, it will call the appropriate callback for that type of code unit. This allows the custom rules analyzer to analyze the code within that code unit. For example, the following method would be called for every statement discovered within the code:

Code
private bool VisitStatement(Statement statement, Expression parentExpression, Statement parentStatement, CsElement parentElement, object context) { if (statement.StatementType == StatementType.Block && statement.ChildStatements.Count == 0) { this.AddViolation(parentElement, statement.LineNumber, "BlockStatementsShouldNotBeEmpty"); } }

The code example above also illustrates how to file a violation against the code. In this example, a custom rule is checking to make sure that the code does not contain any empty block statements. It does this by checking whether the given statement is a block statement, then checking to see whether the statement contains any child statements. If not, the "BlockStatementsShouldNotBeEmpty" rule violation is flagged against the parent element.

StyleCop provides a second way to interate through a code object model. This involves viewing the code token by token, rather than viewing the code model organized by elements, statements, expressions, etc. Every code model object inheriting from the CodeUnit type contains a Tokens property, which exposes a linked-list of all the tokens within that section of code. This list can be iterated over to view each of the tokens one-by-one. For example:

Code

public override void AnalyzeDocument(CodeDocument document) { CsDocument csharpDocument = (CsDocument)document; // Loop through all of the tokens in the document. for (Node<CsToken>; tokenNode = document.Tokens.First; tokenNode != null; tokenNode = tokenNode.Next) { if (tokenNode.Value.CsTokenType == CsTokenType.String) { this.AddViolation(tokenNode.Value, tokenNode.Value.LineNumber, "CodeMustNotContainHardcodedStrings"); } } }

The code example above iterates through all of the code in the document and flags a custom rule violation if the file contains any strings.

Completing the Custom Rules Analyzer

To learn how to complete the custom rules analyzer and install it, read the Writing Custom Rules for StyleCop topic.

Example

Code

// Checks for the presence of access modifiers on all elements. [SourceAnalyzer(typeof(CsParser))] public class AccessModifiers : SourceAnalyzer { public AccessModifiers() { } public override void AnalyzeDocument(CodeDocument document) { CsDocument csdocument = (CsDocument)document; if (csdocument.RootElement != null && !csdocument.RootElement.Generated) { csdocument.WalkDocument( new CodeWalkerElementVisitor<object>(this.VisitElement), null, null); } } private bool VisitElement(CsElement element, CsElement parentElement, object context) { // Make sure this element is not generated. if (!element.Generated) { // Flag a violation if the element does not have an access modifier. if (!element.Declaration.AccessModifier) { this.AddViolation(element, "AccessModifiersMustBeDeclared"); } } } }