.NET Runtime 仓库编辑与调试完全指南从解决方案文件到 CoreCLR 源码级断点【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime本指南围绕 docs/workflow/editing-and-debugging.md 展开系统讲解在 dotnet/runtime本项目 runtime仓库中进行代码编辑、解决方案生成与调试的完整工作流。你将掌握如何借助 Visual Studio / Visual Studio Code 打开仓库内各类*.slnx解决方案如何通过build.cmd -vs一键生成并打开 CoreCLR 与 corehost 原生工程以及如何从EEStartup()到clrstack完成一次真正的运行时源码级调试。一、编辑环境选型Windows 上的 Visual Studio 与跨平台 VS Code当前仓库.NET Runtime跨平台运行时体积庞大涉及托管C#与原生C两类代码。官方文档给出的编辑建议非常务实Windows 平台使用Visual Studio是编辑本仓库代码的推荐方案它对 C# 与 C 工程、CMake 工作区、调试器都有最完整的集成支持当然你也可以选择自己熟悉的任意编辑器。跨平台场景Visual Studio Code 是轻量、跨平台的选择除了在 macOS 与 Linux 上可用外也针对代码编辑与调试工作流做了优化。仓库文档大量使用 Markdown*.md文件例如本指南所在的 docs 目录。VS Code 对 Markdown 有内置的语法高亮与预览支持因此如果要修改文档VS Code 是很好的选择——它天然适合处理 Git 仓库中这类文档型文件。二、仓库内的解决方案文件*.slnx按组件拆分编辑单元仓库内存在大量 Visual Studio 解决方案文件*.slnx即新的 XML 格式解决方案它们把仓库拆分成一个个可独立打开、编译的编辑单元。文档重点推荐以下三类1. 托管代码解决方案System.Private.CoreLib.slnx路径src/coreclr/System.Private.CoreLib/System.Private.CoreLib.slnx这个解决方案覆盖运行时本身定义的所有托管C#代码即各类类库支持代码。从该文件内容可以看到它组织为若干 Folder/gen/源码生成器工程如 System.Private.CoreLib.Generators.csproj、EventSourceGenerator、LibraryImportGenerator 等/ref/引用程序集工程 System.Private.CoreLib.csproj/src/核心源码工程System.Private.CoreLib.csproj及其共享工程System.Private.CoreLib.Shared.shproj/tools/ILLink链接器相关的 Roslyn 分析器与 CodeFix 工程。同时它声明了Checked / Debug / Release三种 BuildType以及amd64 / x64 / x86 / arm / arm64 / wasm / Any CPU等平台映射例如System.Private.CoreLib.csproj会把解决方案的amd64平台映射为工程级的x64。这意味着在解决方案内即可按平台与配置分别编译 CoreLib。2. 原生代码解决方案CoreCLR.slnx路径为生成产物artifacts/obj/coreclr/windows.Arch.BuildType/ide/CoreCLR.slnx包含仓库中绝大多数原生C工程其中coreclr运行时主 DLLGC、类加载器class loader、互操作interop都位于其中corjit即时编译器JIT负责把 .NET 中间语言IL编译为本地机器码corerun简单的宿主程序用于运行 .NET 应用程序。注意该解决方案位于artifacts目录下因为它是构建过程的产物。只有在至少完成一次带-msbuild标志的构建或直接运行过./build.cmd -vs CoreCLR.slnx带指定架构与配置之后才能打开它。3. 宿主组件解决方案corehost.slnx路径为生成产物artifacts/obj/win-Arch.BuildType/corehost/ide/corehost.slnx包含宿主组件host components相关的原生C工程。宿主组件是 .NET 启动链条的关键部分详见 host-components 设计文档主要包括dotnetmuxer、apphost、comhost、ijwhost、nethost等入口宿主hostfxr负责解析并加载运行时与所需框架读取.runtimeconfig.jsonhostpolicy负责应用配置、解析.deps.json依赖构造 TPA 程序集列表并最终加载、初始化coreclr运行时库。编辑方式在资源管理器中双击上述任一个.slnx文件即可打开这通常是完成大部分编辑工作所需的全部操作。三、用 build.cmd -vs 一键生成并打开解决方案原生解决方案由构建生成官方提供了两条命令来生成并自动在 Visual Studio 中打开对应解决方案在仓库根目录执行./build.cmd -vs CoreCLR.slnx -a Arch -c BuildType ./build.cmd -vs corehost.slnx -a Arch -c BuildType参数说明参数含义典型取值-vs solution指定要生成并打开的解决方案文件名CoreCLR.slnx、corehost.slnx-a Arch目标架构Architecturex64、x86、arm64等-c BuildType构建配置ConfigurationDebug默认、Checked、Release不显式指定架构与配置时默认值为x64 Debug。同样的机制也适用于托管侧工程例如在 windows-requirements.md 中提到可通过.\build.cmd -vs System.Text.RegularExpressions直接加载某个库的解决方案从而避免修改机器全局环境。该机制同样被 NativeAOT 与测试流程复用nativeaot.md 提到build.cmd -vs src\coreclr\tools\aot\ilc.slnx可打开 ILC 解决方案build.cmd -vs nativeaot打开 NativeAOT 解决方案host 测试指南 使用build.cmd -vs Microsoft.DotNet.CoreSetup -rc Release -lc Release打开 CoreSetup 宿主工程。此外由于解决方案必须先生成如果直接双击artifacts下的.slnx而尚未构建过将无法正常使用——务必遵循先构建、后打开的顺序。四、深入调试 CoreCLR从构建到断点编辑与调试密不可分。Debugging CoreCLR 指南 给出了从零开始的完整调试流程与上文先构建的原则一脉相承。核心要点如下。1. 构建调试所需的 subset开始调试 CoreCLR 前强烈建议至少以Debug配置构建clrsubset以生成最佳调试体验所需的产物文件.\build.cmd -s clr -c Debug-c Debug是默认配置可省略文档保留它仅为表意清晰。若因故缺少System.Private.CoreLib.dll无需整体重建可只重编 CoreLib 相关子集.\build.cmd -s clr.corelibclr.nativecorelib -c Debug注意当使用CORE_LIBRARIES环境变量调试时libssubset 也必须事先构建。Linux/macOS 下命令对应为./build.sh -s clr -c Debug与./build.sh -s clr.corelibclr.nativecorelib -c Debug。2. 三种调试方式总览该指南覆盖的调试路径包括Visual StudioWindows既可通过build.cmd -vs coreclr.slnx打开解决方案调试也可用Open Folder CMake方式选择src/coreclr/CMakeLists.txt作为 CMake 工作区还可附加调试由 CLI 脚本clrlibssubset 构建 .\src\tests\build.cmd generatelayoutonly生成 Core_Root构建出的corerun.exeVisual Studio Code安装 C# 扩展并配置launch.jsontype: coreclr、program指向 corerun、justMyCode: false、enableStepFiltering: falselldbLinux/macOSlldb -- /path/to/corerun /path/to/app.dll args随后plugin load加载 SOS 插件Linux 为libsosplugin.somacOS 为.dylib用breakpoint set -n coreclr_execute_assembly在运行时初始化点下断再用clrstack、sos VerifyHeap等命令分析托管状态。可借助export DOTNET_EnableDiagnostics0禁用托管附加/调试阻止创建命名管道、信号量等调试用 OS 产物。3. 以 Visual Studio 调试为例的关键步骤以 INSTALL 工程为启动项目的经典流程首次配置一次之后直接断点调试运行.\build.cmd clr.nativeprereqs -a arch -c config构建原生构建所需工具仅需一次除非清空artifacts打开 CoreCLR 解决方案build.cmd -vs coreclr.slnx或手动打开artifacts\obj\coreclr\windows.arch.config\ide\CoreCLR.slnx将INSTALL工程设为启动项目在其调试Debugging属性页中配置Command指向corerun.exe如$(SolutionDir)\..\..\..\..\bin\coreclr\windows.$(Platform).$(Configuration)\corerun.exeCommand Arguments待运行的托管程序如HelloWorld.dllWorking DirectoryCoreCLR 二进制目录EnvironmentCORE_LIBRARIES...\bin\runtime\tfm-windows-Configuration-Platform当前分支目标框架为net11.0仅调试只引用 System.Private.CoreLib 的 CLR 测试时可跳过生成 INSTALL 工程以加载 CMake 信息随后在ceemain.cpp的EEStartup()设断点、按 F5 运行即可在 CoreCLR 启动处中断。另外若使用 Visual Studio 2022 17.5 调试自建/每日构建的运行时可能遇到Signature validation failed错误可通过设置环境变量VSDebugger_ValidateDotnetDebugLibSignatures0后从同一命令行启动devenv.exe来临时禁用签名校验官方发布版运行时切勿关闭该校验。五、配套概念Build 配置与 Subset 速览为了让调试体验可控建议先了解 Workflow 指南 中的几个基础概念Build 配置Debug未优化、断言开启、运行最慢但调试体验最佳、Checked仅 CoreCLR已优化但断言开启、Release优化且断言关闭速度最快但优化会降低调试可读性SubsetclrCoreCLR 运行时 CoreLib、libs所有库组件、host.NET 宿主与托管库、mono、packs等可用连接多个 subset如-subset clrlibs -configuration Release -runtimeConfiguration Debug实现运行时 Debug、库 Release 的混合构建调试建议调试运行时用 Debug 构建若只需要库而不调试库源码如 Core_Root 场景库用 Release 可显著提升构建效率。六、See Also动手修改前值得先读的资料Debugging CoreCLR 完整指南涵盖 Windows/VS、VS Code、lldb、SOS、核心转储core dump、AOT 编译器与托管代码调试.NET Runtime 文档总览了解仓库整体架构Workflow Guide构建、测试、CI 失败分析与提交流程NativeAOT 构建文档AOT 编译器相关解决方案与调试入口Libraries VS Code 调试指南面向库代码的 VS Code 调试配置。在动手修改代码之前理解 .NET Runtime 的整体架构运行时、CoreLib、Libraries、Host 四大组件及其构建/调试关系会让后续工作事半功倍。【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
