BenchmarkDotNet 从源码构建完全指南Visual Studio 与命令行双方案详解【免费下载链接】BenchmarkDotNetPowerful .NET library for benchmarking项目地址: https://gitcode.com/gh_mirrors/be/BenchmarkDotNet导读本文讲解如何从源码构建 BenchmarkDotNet 这一 .NET 基准测试库。核心内容基于仓库 docs/articles/contributing/building.md 展开并结合仓库根目录的 build.cmd、build/build.sh 以及build/BenchmarkDotNet.Build下的 Cake 构建工程源码深入剖析构建系统的任务体系、依赖项与常用参数。读完本文你将掌握两种官方推荐的构建方式Visual Studio 图形界面构建与跨平台命令行构建并能熟练使用build.cmd执行编译、测试、打包、文档生成、发布等各类构建任务。构建方式总览BenchmarkDotNet 仓库提供两条官方推荐的从源码构建路径Visual Studio 方式适合 Windows 上的交互式开发与调试直接打开解决方案文件执行 Build。命令行方式基于 CakeC# Make的跨平台自动化构建在 Windows、Linux、macOS 上使用同一套脚本与任务。两种方式最终都依赖 .NET SDK 完成编译命令行方式额外封装了依赖安装、任务编排与结果输出等自动化能力。方式一使用 Visual Studio 构建环境准备在开始前需要安装以下工具Visual Studio 与 tests/BenchmarkDotNet.IntegrationTests.FSharp/BenchmarkDotNet.IntegrationTests.FSharp.fsproj。.NET 10 SDK 中确认其指定了 SDK 版本10.0.400且rollForward为disable即要求精确匹配该版本。构建步骤工具就绪后构建非常简单打开位于仓库根目录的解决方案文件BenchmarkDotNet.slnx注意是.slnx新型解决方案格式不是传统的.sln。在 Visual Studio 中执行Build操作CtrlShiftB或菜单 Build → Build Solution即可完成编译。解决方案同时被 build/BenchmarkDotNet.Build/Runners/BuildRunner.cs 中的DotNetBuild调用引用命令行方式与 IDE 方式构建的是同一套工程。方式二命令行构建Cake 自动化构建系统的定位命令行构建基于 CakeC# Make这是一个跨平台的构建自动化系统使用 C# DSL 描述构建流程可完成代码编译、文件/目录复制、单元测试运行、压缩打包以及 NuGet 包生成等任务。值得注意的是当前仓库的构建工程采用的是Cake Frosting模式——构建逻辑本身就是一段 C# 程序。入口在 build/BenchmarkDotNet.Build/Program.csProgram.Main先通过 CommandLineParser 解析用户输入的任务名与参数然后使用CakeHost配合BuildContext运行对应的FrostingTask。每个构建任务都是一个继承FrostingTaskBuildContext的类通过[TaskName]与[TaskDescription]特性声明任务名与描述通过[IsDependentOn]声明任务间的依赖关系通过实现IHelpProvider提供该任务的帮助信息。启动脚本build.cmd在仓库根目录执行 build.cmd 即可启动构建。该脚本本身是一个跨平台分发器在 Windows 上它调用 build/build.bat在 Linux/macOS 上它调用 build/build.sh。当不带任何参数执行时脚本会打印帮助信息列出所有可用构建任务。这是探索构建能力的第一步也是排查参数错误时的好帮手。跨平台前置依赖构建脚本根据操作系统有不同的前置依赖要求WindowsPowerShell 5 或更高版本MSBuild 15.1 或更高版本.NET Framework 4.6 或更高版本LinuxMono 5 或更高版本fsharp 包运行 .NET Core SDK 所需的系统包gettextlibcurl4-openssl-devlibicu-devlibssl-devlibunwind8macOSMono 5 或更高版本fsharp 包最新版本的 OpenSSL需要说明的是文档中列出的 Mono、OpenSSL 等传统依赖主要是为了支持旧版 .NET Framework / F# 场景现代 .NET 编译链路由脚本自动安装的 .NET SDK 承担。build.sh 的自动化引导逻辑在 Linux/macOS 上build/build.sh 会完成 SDK 的自动化引导设置环境变量跳过首次体验、关闭遥测、指定 HTTP 处理器若仓库根目录下不存在.dotnet目录则自动下载 dotnet-install.sh 指定的版本安装 SDK同时额外安装 .NET 8 SDK用于支持多目标框架测试将本地安装的 SDK 加入PATH与DOTNET_ROOT最后以 Release 配置运行dotnet run启动构建工程build/BenchmarkDotNet.Build/BenchmarkDotNet.Build.csproj并把命令行参数透传进去。这套引导逻辑保证了在全新机器上即使尚未安装匹配版本的 .NET SDK也能自动完成准备并进入构建流程。构建任务清单与依赖关系通过阅读 build/BenchmarkDotNet.Build/Program.cs 中的各个FrostingTask可以整理出完整的任务清单。所有任务名与描述也会在build.cmd无参数执行时打印出来。任务名描述关键依赖build构建 BenchmarkDotNet.slnx 解决方案restorerestore还原 NuGet 包pack-weaverpack-weaver打包 BenchmarkDotNet.WeaverIL 织入器—unit-tests运行单元测试快速buildanalyzer-tests运行分析器测试buildin-tests-full使用 .NET Framework 4.7.2 运行集成测试慢仅 Windowsbuildin-tests-core使用 .NET 10 运行集成测试慢buildall-tests运行全部单元、分析器与集成测试慢unit-tests、analyzer-tests、in-tests-full、in-tests-corebuild-analyzers构建 BenchmarkDotNet.Analyzers—move-analyzer-rules将已更新的分析器规则从未发布文件移至已发布文件—pack打包 NuGet 包build、build-analyzersinstall-wasm-tools安装 wasm-tools workload—docs-fetch拉取更新变更日志文件—docs-generate生成辅助文档文件—docs-build构建最终文档docs-generateversion-increment递增当前版本号—release发布新版本build、pack、docs-fetch、docs-generate、docs-build任务依赖关系在源码中以[IsDependentOn]特性声明例如restore依赖pack-weaver——因为 Weaver 包的本地包必须先打出来才能被解决方案还原引用unit-tests/analyzer-tests依赖build——先编译再测试pack同时依赖build与build-analyzers——打包主库与 Roslyn 分析器release是链路上的最终任务聚合了构建、打包与文档生成。典型用法示例# 查看帮助与全部任务列表无参数执行 build.cmd # 查看某个任务的帮助 build.cmd build --help # 还原 构建解决方案默认 Release 配置 build.cmd build # 以 Debug 配置构建 build.cmd build /p:ConfigurationDebug # 运行快速单元测试 build.cmd unit-tests # 只执行目标任务本身跳过其依赖任务 build.cmd unit-tests --exclusive # 打包 NuGet 包并指定版本前缀与后缀 build.cmd pack /p:VersionPrefix0.1.1729 /p:VersionSuffixpreview # 打包稳定版本去掉 VersionSuffix build.cmd pack --stable # 安装 wasm-tools workload用于构建 WebAssembly 相关工程 build.cmd install-wasm-tools这些示例大多直接取自Program.cs中各个任务IHelpProvider.GetHelp()声明的Examples是可以直接复制的真实用法。常用命令行参数解析构建脚本的参数解析逻辑位于 build/BenchmarkDotNet.Build/CommandLineParser.cs支持的参数定义在 build/BenchmarkDotNet.Build/Options/KnownOptions.cs。解析器对任务名做了容错处理忽略连字符且不区分大小写例如unit-tests与unittests等价-t/--target可显式指定任务以/p:开头的参数会被转换为 MSBuild 属性传入 Cake。全局参数参数别名说明--verbosity VALUE-v控制输出信息量Quiet / Minimal / Normal / Verbose / Diagnostic--exclusive-e只执行目标任务本身不执行其依赖任务--help-h打印帮助信息全局帮助或某个任务的帮助--stable-s移除 MSBuild 设置中的 VersionSuffix用于打包正式版任务专属参数参数别名适用任务说明--preview-pdocs-fetch、docs-generate、docs-build文档变更日志中包含即将发布的版本--depth VALUE-ddocs-fetch需要重新生成变更日志的最近稳定版本数量all表示全部默认 0--force-clone-fdocs-fetch强制重新克隆变更日志仓库删除已有目录--next-version VALUE-nversion-increment、release指定下一个版本号--push—release指定后真正执行 GitHub 与 nuget.org 的推送MSBuild 属性透传所有任务都支持/p:KEYVALUE语法将自定义属性透传给 MSBuild例如build.cmd build /p:ConfigurationDebug build.cmd pack /p:VersionPrefix0.1.1729 /p:VersionSuffixpreview从源码看pack任务还会自动附加--include-symbols、-p:SymbolPackageFormatsnupkg、-p:IsFullPacktrue等参数用于同时产出源码符号包snupkg并保证与版本相关属性的一致性。环境变量部分任务需要环境变量配合尤其是发布相关任务GitHubTokendocs-fetch、release任务拉取/推送 GitHub 时使用NuGetTokenrelease任务向 nuget.org 推送时使用。测试任务背后的工程映射测试任务的工程映射可以在 build/BenchmarkDotNet.Build/Runners/UnitTestRunner.cs 中看到任务测试工程unit-teststests/BenchmarkDotNet.Tests/BenchmarkDotNet.Tests.csproj 与 tests/BenchmarkDotNet.Exporters.Plotting.Tests/BenchmarkDotNet.Exporters.Plotting.Tests.csprojanalyzer-teststests/BenchmarkDotNet.Analyzers.Tests/BenchmarkDotNet.Analyzers.Tests.csprojin-tests-full/in-tests-coretests/BenchmarkDotNet.IntegrationTests/BenchmarkDotNet.IntegrationTests.csproj测试运行细节unit-tests按 Utils.GetTargetFrameworks 返回的目标框架列表逐框架执行in-tests-full使用net472目标框架且仅当构建运行在 Windows 上ShouldRun中判断IsRunningOnWindows才执行in-tests-core使用net10.0目标框架测试结果以 TRX 格式输出到仓库根目录的TestResults目录文件名形如linux(x64)-unit-net10.0.trx同时控制台会输出 detailed 级别的日志便于 CI 归档与排查。如果你只想快速验证某个改动优先运行unit-tests完整回归请运行all-tests耗时较长且集成测试需要实际启动子进程运行基准务必在性能稳定的机器上执行。打包与发布流程pack产出 NuGet 包pack任务会先清空输出目录然后对 src 下所有可打包工程逐一执行dotnet pack最终产物输出到artifacts目录。打包范围包括主库 src/BenchmarkDotNet/BenchmarkDotNet.csproj注解库 src/BenchmarkDotNet.Annotations/BenchmarkDotNet.Annotations.csprojRoslyn 分析器 src/BenchmarkDotNet.Analyzers/BenchmarkDotNet.Analyzers.csproj代码修复器 src/BenchmarkDotNet.CodeFixers/BenchmarkDotNet.CodeFixers.csprojWindows 专属诊断器 src/BenchmarkDotNet.Diagnostics.Windows/BenchmarkDotNet.Diagnostics.Windows.csprojdotMemory / dotTrace 集成、TestAdapter、Weaver 等其余可打包工程项目模板 templates/BenchmarkDotNet.Templates.csproj主库打包时会附加-p:IsFullPacktrue并启用 snupkg 符号包输出。release一键发布release任务串联了build、pack、docs-fetch、docs-generate、docs-build等前置任务最终由 ReleaseRunner 执行发布。典型用法build.cmd release --stable --next-version 0.1.1729 --push其中--push表示真正执行 GitHub 与 nuget.org 推送省略时仅演练流程同时需要配置GitHubToken与NuGetToken环境变量。常见问题与排障建议1. 无参数运行 build.cmd 报错或没反应无参数运行会直接打印帮助信息而不是执行构建这是预期行为。真正构建需要显式指定任务名例如build.cmd build。2. 提示 SDK 版本不匹配build/sdk/global.json 固定了 SDK 版本为10.0.400且禁止 rollForward。请安装对应版本的 .NET SDK或使用build.sh让脚本自动下载安装到仓库内的.dotnet目录。3. 任务名拼写不敏感但连字符很关键解析器会忽略连字符与大小写差异但为了可读性和帮助文档的一致性建议按官方任务名书写。4. 只想单独跑一个任务使用--exclusive-e跳过依赖任务。例如只想编译而不想重新还原时可尝试build.cmd build --exclusive但请确保此前已执行过restore。5. Linux 构建报缺少系统库对照上文 Linux 前置依赖清单安装gettext、libcurl4-openssl-dev、libicu-dev、libssl-dev、libunwind8等包具体包名随发行版略有差异。6. 查看某个任务支持哪些参数执行build.cmd 任务名 --help例如build.cmd pack --help会打印该任务的描述、示例、专属参数与环境变量要求。延伸阅读docs/articles/contributing/building.md本文的原始依据文档docs/articles/contributing/running-tests.md测试运行详解docs/articles/contributing/debugging.md调试指南docs/articles/contributing/documentation.md文档贡献说明tests/runCoreTests.sh 与 tests/runClassicTests.cmd测试脚本的另一种快速入口。【免费下载链接】BenchmarkDotNetPowerful .NET library for benchmarking项目地址: https://gitcode.com/gh_mirrors/be/BenchmarkDotNet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考