Diagnostic Code Analysis for ASP.NET API Versioning
.NET compiler platform analyzers inspect application code for code quality and style issues using ASP.NET API Versioning.
| ID | Category | Description | |
|---|---|---|---|
| AV0001 | Usage | Invalid API version | |
| AV0002 | Usage | Invalid API version range | |
| AV0003 | Usage | Invalid API version status | |
| AV0004 | Usage | Invalid API version number | |
| AV0005 | Usage | Invalid API version year | |
| AV0006 | Usage | Invalid API version month | |
| AV0007 | Usage | Invalid API version day | |
| AV0008 | Usage | Invalid API version date | |
| AV0009 | Usage | Invalid API version format specifier | |
| AV0010 | Usage | Unexpected API version format | |
| AV0011 | Style | Remove unnecessary default API version | |
| AV0012 | Usage | Invalid default API version | |
| AV0013 | Usage | Missing AddMvc | |
| AV0014 | Usage | Missing API behavior | |
| AV0015 | Performance | Use a specific API version reader | |
| AV0016 | Usage | Do not assume default API version | |
| AV0017 | Usage | Remove unnecessary default value | |
| AV0018 | Usage | All endpoints are version-neutral | |
| AV0019 | Usage | Versioned and version-neutral | |
| AV0020 | Style | Remove unnecessary API explorer | |
| AV0021 | Usage | Use the versioned API explorer | |
| AV0022 | Usage | Missing AddOData | |
| AV0023 | Usage | Route components are ignored | |
| AV0024 | Usage | Remove unnecessary API explorer option | |
| AV0025 | Documentation | Missing OpenAPI document description | |
| AV0026 | Usage | Remove unnecessary group name format | |
| AV0027 | Usage | Use DescribeApiVersions | |
| AV0028 | Usage | Sunset policy takes effect before deprecation | |
| AV0029 | Usage | Remove unnecessary OpenAPI services | |
| AV0030 | Usage | Missing WithDocumentPerVersion | |
| AV0031 | Usage | Missing API explorer |
Reporting
Most rules report as you type, but some report only when the project is built.
A rule that judges a single expression decides as soon as that expression is written. AV0017, for example, sees an assignment and has everything it needs. A rule that compares one call against another cannot decide until every file has been read, because the call it is looking for may be in a file that is not open. AV0028 cannot report a sunset until it has seen every deprecation, and AV0027 reports because a call is missing, which is only known once there is nothing left to read.
The rules that report only on build are AV0013, AV0015, AV0016, AV0018, AV0019, AV0020, AV0021, AV0022, AV0023, AV0024, AV0026, AV0027, AV0028, AV0029, AV0030, and AV0031. The rest report live in the editor.
These rules also report live in an editor configured to analyze the whole solution rather than only the documents that are open:
- Visual Studio: Tools → Options → Text Editor → C# → Advanced → Run background code analysis for → Entire solution
- Rider: enable Solution-Wide Analysis
- Visual Studio Code:
"dotnet.backgroundAnalysis.analyzerDiagnosticsScope": "fullSolution"
Suppression
A single rule is configured the same way as any other analyzer, by severity in an .editorconfig file:
[*.cs]
dotnet_diagnostic.AV0028.severity = none
All of the rules are turned off at once with a property, which removes the analyzers instead of silencing each rule:
<PropertyGroup>
<EnableApiVersioningAnalyzers>false</EnableApiVersioningAnalyzers>
</PropertyGroup>
Set it in Directory.Build.props to apply it to every project in a solution. The rules are enabled unless the
property is false.
Important
ExcludeAssets="analyzers"on a package reference does not turn the rules off. The packages that ship the analyzers are also reached through the dependencies of other packages, and NuGet combines the assets from every path that reaches a package, so an exclusion on one path is undone by another that has none. Use the property above instead.