Skip to content

Commit 34f36d9

Browse files
WhitWaldoWhitWaldo
authored
Adding Analyzer documentation, consolidating diagnostic IDs (#1515)
* Added initial pass at documentation for the various analyzers. Placing the documentation link above the "Error handling" section in leftnav. * Updated diagnostic IDs throughout solution to match values in documentation Signed-off-by: Whit Waldo <[email protected]>
1 parent d00da14 commit 34f36d9

File tree

12 files changed

+129
-50
lines changed

12 files changed

+129
-50
lines changed

‎daprdocs/content/en/dotnet-sdk-docs/dotnet-code-analysis/_index.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
type: docs
3+
title: "Overview of Dapr source code analysis"
4+
linkTitle: "Code Analysis"
5+
weight: 70000
6+
description: Code analyzers and fixes for common Dapr issues
7+
no_list: true
8+
---
9+
10+
Dapr supports a growing collection of optional Roslyn analyzers and code fix providers that inspect your code for
11+
code quality issues. Starting with the release of v1.16, developers have the opportunity to install additional projects
12+
from NuGet alongside each of the standard capability packages to enable these analyzers in their solutions.
13+
14+
{{% alert title="Note" color="primary" %}}
15+
16+
A future release of the Dapr .NET SDK will include these analyzers by default without necessitating a separate package
17+
install.
18+
19+
{{% /alert %}}
20+
21+
Rule violations will typically be marked as `Info` or `Warning` so that if the analyzer identifies an issue, it won't
22+
necessarily break builds. All code analysis violations appear with the prefix "DAPR" and are uniquely distinguished
23+
by a number following this prefix.
24+
25+
{{% alert title="Note" color="primary" %}}
26+
27+
At this time, the first two digits of the diagnostic identifier map one-to-one to distinct Dapr packages, but this
28+
is subject to change in the future as more analyzers are developed.
29+
30+
{{% /alert %}}
31+
32+
## Install and configure analyzers
33+
The following packages will be available via NuGet following the v1.16 Dapr release:
34+
- Dapr.Actors.Analyzers
35+
- Dapr.Jobs.Analyzers
36+
37+
Install each NuGet package on every project where you want the analyzers to run. The package will be installed as a
38+
project dependency and analyzers will run as you write your code or as part of a CI/CD build. The analyzers will flag
39+
issues in your existing code and warn you about new issues as you build your project.
40+
41+
Many of our analyzers have associated code fixes that can be applied to automatically correct the problem. If your IDE
42+
supports this capability, any available code fixes will show up as an inline menu option in your code.
43+
44+
Further, most of our analyzers should also report a specific line and column number in your code of the syntax that's
45+
been identified as a key aspect of the rule. If your IDE supports it, double clicking any of the analyzer warnings
46+
should jump directly to the part of your code responsible for the violating the analyzer's rule.
47+
48+
### Suppress specific analyzers
49+
If you wish to keep an analyzer from firing against some particular piece of your project, their outputs can be
50+
individually targeted for suppression through a number of ways. Read more about suppressing analyzers in projects
51+
or files in the associated [.NET documentation](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings#use-the-suppressmessageattribute).
52+
53+
### Disable all analyzers
54+
If you wish to disable all analyzers in your project without removing any packages providing them, set
55+
the `EnableNETAnalyzers` property to `false` in your csproj file.
56+
57+
## Available Analyzers
58+
59+
| Diagnostic ID | Dapr Package | Category | Severity | Version Added | Description | Code Fix Available |
60+
| -- | -- |------------------| -- | -- | -- | -- |
61+
| DAPR1401 | Dapr.Actors | Usage | Warning | 1.16 | Actor timer method invocations require the named callback method to exist on type | No |
62+
| DAPR1402 | Dapr.Actors | Usage | Warning | The actor type is not registered with dependency injection | Yes |
63+
| DAPR1403 | Dapr.Actors | Interoperability | Info | Set options.UseJsonSerialization to true to support interoperability with non-.NET actors | Yes |
64+
| DAPR1404 | Dapr.Actors | Usage | Warning | Call app.MapActorsHandlers to map endpoints for Dapr actors | Yes |
65+
| DAPR1501 | Dapr.Jobs | Usage | Warning | Job invocations require the MapDaprScheduledJobHandler to be set and configured for each anticipated job on IEndpointRouteBuilder | No |
66+
67+
## Analyzer Categories
68+
The following are each of the eligible categories that an analyzer can be assigned to and are modeled after the
69+
standard categories used by the.NET analyzers:
70+
- Design
71+
- Documentation
72+
- Globalization
73+
- Interoperability
74+
- Maintainability
75+
- Naming
76+
- Performance
77+
- Reliability
78+
- Security
79+
- Usage

‎src/Dapr.Actors.Analyzers/Dapr.Actors.Analyzers/ActorRegistrationAnalyzer.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ namespace Dapr.Actors.Analyzers;
2727
public sealed class ActorRegistrationAnalyzer : DiagnosticAnalyzer
2828
{
2929
internal static readonly DiagnosticDescriptor DiagnosticDescriptorActorRegistration = new(
30-
id: "DAPR4002",
31-
title: new LocalizableResourceString(nameof(Resources.DAPR4002Title), Resources.ResourceManager,
30+
id: "DAPR1402",
31+
title: new LocalizableResourceString(nameof(Resources.DAPR1402Title), Resources.ResourceManager,
3232
typeof(Resources)),
33-
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR4002MessageFormat), Resources.ResourceManager,
33+
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR1402MessageFormat), Resources.ResourceManager,
3434
typeof(Resources)),
3535
category: "Usage",
3636
DiagnosticSeverity.Warning,

‎src/Dapr.Actors.Analyzers/Dapr.Actors.Analyzers/AnalyzerReleases.Shipped.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
Rule ID | Category | Severity | Notes
88
--------|----------|----------|------------------------------------------------------------------------------------
9-
DAPR4001 | Usage | Warning | Actor timer method invocations require the named callback method to exist on type.
10-
DAPR4002 | Usage | Warning | The actor type is not registered with dependency injection
11-
DAPR4003 | Usage | Info | Set options.UseJsonSerialization to true to support interoperability with non-.NET actors
12-
DAPR4004 | Usage | Warning | Call app.MapActorsHandlers to map endpoints for Dapr actors.
9+
DAPR1401 | Usage | Warning | Actor timer method invocations require the named callback method to exist on type.
10+
DAPR1402 | Usage | Warning | The actor type is not registered with dependency injection
11+
DAPR1403 | Usage | Info | Set options.UseJsonSerialization to true to support interoperability with non-.NET actors
12+
DAPR1404 | Usage | Warning | Call app.MapActorsHandlers to map endpoints for Dapr actors.

‎src/Dapr.Actors.Analyzers/Dapr.Actors.Analyzers/MappedActorHandlersAnalyzer.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ namespace Dapr.Actors.Analyzers;
2727
public sealed class MappedActorHandlersAnalyzer : DiagnosticAnalyzer
2828
{
2929
internal static readonly DiagnosticDescriptor DiagnosticDescriptorMapActorsHandlers = new(
30-
id: "DAPR4004",
31-
title: new LocalizableResourceString(nameof(Resources.DAPR4004Title), Resources.ResourceManager,
30+
id: "DAPR1404",
31+
title: new LocalizableResourceString(nameof(Resources.DAPR1404Title), Resources.ResourceManager,
3232
typeof(Resources)),
33-
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR4004MessageFormat), Resources.ResourceManager,
33+
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR1404MessageFormat), Resources.ResourceManager,
3434
typeof(Resources)),
3535
category: "Usage",
3636
DiagnosticSeverity.Warning,

‎src/Dapr.Actors.Analyzers/Dapr.Actors.Analyzers/PreferActorJsonSerializationAnalyzer.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ namespace Dapr.Actors.Analyzers;
2727
public sealed class PreferActorJsonSerializationAnalyzer : DiagnosticAnalyzer
2828
{
2929
internal static readonly DiagnosticDescriptor DiagnosticDescriptorJsonSerialization = new(
30-
id: "DAPR4003",
31-
title: new LocalizableResourceString(nameof(Resources.DAPR4003Title), Resources.ResourceManager,
30+
id: "DAPR1403",
31+
title: new LocalizableResourceString(nameof(Resources.DAPR1403Title), Resources.ResourceManager,
3232
typeof(Resources)),
33-
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR4003MessageFormat), Resources.ResourceManager,
33+
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR1403MessageFormat), Resources.ResourceManager,
3434
typeof(Resources)),
3535
category: "Usage",
3636
DiagnosticSeverity.Info,

‎src/Dapr.Actors.Analyzers/Dapr.Actors.Analyzers/Resources.Designer.cs‎

Lines changed: 16 additions & 16 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/Dapr.Actors.Analyzers/Dapr.Actors.Analyzers/Resources.resx‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,28 +18,28 @@
1818
<resheader name="writer">
1919
<value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
2020
</resheader>
21-
<data name="DAPR4001Title" xml:space="preserve">
21+
<data name="DAPR1401Title" xml:space="preserve">
2222
<value>Actor timer method invocations require the named callback method to exist on type</value>
2323
</data>
24-
<data name="DAPR4001MessageFormat" xml:space="preserve">
24+
<data name="DAPR1401MessageFormat" xml:space="preserve">
2525
<value>Actor timer method invocations require the named callback '{0}' method to exist on type '{1}'</value>
2626
</data>
27-
<data name="DAPR4002Title" xml:space="preserve">
27+
<data name="DAPR1402Title" xml:space="preserve">
2828
<value>The actor type is not registered with dependency injection</value>
2929
</data>
30-
<data name="DAPR4002MessageFormat" xml:space="preserve">
30+
<data name="DAPR1402MessageFormat" xml:space="preserve">
3131
<value>The actor type '{0}' is not registered with dependency injection</value>
3232
</data>
33-
<data name="DAPR4003MessageFormat" xml:space="preserve">
33+
<data name="DAPR1403MessageFormat" xml:space="preserve">
3434
<value>Set options.UseJsonSerialization to true to support interoperability with non-.NET actors</value>
3535
</data>
36-
<data name="DAPR4003Title" xml:space="preserve">
36+
<data name="DAPR1403Title" xml:space="preserve">
3737
<value>Set options.UseJsonSerialization to true to support interoperability with non-.NET actors</value>
3838
</data>
39-
<data name="DAPR4004MessageFormat" xml:space="preserve">
39+
<data name="DAPR1404MessageFormat" xml:space="preserve">
4040
<value>Call app.MapActorsHandlers to map endpoints for Dapr actors</value>
4141
</data>
42-
<data name="DAPR4004Title" xml:space="preserve">
42+
<data name="DAPR1404Title" xml:space="preserve">
4343
<value>Call app.MapActorsHandlers to map endpoints for Dapr actors</value>
4444
</data>
4545
</root>

‎src/Dapr.Actors.Analyzers/Dapr.Actors.Analyzers/TimerCallbackMethodPresentAnalyzer.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,9 @@ namespace Dapr.Actors.Analyzers;
2727
public sealed class TimerCallbackMethodPresentAnalyzer : DiagnosticAnalyzer
2828
{
2929
internal static readonly DiagnosticDescriptor DaprTimerCallbackMethodRule = new(
30-
id: "DAPR4001",
31-
title: new LocalizableResourceString(nameof(Resources.DAPR4001Title), Resources.ResourceManager, typeof(Resources)),
32-
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR4001MessageFormat), Resources.ResourceManager, typeof(Resources)),
30+
id: "DAPR1401",
31+
title: new LocalizableResourceString(nameof(Resources.DAPR1401Title), Resources.ResourceManager, typeof(Resources)),
32+
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR1401MessageFormat), Resources.ResourceManager, typeof(Resources)),
3333
category: "Usage",
3434
DiagnosticSeverity.Warning,
3535
isEnabledByDefault: true

‎src/Dapr.Jobs.Analyzer/AnalyzerReleases.Shipped.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@
44

55
Rule ID | Category | Severity | Notes
66
--------|----------|----------|--------------------
7-
DAPR3001| Usage | Warning | Job invocations require the MapDaprScheduledJobHandler be set and configured for each anticipated job on IEndpointRouteBuilder
7+
DAPR1501 | Usage | Warning | Job invocations require the MapDaprScheduledJobHandler be set and configured for each anticipated job on IEndpointRouteBuilder

‎src/Dapr.Jobs.Analyzer/MapDaprScheduledJobHandlerAnalyzer.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ namespace Dapr.Jobs.Analyzers
1414
public sealed class MapDaprScheduledJobHandlerAnalyzer : DiagnosticAnalyzer
1515
{
1616
internal static readonly DiagnosticDescriptor DaprJobHandlerRule = new (
17-
id: "DAPR3001",
18-
title: new LocalizableResourceString(nameof(Resources.DAPR3001Title), Resources.ResourceManager, typeof(Resources)),
19-
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR3001MessageFormat), Resources.ResourceManager, typeof(Resources)),
17+
id: "DAPR1501",
18+
title: new LocalizableResourceString(nameof(Resources.DAPR1501Title), Resources.ResourceManager, typeof(Resources)),
19+
messageFormat: new LocalizableResourceString(nameof(Resources.DAPR1501MessageFormat), Resources.ResourceManager, typeof(Resources)),
2020
category: "Usage",
2121
DiagnosticSeverity.Warning,
2222
isEnabledByDefault: true

0 commit comments

Comments
 (0)