StyleCop Analyzers Documentation

StyleCop Analyzers is configured via two mechanisms:

1. Code analysis rule set files: Used to enable/disable individual rules and configure their severity. These are standard Visual Studio rule sets.
2. stylecop.json: Used to specify project-specific text (like company names or copyright headers) and fine-tune the behavior of specific rules.

You can find an example of the default rule set configuration here.

The rule SA1626 (Documentation Rules) triggers when a single-line comment begins with three forward slashes (///). In C#, three slashes are reserved for XML documentation headers.

To fix this violation:

• Use exactly two slashes (//) for standard single-line comments.
• Use four slashes (////) when commenting out lines of code to clearly differentiate them from standard comments.
• Use three slashes (///) only for XML documentation headers.

The SA1401 rule (part of StyleCop.CSharp.MaintainabilityRules) requires that all instance fields within a C# class be declared with private access. Using properties instead of public fields allows you to change the internal implementation without breaking the class interface.

Exemptions:

• Fields within C# structs can have any access level.
• static readonly fields are exempt (commonly used as constants).
• readonly instance fields are not exempt; they must still be private.
• The C# 8 readonly modifier on struct members does not affect this rule.

## How to fix violations

To fix a violation of this rule, make the field private and add a property to expose the field outside of the class.

The SA1601 rule requires that every partial element (such as a partial class or partial method) has a documentation header. A violation occurs if the header is missing or empty.

Recommended Pattern for Partial Classes

To avoid issues with SDK documentation tools merging or ignoring documentation, follow this pattern:

1. Main Part: Use the standard <summary> tag to provide the official SDK documentation.
2. Other Parts: Omit the <summary> tag and use the <content> tag instead. The <content> tag is ignored by SDK documentation tools but helps with code readability and maintainability.

Example Fix

/// <summary>
/// Represents a customer in the database.
/// </summary>
public partial class Customer
{
}

/// <content>
/// Contains auto-generated functionality for the Customer class.
/// </content>
public partial class Customer
{
}

To enable IntelliSense (code completion, quick info) in Visual Studio while editing stylecop.json, add a $schema reference to the top level of your file:

{
  "$schema": "https://raw.githubusercontent.com/DotNetAnalyzers/StyleCopAnalyzers/master/StyleCop.Analyzers/StyleCop.Analyzers/Settings/stylecop.schema.json"
}

If the schema appears out-of-date, right-click anywhere in the stylecop.json document and select Reload Schemas.

To enforce StyleCop rules in your project, install the StyleCop.Analyzers NuGet package. You can do this using the NuGet command line or the NuGet Package Manager in Visual Studio 2015 or newer.

Install-Package StyleCop.Analyzers

The SA1212 rule (PropertyAccessorsMustFollowOrder) requires that a get accessor appears before any set or init accessor within a property or indexer. This rule also applies to readonly getters in structs; a readonly get must appear before any set or init accessor.

To fix a violation, move the get accessor so that it precedes the set or init accessor.

// Violates SA1212
public string Name
{
    set { this.name = value; }
    get { return this.name; }
}

// Complies with SA1212
public string Name
{
    get { return this.name; }
    set { this.name = value; }
}

To fix an SA1603 violation, ensure that all XML nodes in your documentation headers are valid and can be parsed by a standard XML parser. Ensure every opening tag has a corresponding, correctly spelled closing tag.

// Invalid: The closing tag is misspelled
/// <summary>
/// An example of badly formed Xml.
/// </summa3ry>
public class Example
{
}

// Fixed: Use a valid closing tag
/// <summary>
/// An example of valid Xml.
/// </summary>
public class Example
{
}

To reuse stylecop.json and custom rulesets across multiple solutions, package them into a NuGet package and use a .props file to inject them into projects.

1. Create a .nuspec containing stylecop.json, your .ruleset, and a .props file.
2. In the .props file, set CodeAnalysisRuleSet and add stylecop.json to AdditionalFiles.
3. Consume the NuGet package in your target projects.

<!-- Example .props file content -->
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
      <CodeAnalysisRuleSet>$(MSBuildThisFileDirectory)\..\acme.stylecop.ruleset</CodeAnalysisRuleSet>
  </PropertyGroup>
  <ItemGroup>
      <AdditionalFiles Include="$(MSBuildThisFileDirectory)\..\stylecop.json" Link="stylecop.json" />
  </ItemGroup>
</Project>