“源代码中禁止显示”概述
更新:2007 年 11 月
源代码中禁止显示是指通过使用 SuppressMessage属性禁止显示或忽略代码分析冲突的功能。SuppressMessage属性是一个条件属性,只有在编译时定义了 CODE_ANALYSIS 编译符号时,它才会包含在托管代码程序集的 IL 元数据中。在 C++ 中,可以通过两个宏 CA_SUPPRESS_MESSAGE 和 CA_GLOBAL_SUPPRESS_MESSAGE 实现相同的目的。
建议您在调试版本或签入版本中使用源代码中禁止显示,以避免错误地提供源代码中禁止显示元数据以及由于元数据膨胀而影响执行或性能。
说明: |
---|
您不需要亲自为这些属性手动编写代码。有关更多信息,请参见如何:使用菜单项禁止显示警告。 |
SuppressMessage 属性
当您右击“错误列表”中的某个代码分析警告并单击“禁止显示消息”时,SuppressMessage 属性将添加到您的代码中,或者添加到项目的全局禁止显示文件中。
SuppressMessage 属性的格式如下所示:
<Scope:SuppressMessage("Rule Category", "Rule Id", "Justification", "MessageId", Scope = "Scope", Target = "Target")>
[Scope:SuppressMessage("Rule Category", "Rule Id", "Justification", "MessageId", Scope = "Scope", Target = "Target")]
其中:
Rule Category - 定义的规则所属的类别。
Rule Id - 规则的标识符。支持对规则 ID 的使用短名称或长名称。短名称为 CAXXXX;长名称为 CAXXXX:FriendlyTypeName。
Justification - 用于记录禁止显示消息的原因的文本。
Message Id - 每个消息的问题的唯一标识符。
Scope - 在其上禁止显示警告的目标。如果未指定目标,则设置为属性的目标。支持的范围包括:
模块
命名空间
资源
类型
成员
参数
Target - 用于指定在其上禁止显示警告的目标的标识符。它必须包含完全限定的项名称。
SuppressMessage 的用法
在应用 SuppressMessage 属性的实例的级别上,禁止显示代码分析警告。执行此操作的目的是为了使禁止显示信息与发生冲突的代码紧密耦合。
禁止显示的一般形式包括规则类别和一个规则标识符,该标识符包含可选的规则名称的用户可读表示形式。例如,
[SuppressMessage("Microsoft.Design", "CA1039:ListsAreStrongTyped")]
如果出于严格的性能原因,要求最大程度地减少代码内禁止显示元数据,则可以省略规则名称本身。规则类别及其规则 ID 一起构成足够唯一的规则标识符。例如,
[SuppressMessage("Microsoft.Design", "CA1039")]
出于可维护性的原因,建议不要使用该格式。
在方法体内禁止显示多个冲突
属性只能应用于方法,而不能嵌入到方法体中。但是,您可以将标识符指定为消息 ID,以便在方法内多次出现冲突时进行区分。
Imports System
Namespace InSourceSuppression
Public Class Class1
<System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Usage", _
"CA1801:ReviewUnusedParameters", MessageId:="guid")> _
Shared Function IsValidGuid(ByVal guid As String) As Boolean
Try
Return True
Catch e As ArgumentNullException
Catch e As OverflowException
Catch e As FormatException
End Try
Return False
End Function
End Class
End Namespace
using System;
namespace InSourceSuppression
{
public class Class1
{
[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Usage",
"CA1806:DoNotIgnoreMethodResults", MessageId = "System.Guid")]
public static bool IsValidGuid(string guid)
{
try
{
new Guid(guid); //Causes CA1806: DoNotIgnoreMethodResults
return true;
}
catch (ArgumentNullException) {}
catch (OverflowException) {}
catch (FormatException) {}
return false;
}
}
}
生成的代码
托管代码编译器和某些第三方工具会生成代码,以加快代码的开发。源文件中出现的、由编译器生成的代码通常用 GenerateCodeAttribute 属性标记。
您可以选择是否禁止显示生成的代码中的代码分析警告和错误。有关如何禁止显示此类警告和错误的信息,请参见托管代码的代码分析属性。
请注意,如果 GenerateCodeAttribute 应用于整个程序集或单个参数,代码分析将忽略此属性。这些情况极少发生。
全局级禁止显示
托管代码分析工具检查在程序集、模块、类型、成员或参数级应用的 SuppressMessage 属性。它还针对资源和命名空间引发冲突。这些冲突必须在全局级应用,并且是有范围和目标的。例如,下面的消息禁止显示命名空间冲突:
[module: SuppressMessage("Microsoft.Design", "CA1020:AvoidNamespacesWithFewTypes", Scope = "namespace", Target = "MyNamespace")]
说明: |
---|
当您禁止显示具有命名空间范围的警告时,将禁止显示针对该命名空间本身的警告。不会禁止显示针对该命名空间内的类型的警告。 |
任何禁止显示都可以通过指定一个显式范围来表示。这些禁止显示必须在全局级启用。您不能通过修饰某个类型来指定成员级的禁止显示。
对于引用编译器生成的、并未映射到显式提供的用户源的代码的消息,全局级禁止显示是禁止显示它们的唯一方法。例如,下面的代码禁止显示针对编译器发出的构造函数的冲突:
[module: SuppressMessage("Microsoft.Design", "CA1055:AbstractTypesDoNotHavePublicConstructors", Scope="member", Target="Microsoft.Tools.FxCop.Type..ctor()")]
说明: |
---|
目标始终包含完全限定的项名称。 |
全局禁止显示文件
全局禁止显示文件维护全局级禁止显示或未指定目标的禁止显示。例如,程序集级冲突存储在该文件中。此外,某些 ASP.NET 禁止显示之所以存储在此文件中,是因为项目级设置对于窗体背后的代码不可用。