c# - 重用其他代码时如何修复/抑制 SA1636 和 SA1641？

Question

我已将 StyleCop.Analyzers NuGet 包添加到我的项目中(最新的稳定版本，1.1.118)。这包含一些确保文件头存在且正确的分析规则。我的项目还有以下 stylecop.json 文件，其 Build Action 属性设置为“C# analyzer additional file”。

{
  "$schema": "https://raw.githubusercontent.com/DotNetAnalyzers/StyleCopAnalyzers/master/StyleCop.Analyzers/StyleCop.Analyzers/Settings/stylecop.schema.json",
  "settings": {
    "documentationRules": {
      "companyName": "Me"
    }
  }
}

如果我将以下类添加到项目中，它会引发警告“SA1636:文件头版权文本应与设置中的版权文本相匹配”。

// <copyright file="MyClass.cs" company="Me">
// Copyright (c) Me. All rights reserved. Some extra text to intentionally cause SA1636.
// </copyright>

namespace StackOverflowSA1636
{
    /// <summary>
    /// A class that I wrote.
    /// </summary>
    public class MyClass
    {
    }
}

如果我从文件头中删除 Some extra text to intentionally cause SA1636. 那么警告就会消失。到目前为止一切都很好。

但是，如果我想使用其他人编写的类，无论是原样还是经过我所做的任何更改，该怎么办？我想正确地将他们的代码归功于他们。以下类引发警告 SA1636 和“SA1641:文件头公司名称应与设置中的公司名称相匹配”。

// <copyright file="SomeoneElsesClass.cs" company="Me, Someone Else">
// Copyright (c) Me, Someone Else. All rights reserved.
// </copyright>

namespace StackOverflowSA1636
{
    /// <summary>
    /// A class written by someone else which I've adapted for my needs.
    /// </summary>
    public class SomeoneElsesClass
    {
    }
}

Visual Studio 2019 很有帮助地建议我可以在具有如下属性的 GlobalSuppressions.cs 文件中抑制这些警告:

using System.Diagnostics.CodeAnalysis;

[assembly: SuppressMessage(
    "StyleCop.CSharp.DocumentationRules",
    "SA1636:File header copyright text should match",
    Justification = "Someone else wrote the original version of this class",
    Scope = "namespace",
    Target = "~N:StackOverflowSA1636")]

[assembly: SuppressMessage(
    "StyleCop.CSharp.DocumentationRules",
    "SA1641:File header company name text should match",
    Justification = "Someone else wrote the original version of this class",
    Scope = "namespace",
    Target = "~N:StackOverflowSA1636")]

这确实抑制了警告，但对于整个命名空间，这不是我想要的。我只想为一个类压制他们。我尝试将它们更改为:

[assembly: SuppressMessage(
    "StyleCop.CSharp.DocumentationRules",
    "SA1636:File header copyright text should match",
    Justification = "Someone else wrote the original version of this class",
    Scope = "type",
    Target = "~T:StackOverflowSA1636.SomeoneElsesClass")]

[assembly: SuppressMessage(
    "StyleCop.CSharp.DocumentationRules",
    "SA1641:File header company name text should match",
    Justification = "Someone else wrote the original version of this class",
    Scope = "type",
    Target = "~T:StackOverflowSA1636.SomeoneElsesClass")]

当我进行此编辑时，Visual Studio 将属性变灰，因为 Scope 和 Target 没有解析任何内容，但是当我完成编辑时，属性不再变灰，这让我觉得我已经正确指定了 Scope 和 Target。但是，这不会导致警告被抑制。

Visual Studio 还建议我可以像这样抑制 SA1636:

#pragma warning disable SA1636 // File header copyright text should match
// <copyright file="SomeoneElsesClass.cs" company="Me, Someone Else">
// Copyright (c) Me, Someone Else. All rights reserved.
// </copyright>

namespace StackOverflowSA1636
#pragma warning restore SA1636 // File header copyright text should match
{
    /// <summary>
    /// A class written by someone else which I've adapted for my needs.
    /// </summary>
    public class SomeoneElsesClass
    {
    }
}

这确实抑制了警告，但引发了三个新警告:

“SA1633:文件头丢失或不在文件顶部”(因为文件的第一行是#pragma而不是文件头)

“SA1512: Single-line comments should not be followed by blank line”(大概是因为文件头不再被识别为文件头的一部分，因为它不在文件的顶部，所以被处理作为常规评论)

“SA1515:单行注释前应有空行”(同SA1512原因)

有一个不涉及抑制任何内容的解决方案，只需按照 StyleCop 的要求保留文件头，然后在其后加上注明原作者的注释或包含原始代码中的任何版权/许可声明。这感觉具有误导性，因为文件头有效地声称我是唯一作者，而我不是，但是有没有更好的方法既能满足 StyleCop 的要求又能正确地注明原作者的姓名？

我可以对 stylecop.json 文件做些什么来改变文件头的验证方式吗？

我是否偶然发现了 StyleCop.Analyzers 中的错误？

---

1 月 9 日更新

经过进一步思考，我怀疑我无法使用 SuppressMessage 抑制警告的原因是因为警告是针对文件而不是类和 Target 我指定指向类而不是文件。

对 Target 参数的不同值进行一些试验似乎表明，如果 Target 指向不存在的内容，Visual Studio 只会使属性变灰，但是当目标没有这样的警告要压制时就不会了。我怀疑可能无法以文件而不是类为目标，但是我很不高兴找到有关如何构建 Target 的任何指导。

这个 GitHub 问题似乎涵盖了我的用例，所以我没有创建新的:https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2733

Answer 1

您基于 type 的全局抑制看起来是正确的，但我得到的结果是相同的，即这些没有被拾取，尽管抑制规则本身被突出显示/识别。
这看起来确实是一个错误的候选对象。

---

作为获得预期结果的替代/解决方法，您可以在 .editorconfig 文件中配置该忽略规则。

要仅针对该 SomeoneElsesClass 类，请在部分中指定目标文件名 - 此处:[{SomeoneElsesClass.cs}]。
如果需要，您还可以使用更详细的路径，例如[{Folder/SomeoneElsesClass.cs}]

[{SomeoneElsesClass.cs}]
dotnet_diagnostic.SA1636.severity = none
dotnet_diagnostic.SA1641.severity = none