C# Code Analyzers - Overview
-
RavenDB ships a set of C# code analyzers embedded in the
RavenDB.ClientNuGet package.
They inspect client code at compile time, identifying common misuse patterns before the application runs. -
These C# code analyzers are distinct from the text analyzers used in index definitions for full-text search.
For tokenizers, stemmers, and language analyzers, see Using Analyzers in Indexes. -
In this article:
Installation and requirements
The analyzer assembly (Raven.Analyzers.dll) and code-fix assembly (Raven.Analyzers.CodeFixes.dll) are included in RavenDB.Client.nupkg under analyzers/dotnet/cs/.
No separate install is required.
The analyzers require Roslyn 4.4.0 or later, included in the .NET 7 SDK and Visual Studio 2022 version 17.4, and in later versions.
Older compiler hosts cannot load the analyzers and may report CS9057.
This warning can fail the build when TreatWarningsAsErrors is enabled.
To use the client package without loading the analyzers, see Disable all RavenDB analyzers for a project.
Unless excluded, the analyzers run automatically on every build once the client package is referenced.
See Apply automated code fixes for applying fixes in the IDE or from the command line.
Some rules also inspect indexes defined in referenced assemblies. The checks performed by RVN004–RVN008 are skipped when the index information they require cannot be obtained from generated metadata or available source.
Diagnostic severity
New rules default to Info severity in the client release that introduces them.
For the rules listed in this article, the default remains Info throughout the 7.2.x release line.
Diagnostics reported at Info appear in the IDE but are not printed in dotnet build output.
They do not fail builds, even with TreatWarningsAsErrors enabled.
Starting with the next major or minor client release after 7.2, these rules default to Warning,
except RVN006, RVN007, and RVN008, which remain at Info.
If TreatWarningsAsErrors is enabled, diagnostics reported as Warning can fail the build.
Address or suppress relevant occurrences before upgrading to a client version where these rules default to Warning.
You can override the default severity of individual rules in .editorconfig:
[*.cs]
dotnet_diagnostic.RVN012.severity = warning
dotnet_diagnostic.RVN013.severity = error
Suppress diagnostics
You can suppress individual RavenDB analyzer rules in a code region or matching files,
or disable all RavenDB analyzers for a project.
Suppress a diagnostic in a code region
Use #pragma warning disable followed by the rule ID before the relevant code,
and #pragma warning restore followed by the same ID after the code:
#pragma warning disable RVN014
// Code where RVN014 is intentionally suppressed.
#pragma warning restore RVN014
The suppression starts on the line after disable and lasts until restore or the end of the source file.
The restore directive restores the rule's configured reporting behavior from the following line.
Replace RVN014 with the ID of any RavenDB analyzer rule.
To suppress multiple rules, list their IDs separated by commas in both directives, such as RVN009, RVN014.
For more information, see the C# pragma warning reference.
Suppress a diagnostic in matching files
Set the rule's severity to none in .editorconfig:
[*.cs]
dotnet_diagnostic.RVN014.severity = none
The rule is suppressed in all files matched by that configuration section.
Disable all RavenDB analyzers for a project
To skip loading all analyzers supplied by RavenDB.Client, add ExcludeAssets="analyzers" to its PackageReference in the project file.
Keep your existing package version:
<PackageReference Include="RavenDB.Client" Version="..." ExcludeAssets="analyzers" />
Apply automated code fixes
Automated code fixes are suggested code changes that you can choose to apply.
RVN011 and RVN012 provide fixes for supported code patterns.
A diagnostic can still be reported when no automated fix is available; in that case, change the code manually.
Rules with automated code fixes
-
RVN011
Rewritesstore.OpenSession()/store.OpenAsyncSession()tobatch.OpenSession()/batch.OpenAsyncSession()inside a subscriptionRunlambda. -
RVN012
Rewrites independent eagerLoadcalls and queries materialized withToListorToArray(including supported async forms) into lazy registrations whose results are read through.Value(awaited for async calls).
Reading the first value sends all pending lazy operations in the same session to the server in a single request.
How to apply a code fix
Apply a fix through your IDE's quick actions, or run the following command:
dotnet format analyzers MySolution.sln --diagnostics RVN011 RVN012 --severity info
Replace MySolution.sln with the path to your project or solution file.
The --severity info option includes diagnostics reported at Info.
By default, dotnet format analyzers fixes only diagnostics reported at Warning or Error.
For more options, see the dotnet format documentation.
Available rules
| ID | Title | Area | Automated Fix |
|---|---|---|---|
| RVN001 | Index Map or Reduce assigned outside constructor | Index definition | No |
| RVN002 | RavenDB query operator after projection | Query | No |
| RVN003 | ProjectInto called more than once in a query chain | Query | No |
| RVN004 | AbstractIndexCreationTask subclass is missing a Map assignment | Index definition | No |
| RVN005 | Multi-map index has no AddMap call in any constructor | Index definition | No |
| RVN006 | Multi-map index uses only a single AddMap | Index definition | No |
| RVN007 | Query field not defined in the index | Query | No |
| RVN008 | Projected field not retrievable under the applied ProjectionBehavior | Query | No |
| RVN009 | Unsupported method call inside index Map/Reduce expression | Index definition | No |
| RVN010 | Unsupported method call inside RavenDB query expression | Query | No |
| RVN011 | Use batch.OpenSession inside a subscription Run delegate | Subscriptions | Yes |
| RVN012 | Batch independent session operations using the lazy API | Session | Yes |
| RVN013 | Query result is not bounded by Take() | Query | No |
| RVN014 | Index Map fans out over a collection | Index definition | No |
| RVN015 | Correlated conditions over a nested collection in a dynamic query | Query | No |