Introduction
Roslyn Analyzers offer significant value to .NET developers. They identify code issues and vulnerabilities and inform developers about necessary fixes directly in the IDE, through both the output window and the code editor. Some analyzers even have the capability of fixing automatically one or several issues at once.
However, how does one manage Roslyn Analyzer issues within the CI/CD pipeline? In this post, we’ll explore how the latest NDepend version 2024.1 enhances the reporting capabilities by:
- Creating interactive HTML reports that provide a navigable overview of issues detected by Roslyn Analyzers.
- Categorizing issues into newly identified, unresolved, and fixed ones, aiding teams in prioritizing their efforts towards continuous improvement.
- Enabling the build process to fail based on specific conditions related to Roslyn Analyzer issues, ensuring code quality standards are met before progression.
- Completing the set of Roslyn Analyzers with additional kind of rules.
Exporting Roslyn Analyzer’s Issues
To report Roslyn Analyzer’s issues, one must first export them at build process time. This can be achieved easily with the <ErrorLog> option. For example, at the root of your .NET solution(s) a simple Directory.Build.Props file can both:
- define the Roslyn Analyzers suite(s) that scan your code,
- and export the issues in files in the
$(SolutionDir)\.sarifdirectory
Here is the Directory.Build.Props file content to import the popular suites:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<Project> <PropertyGroup> <ErrorLog>$(SolutionDir)\.sarif\$(MSBuildProjectName).json</ErrorLog> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0"> <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> <PrivateAssets>all</PrivateAssets> </PackageReference> <PackageReference Include="Roslynator.Analyzers" Version="4.11.0"> <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> <PrivateAssets>all</PrivateAssets> </PackageReference> <PackageReference Include="Meziantou.Analyzer" Version="2.0.146"> <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> <PrivateAssets>all</PrivateAssets> </PackageReference> </ItemGroup> |
Thanks to <ErrorLog>$(SolutionDir)\.sarif\$(MSBuildProjectName).json</ErrorLog> the build process exports Roslyn Analyzers’ issues in .json files, one per project. The json format is SARIF which stands for Static Analysis Results Interchange Format.
By default, NDepend reads these .json file in the $(SolutionDir)\.sarif directory although this is configurable as explained here. Keep in mind that if you use .editorconfig files to disable certain Roslyn Analyzers or set their severity levels, these configurations are reflected in the issues exported to the SARIF files.
Listing Roslyn Analyzers Violated
Roslyn Analyzers with issues are then listed in the report, side by side with the NDepend C# LINQ based rule’s issues (CQLinq rules). See this report live here:
For each Roslyn Analyzer, it’s possible to view the count of new, unresolved, and resolved issues compared to the baseline. Notice that the first time the report is created there is no baseline to compare with unless you compare with the last version released. However, after further code modifications and scans, the differences highlighted will become more prominent and useful.
Two buttons enable the selection of either only Roslyn Analyzers or only CQLinq rules. Notice how CQLinq rules focus on complementary areas including code coverage by tests, code smells regression since the baseline, and the overall code architecture.
Listing Issues of a Roslyn Analyzer
Clicking on a Roslyn Analyzer allows to jump directly to its list of issues within the report (see it live here). Each analyzer includes a link to its online description. When an analyzer provides its own description, this information is collected and displayed above the list of issues.
Reporting Roslyn Analyzer’s Issues in the Source Code
Clicking on an issue from a Roslyn Analyzer displays it in the source code section of the report, accompanied by its message (see it live here):
This comprehensive view offers several key features:
- It makes it easy to review differences introduced since the baseline.
- It visually marks code coverage sections in green and red.
- It differentiates among new, unresolved, and resolved issues.
- It includes extra metrics for the source file, such as statement counts and an estimation of the effort required to address issues (technical debt).
Refining the Scope
The Rule view encompasses issues across the entire application, which may be too broad. You might prefer to narrow your focus to the project level or even the source file level:
Defining Quality Gates based on some Roslyn Analyzers’ Conditions
When scanning any substantial code base, code rules and Roslyn Analyzers often produce a vast array of issues. This flood of information can be overwhelming and requires careful sorting to determine whether the issues are tolerable for the team or not. This is not a job you want to do manually. Here come the Quality Gates: a set of objective criteria to decide if the code can be released as-is, or if it requires additional work on quality or potential bugs or vulnerabilities.
As with CQLinq rules, in NDepend Quality Gates are simple C# LINQ queries executed against the code and the issues set. For instance, the default Quality Gate Treat Compiler Warnings as Error identifies compiler warnings and fails the build if more than 10 are detected. Quality Gates being C# LINQ queries simplifies the process of modifying existing ones or creating new ones.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
// <QualityGate Name="Treat Compiler Warnings as Error" Unit="issues" /> failif count > 10 warnif count > 0 from issue in context.IssuesSet.AllIssues.Where( i => i.Rule.Provider == RuleProvider.Import && i.Rule.Id.StartsWithAny("CS","VB")) select new { issue, Explanation =issue.GetExplanation() } //<Desc> // Many compiler warnings, if ignored, could lead to runtime errors, // unpredictable behavior, or security vulnerabilities. // Addressing these warnings early can prevent such issues from // becoming real problems in production. // ... |
Conclusion
In conclusion, effectively reporting Roslyn Analyzer issues is pivotal in maintaining the integrity and quality of your .NET projects. Interactive and lightweight web reports are effortless to generate without the need for costly servers to setup and maintain. By categorizing and transforming these issues into actionable insights, teams can significantly enhance their workflows. Ultimately, embracing these practices ensures that your code remains robust, efficient, and aligned with best practices.