使用已安装 SDK 运行自建 .NET Runtime 构建从 CoreCLR 产物替换到应用验证的完整指南【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime本文是 dotnet/runtime 仓库当前工作区为 GitHub_Trending/runtime6/runtime中 docs/workflow/testing/using-your-build-with-installed-sdk.md 的深度展开。当你修改了 CoreCLRC 运行时或System.Private.CoreLib.dll托管核心库并完成构建后最快捷的验证方式之一就是借助本机已安装的 .NET SDK将自建产物替换进一个自包含self-contained发布的应用里然后直接运行。读完本文你将掌握如何准备开发版 SDK、如何创建并发布自包含应用、如何用artifacts/bin/coreclr/OS.arch.configuration中的构建产物替换发布目录中的运行时二进制以及如何确认应用确实加载了你自建的运行时并排解常见错误。引言运行自建 Runtime 的三种方式要运行一个使用自建 .NET 运行时的应用你需要一个能加载运行时的host程序以及应用依赖的全部 .NET 类库。仓库文档给出了三种主流方案使用本机已安装的 .NET SDK在自包含应用中替换必要二进制本文主题。使用自构建的 Dev Shipping Packages 运行应用详见 docs/workflow/testing/using-dev-shipping-packages.md。使用构建产物中生成的 CoreRun host详见 docs/workflow/testing/using-corerun-and-coreroot.md。本文聚焦第一种。它的前提是你已经至少构建了仓库的clr子集并且二进制位于artifacts/bin/coreclr/OS.arch.configuration目录下。如果尚未构建请先参考 docs/workflow/building/coreclr/README.md 中关于获取这些产物的详细说明。重要前提注意兼容性限制此方法要求应用是自包含self-contained的因为只有自包含发布才会把完整运行时复制进应用目录而当前官方发布的dotnet便携版portable build不支持自包含场景。因此如果已发布的dotnet版本与 live 仓库不兼容虽然这种情况不太可能你就只能退而选择安装 nightly 构建不太推荐或者改用上面提到的另外两种方案来测试你的构建。获取最新开发版 .NET SDK由于仓库主干的 API 和能力总是超前于正式发布版官方推荐使用nightly 开发版 SDK即dogfood SDK。获取步骤从 dotnet/sdk 仓库的 nightly builds 下载表中找到与你机器平台匹配的安装包installer或便携压缩包zip/tar.gz。安装方式如果下载的是 installer按常规安装流程完成安装即可。便携方式把下载的 zip/tar.gz 解压到某个目录然后二选一将解压目录加入PATH环境变量每次直接使用完整路径调用dotnet例如/path/to/nightly/build/dotnet。设置完成后用dotnet --version验证版本。在本文档撰写时版本号必须 ≥9.0.100-*。注意dotnet --version只能确认 SDK 版本若要查看完整运行时信息可用dotnet --info查看安装的运行时版本与提交哈希commit。仓库内还提供了一份更简短的上手说明参见 docs/project/dogfooding.md。关于版本标识的补充仓库的版本品牌branding定义在 eng/Versions.props 中例如ProductVersion12.0.0/ProductVersion、PreReleaseVersionLabelalpha/PreReleaseVersionLabel等而 CoreCLR 原生代码中的版本宏如CLR_PRODUCT_VERSION、VER_FILEVERSION_STR定义在 src/coreclr/inc/clrversion.h。你构建出来的运行时版本号会形如Major.Minor.0.0-dev-dev表示开发版这正好是下文验证是否用上了自建运行时的关键标记。创建示例自包含应用先创建一个用于测试的 Hello World 应用mkdir HelloWorld cd HelloWorld dotnet new console默认情况下dotnet new console创建的是框架依赖framework-dependent应用运行在机器上已安装的共享框架上无法加载你的本地构建。要让应用使用本地修改必须让它成为自包含应用方法是为项目指定一个RuntimeIdentifierRID。你可以稍后在命令行里直接指定也可以把它写进应用的.csprojPropertyGroup ... RuntimeIdentifierwin-x64/RuntimeIdentifier /PropertyGroup本文示例使用 Windows x64请务必把它设置为你实际构建产物对应的平台与架构。常见操作系统代号操作系统代号WindowswinmacOSosxLinuxlinux例如如果你测试的是 macOS ARM64 构建那么RuntimeIdentifier应为osx-arm64。RID 的完整形态就是os代号-架构它必须与artifacts/bin/coreclr/OS.arch.configuration中产物的平台架构一一对应。发布你的应用接下来构建并发布。dotnet publish会自动触发 restore 和 builddotnet publish --self-contained注意若 publish 在还原运行时包时失败你需要配置自定义 NuGet 源。这是使用 dogfood .NET SDK 的副作用——它的依赖尚未发布到常规 NuGet 源上。解决办法执行dotnet new nugetconfig生成一个NuGet.Config用以下模板替换文件内容?xml version1.0 encodingutf-8? configuration packageSources !--To inherit the global NuGet package sources remove the clear/ line below -- clear / add keynuget valuehttps://api.nuget.org/v3/index.json / add keydotnet9 valuehttps://dnceng.pkgs.visualstudio.com/public/_packaging/dotnet9/nuget/v3/index.json / /packageSources /configuration其中dotnet9源对应文档撰写时期的开发版包源feed 名称与当前主干版本相关例如仓库当前版本对应的开发源为dotnet11/dotnet12一类请以 docs/project/dogfooding.md 及当时 SDK 文档为准。发布成功后运行应用所需的全部二进制会出现在bin\Debug\net11.0\win-x64\publish目录下net11.0为文档撰写时的目标框架具体以你的TargetFramework为准。但到这里还没完——你必须用本地构建的产物替换发布目录中的运行时文件这正是本方法的核心所在。用你的构建替换 CoreCLR 与 System.Private.CoreLib.dll发布步骤生成的应用目录包含了运行所需的全部文件其中就有 CoreCLR 运行时和必要的类库。在所有二进制中有三个文件承载了你对运行时所做的绝大部分修改二进制承载的修改coreclr.dllWindows/libcoreclr.dylibmacOS/libcoreclr.soLinux绝大多数 C 代码修改JIT 编译器与工具除外System.Private.CoreLib.dll你修改的托管 C# 代码clrjit.dllJIT 编译器本体必须一并复制到发布目录复制这些二进制时注意来源artifacts/bin/coreclr/OS.arch.configuration/你的 CoreCLR 构建产物目录目标应用的发布目录默认路径为your-app-folder/bin/configuration/net11.0/os-code-arch/publish。沿用前文的例子即从artifacts/bin/coreclr/windows.x64.Debug/到HelloWorld/bin/Debug/net11.0/win-x64/publish/从源码结构看这些产物名称与平台绑定的行为定义在仓库的构建系统中CoreCLR 各平台二进制命名coreclr.dll/libcoreclr.dylib/libcoreclr.so以及corerunhost 均来自clr子集构建构建文档 docs/workflow/building/coreclr/README.md 中列出了产物目录下最重要的几个二进制corerun、coreclr、System.Private.CoreLib.dll。另外要注意构建配置Debug/Release/Checked会影响产物行为——Debug无优化但断言全开Release优化最彻底Checked保留断言同时开启原生优化CI 测试的常用模式。在性能基准测试时务必使用Release构建的产物进行替换。确认应用使用了你的新运行时可选至此你已经成功使用自建运行时运行了应用。如果你希望在深入更复杂的实验与测试前进一步确认这一点可以在应用中运行以下代码using System.Diagnostics; var coreAssemblyInfo FileVersionInfo.GetVersionInfo(typeof(object).Assembly.Location); Console.WriteLine($Core Runtime Info: {coreAssemblyInfo.ProductVersion}); Console.WriteLine($System.Private.CoreLib.dll is located at: {typeof(object).Assembly.Location});它会告诉你程序集版本以及构建该程序集的用户、机器和代码提交哈希Core Runtime Info: 11.0.0-dev System.Private.CoreLib.dll is located at: /path/to/your/app/bin/Debug/net11.0/win-x64/publish/System.Private.CoreLib.dll你需要确认两点核心运行时版本标注为-dev——这说明它确实来自你在 runtime 仓库自建的构建正式发布版不会带-dev后缀输出的System.Private.CoreLib.dll路径确实位于你的publish目录而不是机器上安装的共享框架目录。该版本字符串的生成链路可以追溯到源码typeof(object).Assembly即System.Private.CoreLib.dll其文件版本信息在构建时由 eng/Versions.props 中的品牌版本与 src/coreclr/inc/clrversion.h 中的版本宏CLR_PRODUCT_VERSION、VER_FILEVERSION_STR等共同决定开发构建会带上-dev标记。故障排查以下是几个常见的错误及其解决办法。问题一应用没有使用你复制的二进制请确保你直接运行发布的可执行文件.\bin\Debug\net11.0\win-x64\publish\HelloWorld.exe如果你改用dotnet run它会在执行应用前用共享框架覆盖你自定义的二进制导致你的修改不生效。问题二一致性检查断言失败Consistency check assertion failure该失败通常发生在你只复制了coreclr却没有同时复制System.Private.CoreLib.dll时。此时coreclr与你复制过去的System.Private.CoreLib.dll版本不匹配运行时启动时的一致性检查会直接断言Assert failure(PID 13452 [0x0000348c], Thread: 10784 [0x2a20]): Consistency check failed: AV in clr at this callstack:解决办法确保coreclr或各平台的libcoreclr.*与System.Private.CoreLib.dll始终成对替换因为它们必须来自同一次构建。问题三JIT 加载错误如果你忘了同时复制clrjit.dll应用启动时会报Fatal error. Failed to load JIT compiler.解决办法把 JIT 编译器二进制clrjit.dll也一并复制到发布目录。这三个文件coreclr、System.Private.CoreLib.dll、clrjit.dll必须配套替换缺一不可。延伸与本仓库其他测试方式的衔接本文介绍的方法适合修改少量运行时代码后快速验证。如果你的修改迭代非常频繁或者希望同时调试类库可以考虑切换到本仓库的另外两条路径CoreRun / Core_Root 方式docs/workflow/testing/using-corerun-and-coreroot.mdcorerun是随clr子集生成的原生 host它通过--clr-path、CORE_ROOT环境变量或同目录探测三条启发式规则定位运行时是频繁改动时最快的验证方式Dev Shipping Packages 方式docs/workflow/testing/using-dev-shipping-packages.md构建clrlibshostpacks子集生成 NuGet 包最接近真实用户的使用形态但需要处理本地 NuGet 缓存的刷新问题。此外仓库的 CoreCLR 测试体系docs/workflow/testing/coreclr/testing.md也围绕 Core_Root 构建测试布局artifacts/tests/coreclr/OS.arch.configuration/Tests/Core_Root与本文的自包含应用替换法在原理上相通——都是让自建运行时与配套类库一起被加载。理解本文的替换机制也有助于你调试测试失败时排查用的是哪个运行时这类问题。【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考