SquiggleCop.Tasks 1.0.13

dotnet add package SquiggleCop.Tasks --version 1.0.13                
NuGet\Install-Package SquiggleCop.Tasks -Version 1.0.13                
此命令旨在在 Visual Studio 的包管理器控制台中使用,因为它使用了 NuGet 模块版本的 Install-Package.
<PackageReference Include="SquiggleCop.Tasks" Version="1.0.13">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>                
对于支持 PackageReference 的项目,将此 XML 节点复制到项目文件以引用此包。
paket add SquiggleCop.Tasks --version 1.0.13                
#r "nuget: SquiggleCop.Tasks, 1.0.13"                
#r 指令可用于 F# Interactive 和 Polyglot Notebooks。将其复制到交互工具或脚本的源代码中以引用此包。
// Install SquiggleCop.Tasks as a Cake Addin
#addin nuget:?package=SquiggleCop.Tasks&version=1.0.13

// Install SquiggleCop.Tasks as a Cake Tool
#tool nuget:?package=SquiggleCop.Tasks&version=1.0.13                

Icon

SquiggleCop

防止对 .NET (Roslyn) 分析器的无意配置更改。

NuGet Version NuGet Version Main build

.NET 构建中配置诊断警告和错误级别的有许多方法,而了解它们如何相互作用的正确性可能很困难。.NET / MSBuild 支持所有这些机制(以及可能更多的!)来配置启用了哪些分析器以及其严重级别

要跟踪的内容实在太多了!

使用SquiggleCop,任何对项目文件或构建脚本的更改都会生成一个易于理解(并diff!)的基线文件,该文件显示了更改的后果

<table> <tr> <th>代码更改</th> </tr> <tr> <td>

--- a/sample.csproj
+++ b/sample.csproj
@@ -3,7 +3,7 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net8.0</TargetFramework>
-    <AnalysisLevel>5</AnalysisLevel>
+    <AnalysisLevel>6</AnalysisLevel>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>

</td> <tr> <th>基线文件diff</th> </tr> <tr> <td>

--- a/SquiggleCop.Baseline.yaml
+++ b/SquiggleCop.Baseline.yaml
@@ -57,8 +57,8 @@
 - {Id: CA1401, Title: P/Invokes should not be visible, Category: Interoperability, DefaultSeverity: Note, IsEnabledByDefault: true, EffectiveSeverities: [Note], IsEverSuppressed: false}
 - {Id: CA1416, Title: Validate platform compatibility, Category: Interoperability, DefaultSeverity: Warning, IsEnabledByDefault: true, EffectiveSeverities: [Warning], IsEverSuppressed: false}
 - {Id: CA1417, Title: Do not use 'OutAttribute' on string parameters for P/Invokes, Category: Interoperability, DefaultSeverity: Warning, IsEnabledByDefault: true, EffectiveSeverities: [Warning], IsEverSuppressed: false}
-- {Id: CA1418, Title: Use valid platform string, Category: Interoperability, DefaultSeverity: Warning, IsEnabledByDefault: true, EffectiveSeverities: [None], IsEverSuppressed: true}
-- {Id: CA1419, Title: Provide a parameterless constructor that is as visible as the containing type for concrete types derived from 'System.Runtime.InteropServices.SafeHandle', Category: Interoperability, DefaultSeverity: Note, IsEnabledByDefault: true, EffectiveSeverities: [None], IsEverSuppressed: true}
+- {Id: CA1418, Title: Use valid platform string, Category: Interoperability, DefaultSeverity: Warning, IsEnabledByDefault: true, EffectiveSeverities: [Warning], IsEverSuppressed: false}
+- {Id: CA1419, Title: Provide a parameterless constructor that is as visible as the containing type for concrete types derived from 'System.Runtime.InteropServices.SafeHandle', Category: Interoperability, DefaultSeverity: Note, IsEnabledByDefault: true, EffectiveSeverities: [Note], IsEverSuppressed: false}
 - {Id: CA1420, Title: 'Property, type, or attribute requires runtime marshalling', Category: Interoperability, DefaultSeverity: Warning, IsEnabledByDefault: true, EffectiveSeverities: [None], IsEverSuppressed: true}
 - {Id: CA1421, Title: This method uses runtime marshalling even when the 'DisableRuntimeMarshallingAttribute' is applied, Category: Interoperability, DefaultSeverity: Note, IsEnabledByDefault: true, EffectiveSeverities: [None], IsEverSuppressed: true}
 - {Id: CA1422, Title: Validate platform compatibility, Category: Interoperability, DefaultSeverity: Warning, IsEnabledByDefault: true, EffectiveSeverities: [None], IsEverSuppressed: false}

</td> </tr> </table>

SquiggleCop解析编译器输出,以创建所有.NET(Roslyn)分析器规则及其配置严重级别的基线文件。该基线文件应该被加入源代码管理。在后续运行中,新的基线将与其他文件进行比较。如果基线不匹配,则可能是意外配置更改并应加以修复,或者应更新基线以记录新的预期配置。

SquiggleCop提供MSBuild任务和CLI工具两种形式,以便于将其集成到现有的开发流程中。

入门指南

使用SARIF日志

SquiggleCop使用SARIF v2.1文件来发挥作用。如果需要,SquiggleCop将自动启用SARIF日志并将它们放在obj/文件夹中。如果您想要/需要自定义SARIF输出路径,请参阅设置SARIF输出路径

CLI工具

CLI工具旨在进行零散验证和与基线文件交互。通过运行此命令安装CLI工具

dotnet tool install SquiggleCop.Tool

要生成或比较新的基线,运行此generate命令

Usage: dotnet squigglecop generate [--auto-baseline] [--output <String>] [--context <Int32>] [--help] sarif

Arguments:
  0: sarif    The SARIF log to generate a baseline for (Required)

Options:
  -a, --auto-baseline      Automatically update baseline if necessary
  -o, --output <String>    The output path for the baseline file
  -c, --context <Int32>    Number of context lines to use in the diff (Default: 3)
  -h, --help               Show help message

MSBuild任务

Tasks包会自动使用MSBuild将SquiggleCop集成到构建中。该包旨在在大规模构建中生成基线,并持续验证基线和防止意外的构建更改。

以下是添加Tasks包的方法

dotnet add package SquiggleCop.Tasks

如果您使用中心包管理(CPM),可以使用GlobalPackageReference在项目自动将SquiggleCop添加。

<Project>
  <ItemGroup>
    <GlobalPackageReference Include="SquiggleCop.Tasks" Version="{{version}}" />
  </ItemGroup>
</Project>

如果新的基线文件与现有文件不匹配,SquiggleCop会发出MSBuild警告SQ2000: 基线不匹配。可以使用SquiggleCop CLI创建新的基线,或者通过以下方式启用自动基线

<Project>
  <PropertyGroup>
    <SquiggleCop_AutoBaseline>true</SquiggleCop_AutoBaseline>
  </PropertyGroup>
</Project>

自动基线开启时,在提交代码之前,一定要检查基线文件中的任何更改。

[!警告]如果您启动自动基线,请务必在CI中关闭它。否则SquiggleCop可能无法警告潜在的问题!

基线文件的结构

基线文件是一个结构重复的YAML文件。以下是单个规则条目

- Id: CA1000
  Title: Do not declare static members on generic types
  Category: Design
  DefaultSeverity: Note
  IsEnabledByDefault: true
  EffectiveSeverities:
  - Note
  - None
  IsEverSuppressed: true

ID

这是诊断的ID。

Title

诊断的标题。注意,某些诊断可能具有单个ID的多个标题。例如,根据配置方式的不同,IDE0053的标题可以是“为lambda表达式使用块体”或“为lambda表达式使用表达式体”。

Category

诊断的类别。有关更多信息,请参阅分析器配置

DefaultSeverity

诊断的默认严重性。

IsEnabledByDefault

如果诊断默认启用。

EffectiveSeverities

在考虑所有选项(即规则集、.editorconfig、.globalconfig等)后,诊断的严重性或严重性级别。导致多个实际严重性的常见方式是使用针对代码库不同部分的不同.editorconfig文件。注意,行内抑制不会显示在这里,而是在IsEverSuppressed中显示。

IsEverSuppressed

如果诊断在调用站点处被抑制过,则为true。常用的做法是

  • 预处理器指令
  • 抑制消息
  • <分析级别>

诊断基线不匹配

在CI中发生但本地未发生的基线不匹配的调试最容易的方法是:

  1. 上传构建过程中的SARIF文件
  2. 使用SquiggleCop CLI从CI SARIF文件生成新的基线,并将其与已签入的基线进行比较

上传SARIF报告

将SARIF报告作为流水线工件上传,以帮助缩小问题范围。

GitHub Actions
- name: Upload SARIF logs
  uses: actions/upload-artifact@v4
  if: success() || failure() # Upload logs even if the build failed
  with:
    name: SARIF logs
    path: ./artifacts/**/*.sarif # Modify as necessary to point to your sarif files
Azure DevOps
- task: CopyFiles@2
  displayName: 'Copy SARIF files to Artifact Staging'
  condition: succeededOrFailed() # Upload logs even if the build failed
  inputs:
    contents: 'artifacts\**\*.sarif' # Modify as necessary to point to your sarif files
    targetFolder: '$(Build.ArtifactStagingDirectory)\sarif'
    cleanTargetFolder: true
    overWrite: true

- task: PublishPipelineArtifact@1
  displayName: 'Publish SARIF files as Artifacts'
  condition: succeededOrFailed() # Upload logs even if the build failed
  inputs:
    targetPath: '$(Build.ArtifactStagingDirectory)\sarif'
    publishLocation: 'pipeline'
    artifact: 'sarif'

基线不匹配的常见原因

  • 本地与CI中的不同MSBuild参数
    • 还要检查设置是否基于$(ContinuousIntegrationBuild)属性,一些CI提供商设置了此属性
  • 不同的SDK版本
    • 使用global.json设置本地和CI中相同的SDK版本
    • 新的SDK特性版本可能会导致引入新的分析器,因此建议将rollForward限制为修补更新,或者完全禁用

高级配置

设置SARIF输出路径

如果ErrorLog属性未设置,SquiggleCop会在CoreCompile目标之前将其设置为。要设置自定义的SARIF输出路径,将属性设置为如下所示:

<ErrorLog>$(MSBuildProjectFile).sarif,version=2.1</ErrorLog>

[!TIP] 我们建议您将*.sarif添加到您的.gitignore文件中

或将其在命令行作为临时验证的一部分设置属性

dotnet build -p:ErrorLog=diagnostics.sarif%2cversion=2.1

[!IMPORTANT] 日志路径中的逗号或分号字符必须进行XML转义

备选基线路径

默认情况下,SquiggleCop期望基线文件命名为SquiggleCop.Baseline.yaml并放在项目文件旁边。要指定基线文件的自定义路径,请在AdditionalFiles中添加一个指向基线文件的项

<Project>
  <ItemGroup>
    <AdditionalFiles Include="/path/to/SquiggleCop.Baseline.yaml" />
  </ItemGroup>
</Project>

TreatWarningsAsErrors

通常,项目会在CI构建中使用TreatWarningsAsErrors以防止警告进入主分支。

但是,切换TreatWarningsAsErrors 也会更改分析诊断的实际严重性,这可能导致基线文件中出现不必要的波动。如果您的项目或开发工作流程在CI和本地开发之间切换TreatWarningsAsErrors,还可以根据相同的逻辑切换SquiggleCop_Enabled属性。

这里是一个根据ContinuousIntegrationBuild属性切换TreatWarningsAsErrors的示例

<Project>
  <PropertyGroup>
    <PedanticMode Condition=" '$(PedanticMode)' == '' ">$([MSBuild]::ValueOrDefault('$(ContinuousIntegrationBuild)', 'false'))</PedanticMode>
    <TreatWarningsAsErrors>$(PedanticMode)</TreatWarningsAsErrors>
    <SquiggleCop_Enabled>$(PedanticMode)</SquiggleCop_Enabled>
  </PropertyGroup>
</Project>

编码与换行符

基线文件使用UTF-8编码写入,不带BOM。基线文件使用所有平台的\n换行符。SquiggleCop的自己的差异算法忽略换行符差异以避免不必要的差异,但根据您的.gitattributes设置,换行符可能被规范化为其他值。如果Git的换行符规范化引起问题,请考虑在您的.gitattributes文件中设置以下内容:

# Store SquiggleCop baselines as lf regardless of platform
SquiggleCop.Baseline.yaml text eol=lf

然后运行git add --renormalize .来更新Git以使用重新规范的文件。


图标“分形”由Bohdan Burmich在Noun Project提供(CC BY 3.0)

此包中没有支持的框架资源。

了解更多关于目标框架.NET Standard的信息。

此包没有依赖项。

NuGet包

此包没有被任何NuGet包使用。

GitHub仓库

此包没有被任何流行的GitHub仓库使用。

版本 下载 最后更新
1.0.13 93 8/6/2024
1.0.11 46 8/6/2024
1.0.8 116 8/1/2024
1.0.6 33 7/31/2024
1.0.1 55 7/26/2024