coverlet.msbuild 6.0.2

Coverlet 与 MSBuild 集成

在此模式下，Coverlet 除了在单元测试项目中包含 NuGet 包外，无需任何额外设置。它与 .NET Core CLI 内置的 dotnet test 基础设施集成，当启用时，将在测试运行后自动生成覆盖率结果。

如果您想在一个属性中输入多个以逗号分隔的值，请注意，您需要像这样在字符串周围添加转义引号 you will have to add escaped quotes around the string：如 /p:Exclude=\"[coverlet.*]*,[*]Coverlet.Core*\"，/p:Include=\"[coverlet.*]*,[*]Coverlet.Core*\"，或 /p:CoverletOutputFormat=\"json,opencover\"。

要使用 powershell 实现与上面相同的行为，您需要使用字面量参数标记 --%，如下所示

dotnet test /p:CollectCoverage=true --% /p:CoverletOutputFormat=\"opencover,lcov\"

代码覆盖率

启用代码覆盖率只需将 CollectCoverage 属性设置为 true

dotnet test /p:CollectCoverage=true

运行上述命令后，将在测试项目的根目录中生成包含结果的 coverage.json 文件。结果摘要也将显示在终端中。

覆盖率输出

Coverlet 可以使用多个格式生成覆盖率结果，这是通过 CoverletOutputFormat 属性指定的。例如，以下命令将覆盖率结果输出为 opencover 格式

dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

支持的格式

• json（默认）
• lcov
• opencover
• cobertura
• teamcity

您可以通过逗号（,）分隔来指定多个输出格式。

可以使用CoverletOutput属性指定覆盖率结果输出。

dotnet test /p:CollectCoverage=true /p:CoverletOutput='./result.json'

要指定所有结果将被写入的目录（尤其是使用多个格式时），在值后键入一个/。

dotnet test /p:CollectCoverage=true /p:CoverletOutput='./results/'

注意：转义字符可能会产生一些意想不到的结果。

Coverlet MSBuild任务会设置CoverletReport MSBuild项，从而您可以轻松使用生成的覆盖率报告。例如，使用ReportGenerator生成HTML覆盖率报告。

<Target Name="GenerateHtmlCoverageReport" AfterTargets="GenerateCoverageResultAfterTest">
  <ReportGenerator ReportFiles="@(CoverletReport)" TargetDirectory="../html-coverage-report" />
</Target>

TeamCity 输出

Coverlet可以使用TeamCity服务消息输出基本的代码覆盖率统计信息。

dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=teamcity

当前支持的TeamCity统计信息包括

合并结果

使用Coverlet，您可以将多个覆盖率运行的输出合并为单个结果。

dotnet test /p:CollectCoverage=true /p:MergeWith='/path/to/result.json'

给/p:MergeWith提供的值必须是Coverlet自身json结果格式的路径。将读取result.json中的结果，并将其添加到Coverlet写入的新结果中。查看示例。

阈值

Coverlet允许您指定一个覆盖率阈值，低于此阈值它将失败构建。这允许您在项目的所有更改中强制实施最小覆盖率百分比。

dotnet test /p:CollectCoverage=true /p:Threshold=80

上述命令会在任何受测模块的行、分支或方法覆盖率低于80%时自动使构建失败。您可以使用ThresholdType属性指定应用阈值值的覆盖率类型。例如，为仅应用阈值检查到行覆盖率

dotnet test /p:CollectCoverage=true /p:Threshold=80 /p:ThresholdType=line

您可以通过逗号分隔来指定多个ThresholdType的值。有效的值包括line、branch和method。同样，您可以对Threshold做相同的事。

dotnet test /p:CollectCoverage=true /p:Threshold=\"80,100,70\" /p:ThresholdType=\"line,branch,method\"

默认情况下，Coverlet会验证阈值值与每个模块的覆盖率结果。/p:ThresholdStat选项允许您更改此行为并可以具有以下任何值

• 最小值（默认）：确保每个模块的覆盖率结果不低于阈值
• 总计数：确保所有模块的总组合覆盖率结果不低于阈值
• 平均数：确保所有模块的平均覆盖率结果不低于阈值

以下命令将比较阈值值与所有模块的整体总覆盖率

dotnet test /p:CollectCoverage=true /p:Threshold=80 /p:ThresholdType=line /p:ThresholdStat=total

排除覆盖率

属性

您可以通过创建并应用名为ExcludeFromCodeCoverage的属性（位于System.Diagnostics.CodeAnalysis命名空间中），来忽略方法、整个类或程序集的代码覆盖率。

您还可以通过使用ExcludeByAttribute属性来忽略额外的属性

• 使用单个或多个属性（通过逗号分隔）
• 使用属性名、属性全名或属性类型的完全限定名（例如：Obsolete、ObsoleteAttribute、System.ObsoleteAttribute）

dotnet test /p:CollectCoverage=true /p:ExcludeByAttribute="Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute"

源文件

您还可以使用 ExcludeByFile 属性忽略特定的源文件以排除代码覆盖率

• 使用单个或多个路径（以逗号分隔）
• 使用带 globbing 的文件路径或目录路径（例如 dir1/*.cs）

dotnet test /p:CollectCoverage=true /p:ExcludeByFile=\"**/dir1/class1.cs,**/dir2/*.cs,**/dir3/**/*.cs\"

过滤器

Coverlet 提供了使用 "过滤器表达式" 对要排除的内容进行细粒度控制的权限。

语法：/p:Exclude=[Assembly-Filter]Type-Filter

通配符

• * 表示匹配零个或多个字符
• ? 表示前缀字符是可选的

示例

• /p:Exclude="[*]*" 表示排除所有程序集中（无内容受检测）的所有类型
• /p:Exclude="[coverlet.*]Coverlet.Core.Coverage" 表示排除属于 Coverlet.Core 命名空间并且任何符合 coverlet.* 的程序集（例如 coverlet.core）中的 Coverage 类
• /p:Exclude="[*]Coverlet.Core.Instrumentation.*" 表示排除任何程序集中属于 Coverlet.Core.Instrumentation 命名空间的所有类型
• /p:Exclude="[coverlet.*.tests?]*" 表示排除任何程序集中以 coverlet. 为开头并以 .test 或 .tests 结尾的所有类型（其中的 ? 使得 s 可选）
• /p:Exclude=\"[coverlet.*]*,[*]Coverlet.Core*\" 表示排除符合 coverlet.* 的程序集以及任何程序集中属于 Coverlet.Core 命名空间的所有类型

dotnet test /p:CollectCoverage=true /p:Exclude="[coverlet.*]Coverlet.Core.Coverage"

Coverlet 还可以通过使用 Include 属性，让您明确设置可以包含的内容。

示例

• /p:Include="[*]*" 表示包括所有程序集中（全部内容受检测）的所有类型
• /p:Include="[coverlet.*]Coverlet.Core.Coverage" 表示包括属于 Coverlet.Core 命名空间并且任何符合 coverlet.* 的程序集（例如 coverlet.core）中的 Coverage 类
• /p:Include="[coverlet.*.tests?]*" 表示包括任何程序集中以 coverlet. 为开头并以 .test 或 .tests 结尾的所有类型（其中的 ? 使得 s 可选）

可以同时使用 Exclude 和 Include 属性，但 Exclude 属性具有优先权。可以通过逗号（,）分隔几个过滤器表达式来指定多个过滤器表达式。

您还可以通过将 /p:IncludeTestAssembly 设置为 true 来包括测试程序集的覆盖率。

跳过自动实现的属性

不会跟踪或记录自动实现的属性。语法：/p:SkipAutoProps=true

无本地源文件的模块进行检测

语法：/p:InstrumentModulesWithoutLocalSources=true

不返回的方法

不返回的方法可以被属性标记，这会导致其后的语句被排除在覆盖率之外。

可以使用以下语法指定属性。语法：/p:DoesNotReturnAttribute="DoesNotReturnAttribute,OtherAttribute"

适用于 PowerShell/Azure DevOps 用户的说明

当使用 PowerShell 脚本或创建 Azure DevOps 构建过程中的 .yaml 文件时，应使用 %2c 作为分隔符。Msbuild 将将此符号转换为 ,。

/p:Exclude="[*]*Examples?%2c[*]*Startup"

Azure DevOps 构建不需要对双引号进行转义

dotnet test --configuration $(buildConfiguration) --no-build /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura /p:CoverletOutput=$(Build.SourcesDirectory)/TestResults/Coverage/ /p:Exclude="[MyAppName.DebugHost]*%2c[MyAppNamet.WebHost]*%2c[MyAppName.App]*"

适用于 Linux 用户的说明

Linux 中 MSBuild 存在问题，这会影响指定多个以逗号分隔的值时转义引号的能力。Linux MSBuild 在使用之前会自动将属性、任务等中的 \ 转换为 /，这意味着如果您在 MSBuild 脚本中指定了 /p:CoverletOutputFormat=\"json,opencover\"，则在执行之前它将被转换为 /p:CoverletOutputFormat=/"json,opencover/"。这会导致以下类似的错误

MSBUILD : error MSB1006: Property is not valid. [/home/vsts/work/1/s/default.proj]
  Switch: opencover/

如果您在 Linux MSBuild 或使用 Azure DevOpsLinux 代理上的 Azure DevOps MSBuild 任务中直接使用 Linux MSBuild，您将看到此错误。

解决方法是使用 .NET Core 的 dotnet msbuild 命令，而不是直接使用 MSBuild。该问题在 dotnet msbuild 中不存在，脚本将以正确转义的引号运行。

SourceLink

Coverlet 支持存储在 PDB 中的 SourceLink 自定义调试信息。当你指定 /p:UseSourceLink=true 属性时，Coverlet 将生成包含源控制中源文件 URL 的结果，而不是本地文件路径。

确定性构建

欲了解更多信息，请参阅 文档。要生成确定性报告，参数为

/p:DeterministicReport=true

从覆盖率中排除没有源代码的集合

Coverlet 使用一种启发式方法来判定一个集合是否是第三方依赖，这是基于集合的源文件与相应源文件的匹配。此参数有三个不同的值来控制系统自动排除集合。

以下是指定参数的示例

/p:ExcludeAssembliesWithoutSources="MissingAny"