Workleap.DotNet.CodingStandards
0.6.1-preview.8
Prefix Reserved
See the version list below for details.
dotnet add package Workleap.DotNet.CodingStandards --version 0.6.1-preview.8
NuGet\Install-Package Workleap.DotNet.CodingStandards -Version 0.6.1-preview.8
<PackageReference Include="Workleap.DotNet.CodingStandards" Version="0.6.1-preview.8"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add Workleap.DotNet.CodingStandards --version 0.6.1-preview.8
#r "nuget: Workleap.DotNet.CodingStandards, 0.6.1-preview.8"
// Install Workleap.DotNet.CodingStandards as a Cake Addin #addin nuget:?package=Workleap.DotNet.CodingStandards&version=0.6.1-preview.8&prerelease // Install Workleap.DotNet.CodingStandards as a Cake Tool #tool nuget:?package=Workleap.DotNet.CodingStandards&version=0.6.1-preview.8&prerelease
Workleap.DotNet.CodingStandards
This package provides a set of programming standards for .NET projects, including rules for style, quality, security, and performance. It relies on built-in .NET analyzers that are shipped with the .NET SDK.
During development, the package will provide warnings ⚠️ when standards are not met. For a production build (Release
configuration), these warnings will be treated as errors ❌ and will make the build fail.
[!WARNING] This package only works with SDK-style projects. Older ASP.NET projects (non-Core) are not supported. The same applies to older desktop applications unless they have migrated to the new
Microsoft.NET.Sdk.WindowsDesktop
SDK.
Getting started
Install the NuGet package in your project:
dotnet add package Workleap.DotNet.CodingStandards
If you are using StyleCop.Analyzers, you can safely remove it from your project. You can also remove the relevant parts of your .editorconfig
files which contain analysis rules configuration.
If you also have a Directory.Build.props
file in your solution, you can remove properties that are already set by this package.
What's included
- Code style and formatting options, including indentation, line wrapping, encoding, new lines preferences, and more.
- .NET and C# coding conventions, including naming, preferences for types, modifiers, code blocks, expressions, pattern matching, using directives, parentheses, and much more.
- Project properties, including deterministic build, strict mode, continuous integration build detection, faster package restoration, and faster builds on Visual Studio, and more.
- .NET analysis rules configuration, including style rules (
IDExxxx
) and code analysis rules (CAxxxx
). These rules have been manually configured to provide a good balance between quality, performance, security, and build time. - Banned APIs, such as
DateTime.Now
andDateTimeOffset.Now
(use their UTC counterparts instead).
What's NOT included
- Enabling a specific or latest C# language version.
- Enabling nullable reference types by default.
- Enabling implicit using directives by default.
- Enforcing a specific target framework.
- Code styles for files that are not C# source files (e.g.
.csproj
,.json
, etc.).
We believe that most of these settings should be set on a per-project basis, and decided by the project's maintainers.
For files other than C# source files, it is technically impossible for this package to enforce code styles, so you will have to configure their style using your own .editorconfig
files.
How it works
This package comes with a set of .props
and .targets
files that are automatically imported into your project when you install the package. These files contain MSBuild properties and targets that configure the build process and the code analysis rules.
It also includes multiple .editorconfig
files that are automatically imported by Roslyn during the build process.
Facilitating package adoption
From experience, installing the package will result in numerous warnings, the majority of which are related to code formatting. We recommend addressing these in several steps to minimize the impact on code review, using the dotnet format utility, which is included in the .NET SDK.
Firstly, warnings related to code formatting can be automatically corrected. This includes: indentation, unnecessary spaces, empty lines, braces, file-scoped namespaces, unnecessary using directives, etc. Here is the command to execute:
dotnet format <path_to_your_solution_or_project> --diagnostics IDE0001 IDE0004 IDE0005 IDE0007 IDE0009 IDE0011 IDE0055 IDE0161 IDE2000 IDE2001 IDE2002 IDE2003 IDE2004 IDE2005 IDE2006 --verbosity diagnostic
Once the pull request is merged, one can then attempt to automatically correct the remaining warnings. Without the noise of formatting warnings, it will be easier to focus on them:
dotnet format <path_to_your_solution_or_project> --severity warn --verbosity diagnostic
You can also modify the command to specify the IDs of the analysis rules you wish to automatically correct (if a fix is available). In this way, you avoid manual work, and breaking the correction into several pull requests will increase developers' confidence in the process of adopting new standards.
All rules included in this package can be disabled or modified in an .editorconfig
file that you can add to your project. You can also disable a rule for a specific line or block of code using #pragma
directives or [SuppressMessage]
attributes. Learn more about configuring code analysis rules. Remember to always justify why a rule is disabled or modified. Here're some examples:
Disable specific diagnostics in the code
#pragma warning disable CA2200 // Rethrow to preserve stack details throw e; #pragma warning restore CA2200
Disable specific diagnostics for a method
[System.Diagnostics.CodeAnalysis.SuppressMessage("Usage", "CA2200:Rethrow to preserve stack details", Justification = "Not production code.")] void Sample() { }
Disable a rule using an .editorconfig
# Disable CA2200 globally [*.cs] dotnet_diagnostic.CA2200.severity = none # Disable CA2200 for specific files [tests/**/*.cs] dotnet_diagnostic.CA2200.severity = none
Disable NuGet auditing for a specific package
<PackageReference Include="System.Formats.Asn1" Version="8.0.0" NoWarn="NU1903" />
[!WARNING] Remember that this should be a temporary solution to help adopting the package
Finally, the warnings breaks the CI because they are treated as errors when building the Release
configuration. You can disable this behavior by setting the following MSBuild property in the .csproj
file or in the Directory.Build.props
file
````xml
<Project>
<PropertyGroup>
<TreatWarningsAsErrors>false</TreatWarningsAsErrors>
<MSBuildTreatWarningsAsErrors>false</MSBuildTreatWarningsAsErrors>
</PropertyGroup>
</Project>
````
References
- Configuration files for code analysis rules: Global analyzer options (Microsoft documentation).
- Sharing coding style and Roslyn analyzers across projects (blog post written by Gérald Barré).
- Microsoft.CodeAnalysis.NetAnalyzers package content (NuGet.info).
Build and release process
This project uses GitVersion as a .NET tool during the build process to automatically compute the version number for preview packages that are automatically published on the main branch and pull requests.
To publish a new public (non-preview) version, simply create a new release on GitHub with a x.y.z
tag.
License
Copyright © 2024, Workleap. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE.
Learn more about Target Frameworks and .NET Standard.
-
- Microsoft.CodeAnalysis.BannedApiAnalyzers (>= 3.3.4)
- Microsoft.CodeAnalysis.NetAnalyzers (>= 8.0.0)
- StyleCop.Analyzers (>= 1.2.0-beta.556)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.7.1-preview.4 | 33 | 10/30/2024 |
0.7.1-preview.3 | 34 | 10/28/2024 |
0.7.1-preview.2 | 35 | 10/28/2024 |
0.7.1-preview.1 | 32 | 10/28/2024 |
0.7.0 | 5,184 | 10/23/2024 |
0.6.1-preview.15 | 38 | 10/23/2024 |
0.6.1-preview.14 | 32 | 10/23/2024 |
0.6.1-preview.13 | 37 | 10/7/2024 |
0.6.1-preview.12 | 34 | 10/7/2024 |
0.6.1-preview.11 | 40 | 10/1/2024 |
0.6.1-preview.10 | 44 | 9/30/2024 |
0.6.1-preview.9 | 41 | 9/27/2024 |
0.6.1-preview.8 | 27 | 9/20/2024 |
0.6.1-preview.7 | 45 | 9/13/2024 |
0.6.1-preview.6 | 50 | 8/27/2024 |
0.6.1-preview.5 | 42 | 8/27/2024 |
0.6.1-preview.4 | 42 | 8/27/2024 |
0.6.1-preview.3 | 100 | 7/23/2024 |
0.6.1-preview.2 | 49 | 7/15/2024 |
0.6.1-preview.1 | 40 | 7/15/2024 |
0.6.0 | 31,791 | 7/15/2024 |
0.5.1-preview.9 | 43 | 7/15/2024 |
0.5.1-preview.8 | 41 | 7/5/2024 |
0.5.1-preview.7 | 46 | 6/14/2024 |
0.5.1-preview.6 | 49 | 6/11/2024 |
0.5.1-preview.5 | 48 | 6/10/2024 |
0.5.1-preview.3 | 54 | 5/31/2024 |
0.5.1-preview.2 | 54 | 5/21/2024 |
0.5.1-preview.1 | 58 | 5/14/2024 |
0.5.0 | 20,193 | 5/14/2024 |
0.4.1-preview.2 | 54 | 5/14/2024 |
0.4.1-preview.1 | 55 | 5/10/2024 |
0.4.0 | 420 | 5/8/2024 |
0.3.1-preview.3 | 57 | 5/8/2024 |
0.3.1-preview.2 | 66 | 4/26/2024 |
0.3.1-preview.1 | 58 | 4/24/2024 |
0.3.0 | 5,917 | 4/15/2024 |
0.2.1-preview.4 | 62 | 4/15/2024 |
0.2.1-preview.3 | 72 | 4/12/2024 |
0.2.1-preview.2 | 56 | 4/3/2024 |
0.2.1-preview.1 | 62 | 3/8/2024 |
0.2.0 | 5,846 | 3/7/2024 |
0.1.1-preview.7 | 61 | 3/7/2024 |
0.1.1-preview.6 | 54 | 3/7/2024 |
0.1.1-preview.5 | 72 | 3/7/2024 |
0.1.1-preview.4 | 68 | 3/4/2024 |
0.1.1-preview.3 | 69 | 3/4/2024 |
0.1.1-preview.2 | 59 | 2/23/2024 |
0.1.1-preview.1 | 58 | 2/20/2024 |
0.1.0 | 888 | 2/19/2024 |
0.1.0-preview.2 | 54 | 2/19/2024 |