StyleCop.CSharp.Async.Rules

Additional StyleCop rules for async / await style programming.

The following examples will result in StyleCop warnings:

• async void DoSomethingAsync() --> method should return awaitable instead of void
• see Stephen Cleary, Phil Haack,...
• async Task DoSomething() --> method should be named DoSomethingAsync
• see Task-based Asynchronous Pattern (TAP)
• void DoSomethingAsync() --> method should have async modifier or return a Task/Task
• see Task-based Asynchronous Pattern (TAP)

1. Installation

By Nuget

If you have StyleCop integrated into your build already, just install the nuget package StyleCop.CSharp.Async.Rules in all projects you want to be verified.

If you don't have installed StyleCop yet, I'd recommend installing the nuget package StyleCop.MsBuild.

Manually

The rules-dll (StyleCop.CSharp.Async.Rules.dll) is available on the build server(see Artifacts). You can place it alongside the StyleCop.dll and StyleCop will automatically pick it up. Alternatively, you can also tell StyleCop where to pick it up by defining an StyleCopAdditionalAddinPaths item in the *.csproj file:

<ItemGroup>
  <StyleCopAdditionalAddinPaths Include="..\StyleCop.CSharp.Async.Rules\">
    <Visible>false</Visible>
  </StyleCopAdditionalAddinPaths>
</ItemGroup>

2. Rules

Description, supressing a violation and disabling a rule entirely

Methods with async modifier must end with Async

ID: AR0001:MethodsWithAsyncModifierMustEndWithAsync

Violated when an async method is named Foo() instead of FooAsync().

Suppress specific warning / occurrence in code

[SuppressMessage(
  "StyleCop.CSharp.AsyncRules",
  "AR0001:MethodsWithAsyncModifierMustEndWithAsync",
  Justification = "Yipii-ai-ei-oh")]
async Task DoSomething() { }

Disable in Settings.StyleCop file

<Analyzer AnalyzerId="StyleCop.CSharp.AsyncRules">
  <Rules>
    <Rule Name="MethodsWithAsyncModifierMustEndWithAsync">
        <RuleSettings>
          <BooleanProperty Name="Enabled">False</BooleanProperty>
        </RuleSettings>
    </Rule>
  </Rules>
</Analyzer>

Methods ending with Async must have async modifier or return a Task

ID: AR0002:MethodEndingWithAsyncMustHaveAsyncModifierOrReturnTask

Hint: This was recently adapted and renamed from MethodEndingWithAsyncMustHaveAsyncModifier to MethodEndingWithAsyncMustHaveAsyncModifierOrReturnTask

Violated when a method named FooAsync does not have the async modifier and does not return a Task / Task<T>.

Suppress specific warning / occurrence in code

[SuppressMessage(
  "StyleCop.CSharp.AsyncRules",
  "AR0002:MethodEndingWithAsyncMustHaveAsyncModifierOrReturnTask",
  Justification = "I'm cheating")]
int FooAsync() { }

Disable in Settings.StyleCop file

<Analyzer AnalyzerId="StyleCop.CSharp.AsyncRules">
  <Rules>
    <Rule Name="MethodEndingWithAsyncMustHaveAsyncModifierOrReturnTask">
        <RuleSettings>
          <BooleanProperty Name="Enabled">False</BooleanProperty>
        </RuleSettings>
    </Rule>
  </Rules>
</Analyzer>

Methods with async modifier must return awaitable

ID: AR1001:MethodsWithAsyncModifierShouldReturnAwaitable

Violated when a method async void FooAsync() returns void instead of Task or another awaitable type.

Suppress specific warning / occurrence in code

[SuppressMessage(
  "StyleCop.CSharp.AsyncRules",
  "AR1001:MethodsWithAsyncModifierShouldReturnAwaitable",
  Justification = "no need to wait for task to end")]
async void HandleEventAsync() { }

Disable in Settings.StyleCop file

<Analyzer AnalyzerId="StyleCop.CSharp.AsyncRules">
  <Rules>
    <Rule Name="MethodsWithAsyncModifierShouldReturnAwaitable">
        <RuleSettings>
          <BooleanProperty Name="Enabled">False</BooleanProperty>
        </RuleSettings>
    </Rule>
  </Rules>
</Analyzer>