How to combine multiple custom StyleCop rules under a single “Custom Rules” node in StyleCop settings and concurrency

Question

Based on several good articles I have been able to successfully create a few custom StyleCop rules. For reference, a few articles I found very useful on this topic are listed here:

• How to Implement a Custom StyleCop Rule
• Creating Custom Rules for Microsoft Source Analyzer - Part I
• Creating Custom Rules for Microsoft Source Analyzer - Part II
• Creating Custom Rules for Microsoft Source Analyzer - Part III

I am using Visual Studio 2010 Ultimate edition along with StyleCop version 4.4.0.14.

Creating a custom StyleCop rule calls for creating a class file along with a corresponding XML file, which is used to add the rules to the StyleCop settings. When I do this, all my custom rules get executed correctly. However, what I do not like about this is that in the StyleCop settings tree, you end up getting multiple "Custom Rules" nodes, one for every XML file.

Skipping the implementation details of the different rules, here is what I did. Let's take the below two simple custom rules classes along their corresponding XML files:

File: CustomRule1.cs

namespace StyleCop.CustomRules
{
    [SourceAnalyzer(typeof(CsParser))]
    public class CustomRule1 : SourceAnalyzer
    {
        public override void AnalyzeDocument(CodeDocument document)
        {
            Param.RequireNotNull(document, "document");
            CsDocument csDocument = document as CsDocument;
            if ((csDocument.RootElement != null) && !csDocument.RootElement.Generated)
            {
                // Do something...
            }
        }
    }
}

File: CustomRule2.cs

namespace StyleCop.CustomRules
{
    [SourceAnalyzer(typeof(CsParser))]
    public class CustomRule2 : SourceAnalyzer
    {
        public override void AnalyzeDocument(CodeDocument document)
        {
            Param.RequireNotNull(document, "document");
            CsDocument csDocument = document as CsDocument;
            if ((csDocument.RootElement != null) && !csDocument.RootElement.Generated)
            {
                // Do something...
            }
        }
    }
}

File: CustomRule1.xml

<?xml version="1.0" encoding="utf-8" ?>
<SourceAnalyzer Name="Custom Rules">
  <Description>
    These custom rules provide extensions to the ones provided with StyleCop.
  </Description>
  <Rules>
    <Rule Name="CustomRule1" CheckId="CR1001">
      <Context>Test rule 1.</Context>
      <Description>Test rule 1.</Description>
    </Rule>
  </Rules>
</SourceAnalyzer>

File: CustomRule2.xml

<?xml version="1.0" encoding="utf-8" ?>
<SourceAnalyzer Name="Custom Rules">
  <Description>
    These custom rules provide extensions to the ones provided with StyleCop.
  </Description>
  <Rules>
    <Rule Name="CustomRule2" CheckId="CR1002">
      <Context>Test rule 2.</Context>
      <Description>Test rule 2.</Description>
    </Rule>
  </Rules>
</SourceAnalyzer>

With the above, all (both) my rules got correctly executed. The following appeared in the StyleCop settings tree (the square brackets represent a checkbox):

[] C#
    [] {} Custom Rules
        [] {} CR1001: CustomRule1
    [] {} Custom Rules
        [] {} CR1002: CustomRule2
    [] {} Documentation Rules
    [] {} Layout Rules
    etc.

What I would like, is to have my custom rules under one node called "Custom Rules" in the StyleCop settings file as follows:

[] C#
    [] {} Custom Rules
        [] {} CR1001: CustomRule1
        [] {} CR1002: CustomRule2
    [] {} Documentation Rules
    [] {} Layout Rules
    etc.

I was able to combine the rules into a single "Custom Rules" node in the StyleCop settings by combining the two XML files into one as follows:

File: CustomRule1.xml

<?xml version="1.0" encoding="utf-8" ?>
<SourceAnalyzer Name="Custom Rules">
  <Description>
    These custom rules provide extensions to the ones provided with StyleCop.
  </Description>
  <Rules>
    <Rule Name="CustomRule1" CheckId="CR1001">
      <Context>Test rule 1.</Context>
      <Description>Test rule 1.</Description>
    </Rule>
    <Rule Name="CustomRule2" CheckId="CR1002">
      <Context>Test rule 2.</Context>
      <Description>Test rule 2.</Description>
    </Rule>
  </Rules>
</SourceAnalyzer>

However, once I did this, ONLY one custom rule got executed and that was CustomRule1, the rule where the class (file) name matched the XML file name.

I attempted to set the attribute on CustomRule2 to indicate the XML file as follows:

namespace StyleCop.CustomRules
{
    [SourceAnalyzer(typeof(CsParser), "CustomRule1.xml")]
    public class CustomRule2 : SourceAnalyzer
    {
        public override void AnalyzeDocument(CodeDocument document)
        {
            Param.RequireNotNull(document, "document");
            CsDocument csDocument = document as CsDocument;
            if ((csDocument.RootElement != null) && !csDocument.RootElement.Generated)
            {
                // Do nothing.
            }
        }
    }
}

Setting the attribute as shown above to the XML file did not resolve this issue either. Both rules appear in the StyleCop settings, but only CustomRule1 gets executed.

How can I resolve this?

Update:

Based on the accepted answer, I took the approach of checking all my custom rules within a single analyzer.

From my understanding, each expression tree walker runs on its own thread, and thus state cannot be easily shared during the process. If I go with the approach of using a single analyzer, can I safely do the following?

[SourceAnalyzer(typeof(CsParser))]
public class CustomRules : SourceAnalyzer
{
    private enum CustomRuleName
    {
        CustomRule1,
        CustomRule2
    }

    private CustomRuleName currentRule;

    public override void AnalyzeDocument(CodeDocument document)
    {
        Param.RequireNotNull(document, "document");
        CsDocument doc = document as CsDocument;

        // Do not analyze empty documents, code generated files and files that
        // are to be skipped.
        if (doc.RootElement == null || doc.RootElement.Generated)
        {
            return;
        }

        // Check Rule: CustomRule1
        this.currentRule = CustomRuleName.CustomRule1;
        doc.WalkDocument(VisitElement);

        // Check Rule: CustomRule2
        this.currentRule = CustomRuleName.CustomRule2;
        doc.WalkDocument(VisitElement);
    }

    private bool VisitElement(CsElement element, CsElement parentElement, object context)
    {
        if (this.currentRule == CustomRuleName.CustomRule1)
        {
            // Do checks only applicable to custom rule #1
        }
        else if (this.currentRule == CustomRuleName.CustomRule2)
        {
            // Do checks only applicable to custom rule #2
        }
    }
}

Update:

Based on further testing the above is NOT safe. One cannot use instance fields to maintain state.

1. When running StyleCop on a project with multiple source code files, multiple threads will share the same instance of the analyzer.

2. Further, given the below code, multiple threads and concurrency also come into play on each source code document being analyzed when the call to doc.WalkDocument(...) method is made. Each expression tree walker runs on its own thread.

In other words, in addition to the fact that multiple source code files may be analyzed concurrently on multiple threads, the callbacks VisitElement, StatementWalker and ExpressionWalker are also executed on separate threads.

[SourceAnalyzer(typeof(CsParser))]
public class CustomRules : SourceAnalyzer
{
    public override void AnalyzeDocument(CodeDocument document)
    {
        Param.RequireNotNull(document, "document");
        CsDocument doc = document as CsDocument;

        // Do not analyze empty documents, code generated files and files that
        // are to be skipped.
        if (doc.RootElement == null || doc.RootElement.Generated)
        {
            return;
        }

        IDictionary<string, Field> fields = new Dictionary<string, Field>();
        doc.WalkDocument(VisitElement, StatementWalker, ExpressionWalker, fields);
    }

    private bool VisitElement(CsElement element, CsElement parentElement, object context)
    {
        // Do something...
        return true;
    }

    private bool StatementWalker(Statement statement, Expression parentExpression, Statement parentStatement, CsElement parentElement, object context)
    {
        // Do something...
        return true;
    }

    private bool ExpressionWalker(Expression expression, Expression parentExpression, Statement parentStatement, CsElement parentElement, object context)
    {
        // Do something...
        return true;
    }
}

Answer 1

Usually analyzer contains more than one rule (otherwise it would be rather strange). Each analyzer is displayed as a separate node in settings UI.

If you want a single node in settings UI you surely need to have only one analyzer, which would perform both of your checkings.

namespace StyleCop.CustomRules
{
    [SourceAnalyzer(typeof(CsParser))]
    public class MyCustomRules : SourceAnalyzer
    {
        public override void AnalyzeDocument(CodeDocument document)
        {
            // ...
            // code here can raise CR1001 as well as CR1002
        }
    }
}

File: MyCustomRules.xml

<?xml version="1.0" encoding="utf-8" ?>
<SourceAnalyzer Name="My Custom Rules">
  <Description>
    These custom rules provide extensions to the ones provided with StyleCop.
  </Description>
  <Rules>
    <Rule Name="CustomRule1" CheckId="CR1001">
      <Context>Test rule 1.</Context>
      <Description>Test rule 1.</Description>
    </Rule>
    <Rule Name="CustomRule2" CheckId="CR1002">
      <Context>Test rule 2.</Context>
      <Description>Test rule 2.</Description>
    </Rule>
  </Rules>
</SourceAnalyzer>

Answer 2

If someone is interested in this topic, I've made some custom rules and also I was able to group those rules. In fact if someone is interested on passing parameters to the warning messages, my rules also do that :).

Rules: 1. NamespaceMustBeginWithAllowedCompanyName 2. FieldNamesMustBeginWithUnderscore

Filename: StyleCopExtensions.cs

private bool VisitElement(CsElement element, CsElement parentElement, object context)
    {
        #region Namespace rules
        if (!element.Generated && element.ElementType == ElementType.Namespace)
        {
            var @namespace = element.Declaration.Name;
            var companyName = NamespaceUtils.GetNamespaceToken(@namespace, NamespaceTokenType.Company);
            //Flag a "Violation" is the element doesn't start with an allowed company name
            if (!NamespaceUtils.ValidateNamespaceCompany(companyName))
            {
                AddViolation(parentElement, element.LineNumber, "NamespaceMustBeginWithAllowedCompanyName", companyName);
            }
        #endregion

        #region Fields rules
        if (!element.Generated && element.ElementType == ElementType.Field)
        {
            var fieldName = element.Declaration.Name;
            // Flag a violation if the instance variables are not prefixed with an underscore.
            if (element.ActualAccess != AccessModifierType.Public &&
                element.ActualAccess != AccessModifierType.Internal &&
                fieldName.ToCharArray()[0] != '_')
            {
                AddViolation(parentElement, element.LineNumber, "FieldNamesMustBeginWithUnderscore", fieldName);
            }
        }


        #endregion

        return true;
    }

Xml filename: StyleCopExtensions.xml - Similar to the other xml files posted below. - You can use the parameters sent in the messages in the same way 'string.Format()' does: Just include {0}, {1}, {N} inside the of the in the xml file.