diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2007.md b/docs/fundamentals/code-analysis/quality-rules/ca2007.md index d265f85f4f886..1b4f5ec15ad84 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2007.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2007.md @@ -37,12 +37,6 @@ To fix violations, call on - Call `ConfigureAwait(false)` on the task to schedule continuations to the thread pool, thereby avoiding a deadlock on the UI thread. Passing `false` is a good option for app-independent libraries. -## When to suppress warnings - -This warning is intended for libraries, where the code may be executed in arbitrary environments and where code shouldn't make assumptions about the environment or how the caller of the method may be invoking or waiting on it. It is generally appropriate to suppress the warning entirely for projects that represent application code rather than library code; in fact, running this analyzer on application code (for example, button click event handlers in a WinForms or WPF project) is likely to lead to the wrong actions being taken. - -You can suppress this warning in any situation where either the continuation should be scheduled back to the original context or where there is no such context in place. For example, when writing code in a button click event handler in a WinForms or WPF application, in general the continuation from an await should run on the UI thread, and thus the default behavior of scheduling the continuation back to the originating context is desirable. As another example, when writing code in an ASP.NET Core application, by default there is no or , for which reason a `ConfigureAwait` wouldn't actually change any behavior. - ## Example The following code snippet generates the warning: @@ -65,6 +59,14 @@ public async Task Execute() } ``` +## When to suppress warnings + +This warning is intended for libraries, where the code may be executed in arbitrary environments and where code shouldn't make assumptions about the environment or how the caller of the method may be invoking or waiting on it. It is generally appropriate to suppress the warning entirely for projects that represent application code rather than library code; in fact, running this analyzer on application code (for example, button click event handlers in a WinForms or WPF project) is likely to lead to the wrong actions being taken. + +You can suppress this warning in any situation where either the continuation should be scheduled back to the original context or where there is no such context in place. For example, when writing code in a button click event handler in a WinForms or WPF application, in general the continuation from an await should run on the UI thread, and thus the default behavior of scheduling the continuation back to the originating context is desirable. As another example, when writing code in an ASP.NET Core application, by default there is no or , for which reason a `ConfigureAwait` wouldn't actually change any behavior. + +[!INCLUDE [suppress-warning](../../../../includes/code-analysis/suppress-warning.md)] + ## Configure code to analyze Use the following options to configure which parts of your codebase to run this rule on. diff --git a/docs/fundamentals/code-analysis/style-rules/language-rules.md b/docs/fundamentals/code-analysis/style-rules/language-rules.md index 6f8a1a0172660..d98d42bf92ae6 100644 --- a/docs/fundamentals/code-analysis/style-rules/language-rules.md +++ b/docs/fundamentals/code-analysis/style-rules/language-rules.md @@ -25,10 +25,21 @@ Code style language rules affect how various constructs of .NET programming lang Options for language rules can be specified in an EditorConfig file with the following format: +`option_name = value` (Visual Studio 2019 version 16.9 Preview 2 and later) + +or + `option_name = value:severity` -- **Value**: For each language rule, you specify a value that defines if or when to prefer the style. Many rules accept a value of `true` (prefer this style) or `false` (do not prefer this style). Other rules accept values such as `when_on_single_line` or `never`. -- **Severity**: The second part of the rule specifies the [severity level](../configuration-options.md#severity-level) for the rule. Severity specification as part of the above option syntax is only respected inside development IDEs, such as Visual Studio. This setting is not understood by the C# or VB compilers, hence not respected during build. Instead, to enforce code style rules on build, you should set the severity by using the rule ID-based severity configuration syntax for analyzers. The syntax takes the form `dotnet_diagnostic..severity = `, for example, `dotnet_diagnostic.IDE0040.severity = silent`. For more information, see this [GitHub issue](https://github.com/dotnet/roslyn/issues/44201). +- **Value** + + For each language rule, you specify a value that defines if or when to prefer the style. Many rules accept a value of `true` (prefer this style) or `false` (do not prefer this style). Other rules accept values such as `when_on_single_line` or `never`. + +- **Severity** (optional in Visual Studio 2019 version 16.9 Preview 2 and later versions) + + The second part of the rule specifies the [severity level](../configuration-options.md#severity-level) for the rule. When specified in this way, the severity setting is only respected inside development IDEs, such as Visual Studio. It is *not* respected during build. + + To enforce code style rules at build time, set the severity by using the rule ID-based severity configuration syntax for analyzers instead. The syntax takes the form `dotnet_diagnostic..severity = `, for example, `dotnet_diagnostic.IDE0040.severity = silent`. For more information, see [severity level](../configuration-options.md#severity-level). > [!TIP] > diff --git a/includes/code-analysis/suppress-warning.md b/includes/code-analysis/suppress-warning.md new file mode 100644 index 0000000000000..331f5eee370ea --- /dev/null +++ b/includes/code-analysis/suppress-warning.md @@ -0,0 +1,12 @@ +## Suppress a warning + +To suppress a rule violation, set the severity option for the specific rule ID to `none` in an EditorConfig file. For example: + +```ini +[*.{cs,vb}] +dotnet_diagnostic.CA1822.severity = none +``` + +Visual Studio provides additional ways to suppress warnings from code analysis rules. For more information, see [Suppress violations](/visualstudio/code-quality/use-roslyn-analyzers#suppress-violations). + +For more information about rule severities, see [Configure rule severity](~/docs/fundamentals/code-analysis/configuration-options.md#severity-level).