.NET runtime Host 测试构建与运行完全指南从产品构建到测试调试验证【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime本篇指南围绕 .NET runtime 仓库中 docs/workflow/testing/host/testing.md 的核心内容展开系统讲解如何构建并运行托管层host测试。文章以该文档为骨架结合仓库中src/installer/tests下的测试源码、MSBuild 目标与子集配置进行深度佐证帮助你掌握从零构建产品、搭建测试上下文、筛选运行单个测试、在 Visual Studio 中调试以及定位 host 测试失败场景的完整工作流。背景什么是 host 测试Host托管层是 .NET 运行时分发中负责拉起运行时与应用的组件包括dotnet可执行文件muxer、apphost应用主机、hostfxr解析框架与依赖与 hostpolicy策略决策等。为保证这些组件的正确性仓库在 src/installer/tests 目录下维护了一套独立的测试套件统一使用 xunit 作为测试框架见 HostActivation.Tests.csproj 中的TestRunnerName配置。测试套件涵盖的面非常广从 HostActivation.Tests 目录的测试文件即可看出其覆盖范围FrameworkDependentAppLaunch.cs、SelfContainedAppLaunch.cs框架依赖与自包含应用的启动验证DependencyResolution/、FrameworkResolution/依赖解析与框架解析行为Breadcrumbs.csservicing breadcrumb 行为SDKLookup.csSDK 查找逻辑StartupHooks.cs启动钩子NativeHosting/、NativeHostApis.csnative 托管 APIhostfxr/hostpolicy调用Tracing.cs、RuntimeProperties.cs、SymbolicLinks.cs等跟踪、运行时属性、符号链接等专项行为。此外还有AppHost.Bundle.Tests、Microsoft.NET.HostModel.Tests等配套测试项目。这些测试的特点是它们不只是单元测试而是会真实启动一个独立进程如dotnet、apphost 或 native host并校验其标准输出与错误输出因此对构建产物和目录布局有严格的前置要求。构建 host 测试第一步构建产品CoreCLR 与库Host 测试需要基于真实的运行时与库产物运行因此在构建测试之前必须先构建产品。文档给出的命令是build.cmd/sh -subset clrlibs -c Release其中-subset clrlibs表示同时构建 CoreCLR 与 Libraries 两个子集-c Release指定 Release 配置。完整的构建说明可参考 CoreCLR 构建指南 与 Libraries 构建指南。第二步构建 host产品构建完成后构建 host 组件本身build.cmd/sh -subset host -runtimeConfiguration Release -librariesConfiguration Release需要注意两点-runtimeConfiguration与-librariesConfiguration用于声明 CoreCLR/Libraries 实际使用的构建配置。如果你在上一步使用了 Release 之外的配置例如 Debug则必须在这里显式指定对应的配置否则 host 会按照默认配置去寻找产物导致找不到文件或版本不匹配。host子集默认会连带构建 host 测试详见下文子集与依赖一节的源码说明因此执行完这一步后测试二进制通常已经就绪。构建全部测试如果只想构建 host 测试而不重新构建 host 产品可以单独使用host.tests子集build.cmd/sh -subset host.tests -runtimeConfiguration Release -librariesConfiguration Release构建特定测试项目也可以绕过仓库的构建脚本直接用dotnet build构建某个测试项目例如文档中的示例dotnet build src\installer\tests\HostActivation.Tests在 Linux/macOS 上路径分隔符请相应替换为/。这种方式便于在迭代单个测试库时获得更快的反馈。从源码看子集与依赖关系host.tests、host.pretest等子集的定义位于 eng/Subsets.props关键片段如下host.pretest子集eng/Subsets.props#L691-L693将 src/installer/tests/hostpretest.proj 纳入构建它负责构建测试资产项目并创建共享框架布局host.tests子集eng/Subsets.props#L696-L702会以BuildNativeHostTeststrue;BuildNativeHostProductfalse的方式构建 src/native/corehost/corehost.proj即只构建 native 测试不构建 native 产品将AppHost.Bundle.Tests、HostActivation.Tests、Microsoft.NET.HostModel.Tests三个测试项目纳入TestProjectToBuild并以并行方式执行测试。另外eng/Subsets.props#L152 显示DefaultHostSubsets默认包含host.pretesthost.tests这正是构建host子集即可连带构建测试的根源。理解测试上下文Test ContextHost 测试不是自包含的运行前必须满足三项前置依赖预构建的测试项目输出位于 src/installer/tests/Assets/Projects这些测试应用如HelloWorld、StartupHook、Component、HostApiInvokerApp等会被复制并在测试中被实际运行。由host.pretest子集负责构建。与 .NET 安装布局一致的产品二进制目录测试会按照真实 .NET 安装的目录结构去查找dotnet、共享框架等文件因此需要预先创建该布局同样由host.pretest子集完成。TestContextVariables.txt 属性文件以属性值的键值对形式记录测试运行所需的路径与版本信息由host.tests子集在构建测试时生成。当通过build -subset host.tests -test运行全部测试时构建系统会自动保证上述依赖在测试启动前就绪。单独准备测试上下文如果只想更新测试依赖而不跑全量测试可以按两步操作构建host.pretest子集默认已包含在host子集中对应上述 (1)(2) 两项构建目标测试项目对应上述 (3) 项。构建测试本身会自动执行SetupTestContextVariables目标也可以单独手动执行dotnet build src\installer\tests\HostActivation.Tests -t:SetupTestContextVariables -p:RuntimeConfigurationRelease -p:LibrariesConfigurationReleaseTestContextVariables.txt 的生成细节从源码看SetupTestContextVariables目标定义在 src/installer/tests/Directory.Build.targets#L11-L69它会通过WriteLinesToFile在测试输出目录生成TestContextVariables.txt包含以下变量变量含义TEST_ARTIFACTS测试产物根目录使用系统路径分隔符避免字符串比较失败BUILD_RID目标 RID$(TargetRid)BUILD_ARCHITECTURE目标架构$(TargetArchitecture)BUILD_CONFIGURATION构建配置Debug/Release 等MNA_VERSIONMicrosoft.NETCore.App 运行时包版本直接从Microsoft.NETCore.App.Ref.sfxproj的ReturnProductVersion获取避免测试项目因IsShippingfalse导致版本不稳定MNA_TFM目标框架$(NetCoreAppCurrent)TEST_ASSETS_OUTPUT测试资产输出根目录该目标同时会在输出目录写入一个空的global.json防止测试运行过程中被父目录的global.json干扰。读取方是 src/installer/tests/TestUtils/HostTestContext.cs 中的静态构造函数它按行解析TestContextVariables.txt以分隔键值并忽略大小写GetTestContextVariable方法HostTestContext.cs#L56-L70还支持环境变量覆盖——即同名的环境变量优先于文件中的值这在临时调整测试参数时非常有用。另外在 macOS 上它会解析/tmp/的符号链接避免因路径解析不一致导致测试失败。hostpretest.proj 的职责src/installer/tests/hostpretest.proj 承担了两项核心工作通过ProjectReference递归引用 Assets/Projects 下所有*.csproj一次性构建全部测试应用SetUpSharedFrameworkPublish目标会根据RuntimeFlavor选择构建Microsoft.NETCore.App.Runtime.CoreCLR.sfxproj或Microsoft.NETCore.App.Runtime.Mono.sfxproj并将其发布到$(TestArtifactsOutputRoot)sharedFrameworkPublish/形成测试所需的共享框架布局。运行 host 测试运行全部测试build.cmd/sh -subset host.tests -test默认情况下该命令会先构建测试再运行如果产物已是最新可以附加-testnobuild跳过构建阶段直接运行。运行特定测试如果此前从未运行过全部测试请先确保目标测试库的 测试上下文 已就绪即完成host.pretest构建与测试项目构建。针对单个测试项目可以使用dotnet test直接指向构建好的测试二进制例如dotnet test artifacts/bin/HostActivation.Tests/Debug/net11.0/HostActivation.Tests.dll --filter category!failingartifacts/bin/HostActivation.Tests/Debug/net11.0/是测试程序集的默认输出路径配置与目标框架名请以实际构建为准。category!failing用于排除已知失败用例这一惯例遵循仓库的 traits 过滤指南。利用dotnet test的 filter 选项可以进一步缩小范围例如只运行DependencyResolution相关的测试并排除已知失败dotnet test artifacts/bin/HostActivation.Tests/Debug/net11.0/HostActivation.Tests.dll --filter DependencyResolutioncategory!failing关于 filter 的完整语法逻辑运算符、|、!按名称/特性过滤等可查阅dotnet test的 filter option 文档。关于 traits 过滤机制filtering-tests.md 详细解释了仓库使用的 xunit traits 体系host 测试同样遵循这一机制[ActiveIssue(...)]标记存在活跃 issue 的失败用例归类为failing默认被category!failing排除[PlatformSpecific(TestPlatforms.X)]限定仅在特定平台运行的用例[SkipOnPlatform(...)]、[SkipOnTargetFramework(...)]、[SkipOnCoreClr(...)]、[SkipOnMono(...)]按平台、目标框架、运行时做永久性跳过[OuterLoop]标记耗时长或需特殊环境的用例默认不运行可通过-testscope outerloop启用。在 src/installer/tests/HostActivation.Tests/SymbolicLinks.cs#L264-L265 可以看到真实的[SkipOnPlatform(TestPlatforms.OSX, ...)]用法示例用于跳过在 macOS 上因Command.Create报 No such file or directory 而失败的符号链接用例。Visual Studio 中运行与调试仓库提供了 src/installer/Microsoft.DotNet.CoreSetup.slnx 解决方案可直接在 Visual Studio 中运行与调试 host 测试。使用前需满足两个前提产品已按上文 构建 host 测试 完成构建且测试上下文已就绪。如果 runtime/libraries 与 host 的构建配置不一致需要用-vs参数显式指定后启动 Visual Studiobuild.cmd -vs Microsoft.DotNet.CoreSetup -rc Release -lc Release-rc/-lc分别对应 runtime 与 libraries 的配置确保 IDE 中测试运行环境与实际产物配置一致。此外SetupTestContextVariables 目标 的注释提到把变量写入文本文件的目的之一就是让 Visual Studio 测试资源管理器VS Test Explorer也能像 xunit runner 一样读到这些上下文变量。调查测试失败结果报告位置通过build -subset host.tests -test运行全量测试时测试报告生成在repo_root\artifacts\TestResults目录下单独运行单个测试时结果默认输出到控制台可通过dotnet test的选项如--logger配置输出方式。host 测试的失败模式Host 测试与普通单元测试的显著区别在于进程间验证测试会启动一个独立进程dotnet、apphost 或 native host然后校验该进程的标准输出stdout与标准错误stderr是否符合预期。为此测试通常需要复制或创建测试应用与.NET 安装目录形态的临时产物——相关工具类集中在 src/installer/tests/TestUtils例如Command.cs提供Command.Create(executable, args)封装进程启动Command.cs#L43-L53是测试拉起dotnet/apphost 的基础设施CommandResult.cs封装启动结果退出码、stdout、stderrDotNetBuilder.cs、NetCoreAppBuilder.cs在测试产物目录中构造 dotnet 安装布局与应用布局TestArtifact.cs、TestFileBackup.cs管理测试临时产物的创建与清理。失败时测试会报告所启动进程的文件路径、参数与环境变量。结合下面介绍的保留产物机制你可以用这些信息直接复现并调试失败的场景。保留测试产物PRESERVE_TEST_RUNS测试在结束后会默认删除自己生成的临时产物这给事后检查带来了困难。设置环境变量PRESERVE_TEST_RUNS1即可跳过清理PRESERVE_TEST_RUNS1 dotnet test artifacts/bin/HostActivation.Tests/Debug/net11.0/HostActivation.Tests.dll --filter category!failingLinux/macOS 使用上述export或行内变量赋值方式Windows 使用set PRESERVE_TEST_RUNS1。开启后失败的测试会在产物目录中留下完整的应用 .NET 安装布局你可以直接进入该目录手动运行对应的dotnet/apphost 命令观察真实的输出与报错从而定位是 host 逻辑问题还是测试预期问题。完整工作流速查将上述步骤串起来一次典型的 host 测试迭代流程如下# 1. 构建产品CoreCLR Libraries ./build.sh -subset clrlibs -c Release # 2. 构建 host含测试上下文准备 ./build.sh -subset host -runtimeConfiguration Release -librariesConfiguration Release # 3. 运行全部 host 测试 ./build.sh -subset host.tests -test # 4. 或只运行某个测试库中的特定用例 dotnet test artifacts/bin/HostActivation.Tests/Debug/net11.0/HostActivation.Tests.dll \ --filter DependencyResolutioncategory!failing # 5. 失败后保留产物进入 artifacts 目录复现调试 PRESERVE_TEST_RUNS1 dotnet test artifacts/bin/HostActivation.Tests/Debug/net11.0/HostActivation.Tests.dll小结Host 测试是验证 .NET 托管层行为正确性的关键防线。本文以 docs/workflow/testing/host/testing.md 为主线完整梳理了从产品构建、host/host.pretest/host.tests子集划分、TestContextVariables.txt生成机制到全量与定向运行、Visual Studio 调试以及失败调查的完整链路并辅以 eng/Subsets.props、hostpretest.proj、Directory.Build.targets 与 TestUtils 中的源码证据。掌握这些步骤与背后的机制你便能在本地高效地构建、运行与调试任意一个 host 测试场景。【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考