# .NET SDK Code Analysis

## Open/Free Status

- first-party .NET SDK analyzers
- free to use
- included with the modern .NET SDK

## Install

For projects targeting .NET 5 or later, built-in analyzers are included with the SDK and code analysis is enabled by default.

For older or explicitly controlled projects, set analyzer properties in the project or `Directory.Build.props`:

```xml
<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <AnalysisLevel>latest-recommended</AnalysisLevel>
</PropertyGroup>
```

## Verify First

Before adding anything, check whether the repo already set analyzer policy:

```bash
rg -n "EnableNETAnalyzers|AnalysisLevel|AnalysisMode|TreatWarningsAsErrors" -g 'Directory.Build.*' -g '*.csproj' .
```

## Common Commands

```bash
dotnet build MySolution.sln
dotnet build MySolution.sln -warnaserror
```

## CI Fit

- use `dotnet build` as the analyzer gate
- keep `AnalysisLevel` explicit in MSBuild
- keep rule severity in the repo-root `.editorconfig`

## When Not To Use

- when you only need a formatter
- when the repo specifically needs a framework or third-party analyzer set beyond the built-in SDK rules

## Sources

- [Overview of .NET source code analysis](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/overview)

# MSBuild Properties and .editorconfig for Code Analysis

## MSBuild Properties

Set in `Directory.Build.props` or project files.

### EnableNETAnalyzers

```xml
<EnableNETAnalyzers>true</EnableNETAnalyzers>
```
Default true in .NET 5+. Set explicitly to prevent accidental disabling.

### AnalysisLevel

Values: `5.0`–`10.0` (specific SDK), `latest`, `latest-recommended`, `latest-minimum`, `latest-all`, `preview`.

Combined syntax includes mode: `<AnalysisLevel>latest-recommended</AnalysisLevel>` equals `latest` + `Recommended` mode.

### AnalysisMode

Values: `None` (all off), `Default`, `Minimum` (critical only), `Recommended` (start here), `All`.

### Category-Specific AnalysisMode

```xml
<AnalysisLevel>latest-recommended</AnalysisLevel>
<AnalysisModeSecurity>All</AnalysisModeSecurity>
<AnalysisModeReliability>All</AnalysisModeReliability>
```
Categories: Design, Documentation, Globalization, Interoperability, Maintainability, Naming, Performance, Reliability, Security, Usage.

### TreatWarningsAsErrors

```xml
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
```
All warnings fail the build. Use for new projects or clean codebases. Agent rule: never disable to make a build pass.

### WarningsAsErrors (selective — preferred for legacy)

```xml
<WarningsAsErrors>CS8019;CS0219;CS0168;CA2000;CA3001</WarningsAsErrors>
```
Promote specific IDs to errors. Preferred for gradual adoption: add IDs as you fix each batch. Agent rule: never remove IDs from this list to make a build pass.

### WarningsNotAsErrors

```xml
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<WarningsNotAsErrors>CA1707</WarningsNotAsErrors>
```
Explicit exceptions when using TreatWarningsAsErrors.

### NoWarn

```xml
<NoWarn>$(NoWarn);CA1062</NoWarn>
```
Disables warnings entirely. Use sparingly; prefer .editorconfig for visibility.

### EnforceCodeStyleInBuild

```xml
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
```
Enables IDE code style rules during build (off by default for performance).

## .editorconfig

Place at repo root. Rules cascade to subdirectories.

### Severity per rule

```editorconfig
[*.cs]
dotnet_diagnostic.CA2000.severity = error
dotnet_diagnostic.CA1707.severity = none
```

### Severity per category (.NET 6+)

```editorconfig
[*.cs]
dotnet_analyzer_diagnostic.category-Security.severity = error
dotnet_analyzer_diagnostic.category-Performance.severity = warning
```

### Scope patterns

```editorconfig
[**/Tests/**/*.cs]
dotnet_diagnostic.CA1707.severity = none
dotnet_diagnostic.CA1062.severity = none

[*.generated.cs]
generated_code = true
```

### Code Style Settings

```editorconfig
[*.cs]
csharp_style_namespace_declarations = file_scoped:suggestion
csharp_style_expression_bodied_methods = when_on_single_line:suggestion
csharp_style_expression_bodied_properties = true:suggestion
csharp_style_pattern_matching_over_as_with_null_check = true:warning
csharp_style_pattern_matching_over_is_with_cast_check = true:warning
csharp_style_prefer_null_check_over_type_check = true:suggestion
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_var_elsewhere = true:suggestion
```

### Formatting Settings

```editorconfig
[*.cs]
indent_style = space
indent_size = 4
tab_width = 4
csharp_new_line_before_open_brace = all
csharp_new_line_before_else = true
csharp_new_line_before_catch = true
csharp_new_line_before_finally = true
```

## Recommended Starting Configuration

### Directory.Build.props

```xml
<Project>
  <PropertyGroup>
    <EnableNETAnalyzers>true</EnableNETAnalyzers>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>
```

### .editorconfig (root)

```editorconfig
root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.cs]
dotnet_analyzer_diagnostic.category-Security.severity = error
dotnet_analyzer_diagnostic.category-Reliability.severity = warning

[**/Tests/**/*.cs]
dotnet_diagnostic.CA1707.severity = none
dotnet_diagnostic.CA1062.severity = none
```

## Verification

```bash
dotnet build
dotnet build /p:ReportAnalyzer=true
```

## References

- [AnalysisLevel](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#analysislevel)
- [Configuration options](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-options)
- [EditorConfig](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-files)
- [Suppress warnings](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings)

# SDK Analyzer Rule Categories

This reference covers the built-in .NET SDK analyzer rule categories, their prefixes, and practical guidance for each.

## Rule Prefix Summary

| Prefix | Category | Scope |
|--------|----------|-------|
| CA | Code Analysis | Design, reliability, security, performance, usage |
| IDE | IDE Analyzers | Code style, simplification, formatting |
| CS | C# Compiler Warnings | Language-level warnings promoted by analyzers |

## CA Rules: Code Analysis

CA rules are the primary SDK analyzer rules. They cover correctness, performance, and security.

### CA1xxx: Design Rules

- Ensure proper API design and naming.
- Examples: CA1000 (do not declare static members on generic types), CA1010 (collections should implement generic interface).
- High value for public APIs.

### CA2xxx: Usage and Reliability

- Detect misuse of framework types and patterns.
- Examples: CA2000 (dispose objects before losing scope), CA2007 (consider calling ConfigureAwait).
- Enable these early; they catch real bugs.

### CA3xxx: Security

- Identify security vulnerabilities.
- Examples: CA3001 (SQL injection), CA3075 (insecure DTD processing).
- Critical for any user-facing or network-connected code.

### CA5xxx: Security (Extended)

- Extended security rules for cryptography, serialization, and input handling.
- Examples: CA5350 (do not use weak cryptographic algorithms), CA5394 (do not use insecure randomness).
- Enable for production systems handling sensitive data.

### CA18xx, CA19xx: Performance

- Detect performance anti-patterns.
- Examples: CA1802 (use literals where appropriate), CA1860 (avoid Length/Count zero checks).
- High value for hot paths and resource-constrained environments.

## IDE Rules: Code Style

IDE rules enforce consistency and simplify code.

### IDE0001-IDE0099: Code Simplification

- Remove unnecessary code, simplify expressions.
- Examples: IDE0001 (simplify name), IDE0017 (use object initializers).
- Useful for codebase consistency.

### IDE0100-IDE0199: Language Feature Preferences

- Prefer modern C# features.
- Examples: IDE0160 (file-scoped namespace preference), IDE0161 (convert to block-scoped namespace).
- Align with team style guide.

### IDE0200-IDE0299: Expression Preferences

- Expression-bodied members, pattern matching, null checks.
- Examples: IDE0200 (unnecessary lambda expression), IDE0270 (use coalesce expression).
- Enforce via .editorconfig for consistency.

### IDE1xxx: Formatting

- Whitespace, indentation, newlines.
- Examples: IDE1005 (delegate invocation should be conditional).
- Typically set to suggestion or silent; enforce in CI only when the team agrees.

## Severity Levels

| Severity | Build Behavior | Use Case |
|----------|----------------|----------|
| error | Fails build | Critical correctness or security |
| warning | Logged, may fail with TreatWarningsAsErrors | Important but deferrable |
| suggestion | IDE hint only | Style preferences |
| silent | Rule runs but no diagnostic | Rule disabled for output but still analyzed |
| none | Rule disabled | Not applicable to this codebase |

## Suppression Strategies

### Inline Suppression

```csharp
#pragma warning disable CA2000
var resource = new Resource();
#pragma warning restore CA2000
```

Use sparingly. Always include a justification comment.

### GlobalSuppressions.cs

```csharp
[assembly: SuppressMessage("Reliability", "CA2000:Dispose objects before losing scope",
    Justification = "Ownership transferred to caller", Scope = "member",
    Target = "~M:MyClass.CreateResource")]
```

Prefer for project-wide suppression of known false positives.

### .editorconfig

```editorconfig
# Disable specific rule for all files
dotnet_diagnostic.CA1062.severity = none

# Disable for test files only
[**/Tests/**/*.cs]
dotnet_diagnostic.CA1707.severity = none
```

Prefer for category-level or scope-based configuration.

## Rule Selection Guidance

1. Start with `AnalysisMode = Recommended` to get the common high-value rules.
2. Promote security rules (CA3xxx, CA5xxx) to error for production code.
3. Treat CA2xxx reliability rules as warnings initially; promote to error as the codebase matures.
4. Enforce IDE rules only when the team has agreed on style conventions.
5. Do not enable all rules at maximum severity immediately; ramp up over time.

## Discovering Available Rules

```bash
# List all analyzer diagnostics from a build
dotnet build /p:ReportAnalyzer=true /v:d | grep "CA\|IDE"

# Get rule documentation
# https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/
# https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/
```

## References

- [Code quality rules](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/)
- [Code style rules](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/)
- [Configure analyzers](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-files)