ASP.NET Core 仓库源码构建完全指南从 clone、restore 到本地构建与测试【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore本文基于 ASP.NET Core 官方仓库文档 BuildFromSource 与仓库内实际构建脚本完整讲解贡献者如何在本地把 aspnetcore 仓库搭建成可构建、可调试、可测试的工作区涵盖 fork/clone 与子模块拉取、Windows 环境一次性配置、Visual Studio / VS Code / Codespaces 三条开发路径以及顶层构建脚本eng/build.sheng/build.cmd的全部关键参数与推荐用法。读完本文你将能够独立完成从克隆仓库到运行单元测试的完整闭环并理解restore、activate、局部build.sh等脚本在底层实际执行了什么。一、准备工作Fork、Clone 与子模块如果你正在阅读本文档大概率是希望作为贡献者在本地构建、调试和测试这个仓库的改动。整个流程假设开发机上已安装 Git。在 GitHub 上登录并点击仓库的Fork按钮创建属于自己的 fork。使用git clone克隆仓库到本地。由于该仓库包含子模块必须携带--recursive参数以同时拉取子模块源码git clone --recursive https://github.com/YOUR_USERNAME/aspnetcore如果克隆时没有传--recursive也可以随时用下面命令补拉子模块git submodule update --init --recursive注意后续所有步骤都针对你自己的 fork如YOUR_USERNAME/aspnetcore而不是官方dotnet/aspnetcore仓库。从仓库根目录的 .gitmodules 可以看到aspnetcore 目前声明了两个子模块src/submodules/googletestGoogleTest用于 C 单元测试src/submodules/MessagePack-CSharpMessagePack-CSharp这正是克隆时必须--recursive的原因如果这两个目录是空的涉及它们的本地构建会缺少源码。更多子模块相关背景可参考 docs/Submodules.md。二、Windows 一次性配置PowerShell 执行策略与 Visual Studio C 组件如果你的开发机是 Windows还需要完成两项与操作系统相关的一次性配置2.1 更新 PowerShell 执行策略打开 PowerShell 提示符执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser后文所有 Windows 命令均默认在 PowerShell 提示符下执行。2.2 安装包含 C 组件的 Visual Studio即使你不打算用 Visual Studio 构建也建议安装它以获取必需的 C 组件和本机工具链。请使用仓库自带的官方安装脚本来安装即使机器上已装有 Visual Studio也推荐运行这个安装脚本确保安装了正确的 VS 组件。如果只是想修改现有安装可以按官方“从配置文件安装”的说明使用仓库根目录下的.vsconfig文件导入配置。./eng/scripts/InstallVisualStudio.ps1 -Edition Enterprise -Channel Preview把Enterprise换成Professional或Community可切换你偏好的版本。当前要求使用 Preview 通道因为它支持仓库正在使用的预览版 SDK见 global.json 中固定的11.0.100-rc.1.26420.103。如果你看到类似the imported project ....\aspnetcore.tools\msbuild\17.1.0\tools\MSBuild\Microsoft\VC\v170\Microsoft.Cpp.Default.props was not found的错误通常是 VS 组件缺失或过旧按上面的方式重新安装/更新 Visual Studio 即可。三、开发路径一Visual Studio仅 Windows完成上面的通用配置后具体操作取决于你选择的开发环境这里以 Visual Studio 为例该仓库包含 JavaScript 依赖因此你需要安装 Node.js。在 Visual Studio 打开项目之前先运行仓库根目录的restore.cmd脚本安装依赖并初始化仓库./restore.cmd从 restore.cmd 的源码看它实际只是调用eng/build.ps1 -all -nobuild -restore即“恢复全部项目类型但跳过编译”因此它安装的是构建所需的 .NET SDK 与工具链安装位置由 global.json 的paths: [.dotnet]指定为仓库内的.dotnet目录。你通常只关注仓库中的某一块项目。可以用startvs.cmd在特定项目区域启动 Visual Studio。例如启动src/Http区域先在该目录构建再启动 VScd src/Http ./build.cmd ./startvs.cmdbuild.cmd/build.sh脚本位于你所打开的项目目录内如src/Http目录下的那个。若想构建整棵树请使用eng目录下的build.cmd/build.sh。从源码看这两个脚本的分工非常清晰局部脚本 src/Http/build.sh 只有一行核心逻辑$repo_root/eng/build.sh --projects $DIR/**/*.*proj $即把当前目录下所有*.csproj/*.fsproj等工程传给顶层构建脚本因此“局部构建”本质上是顶层脚本加一个--projects过滤startvs.cmd 则把DOTNET_ROOT指向仓库内.dotnet、把本地dotnet.exe放到PATH最前然后用devenv.com打开src/Http下指定的.slnf文件src/Http/startvs.cmd保证 IDE 内构建使用与命令行脚本同一套本地 SDK。关于 Solution Filter.slnf文件仓库有一个覆盖全部 ASP.NET Core 的解决方案文件但大多数人不会直接用它因为 Visual Studio 对这种规模的项目处理能力有限。取而代之的是大量 Solution Filter.slnf文件每个只包含一组相关项目的子集。以 src/Http/HttpAbstractions.slnf 为例它通过 JSON 格式声明指向根级AspNetCore.slnx并筛选出 Hosting、DataProtection、Http 系列、TestHost 等一组项目。仓库维护.slnf的原则解决方案文件不被 CI 或命令行构建脚本使用仅供开发者使用它们把“经常被一起编辑”的工程聚合在一起找不到包含你关注项目的解决方案欢迎提 PR 增加新的.slnf文件。完成以上步骤后即可在 Visual Studio 中构建、调试、测试你的改动。四、开发路径二VS Code 或其他编辑器Windows / Linux / macOS这些步骤同样适用于其他编辑器如果使用别的编辑器把下文中的code替换为对应启动命令即可例如vim。需要安装 VS Code并且能从命令行启动code。仓库有 JavaScript 依赖需要安装 Node.js。在 VS Code 打开任何东西之前先运行根目录的restore脚本安装 .NET 依赖# Linux 或 Mac ./restore.sh# Windows ./restore.cmdrestore完成后运行激活脚本启用本地安装的 .NET# Linux 或 Mac source activate.sh# Windows - 注意开头的“点 空格” . ./activate.ps1activate.sh 做的事情是把DOTNET_ROOT设置为$DIR/.dotnet并将其放到PATH最前面还会给 shell 提示符加上仓库名作为视觉标识运行deactivate可还原环境。如果.dotnet/dotnet不存在脚本会提示先运行restore.sh。激活后进入要修改的项目目录并用编辑器打开例如src/Httpcd src/Http code .在终端中运行项目目录内的./build.sh构建并测试# Linux 或 Mac ./build.sh ./build.sh -test# Windows ./build.cmd ./build.cmd -test同样地脚本位于你打开的项目目录内构建整棵树请用eng目录下的build.sh/build.cmd。另一种方式在激活本地 SDK 之后直接使用dotnet build和dotnet test但必须带上具体的项目文件。例如# Linux 或 Mac source activate.sh dotnet build dotnet test --filter MySpecificUnitTest# Windows . ./activate.ps1 dotnet build dotnet test --filter MySpecificUnitTest之所以要求“带具体项目文件”是因为顶层仓库没有可一键全量构建的单一工程dotnet build只应在某个*.csproj/*.fsproj所在目录执行。五、开发路径三GitHub Codespaces如果你的 GitHub 账户启用了 Codespaces可以直接使用云端的 VS Code 环境来修改代码进入你的 fork选择要修改的分支。如果还没有工作分支先通过 Web 界面或本地 checkout 后 push 创建。点击Code按钮 →Codespaces选项卡 →Create codespace打开该分支的 Codespace。初始化会花费几分钟完成后即可在基于 Web 的 VS Code 环境中工作。在 Codespace 中直接使用dotnet build和dotnet test构建和测试仓库内的具体项目。你不需要手动激活本地 .NET SDK也不需要运行restore脚本——这些步骤会在 Codespace 初始化过程中自动完成。六、构建脚本指南eng/build.sheng/build.cmd的深入解析仓库包含位于eng/build.cmd和eng/build.sh的顶层构建脚本以及各子目录内的局部构建脚本。这些脚本支持一系列标志位可用于 restore、build、test 等操作。本节文档化常见参数与推荐调用方式。官方不推荐运行仓库顶层构建脚本来构建整个仓库——你很少需要构建全部工程构建子项目通常就足以支撑你的工作流。6.1 常见参数可传给build.cmd/build.sh的常见参数参数说明ConfigurationDebug或Release。默认 DebugCI 场景下默认Release。TargetArchitecture目标 CPU 架构x64、x86、arm、arm64。TargetOsName目标基础 RIDwin、linux、osx、linux-musl。从 eng/build.sh 的完整用法输出看脚本实际支持的参数远比上表丰富常用的还包括参数说明--[no-]restore/--[no-]build控制是否恢复依赖、是否编译--no-build隐含--no-restore。--[no-]pack/--[no-]publish控制是否产出 NuGet 包、是否执行 publish。--[no-]test是否运行测试。--projects指定要构建的项目列表绝对路径支持 glob如$(pwd)/**/*.csproj这正是各子目录局部build.sh的内部实现方式。--no-build-deps不构建项目间引用只构建指定项目。--all构建所有项目类型managed、native、nodejs、java、installers。--[no-]build-native是否构建 C/C 原生项目。--[no-]build-managed是否构建 C#/F#/VB 托管项目。--[no-]build-nodejs是否构建 NodeJS/TypeScript 项目。--[no-]build-java是否构建 Java 项目SignalR Java 客户端。--[no-]build-installers是否构建 Windows 安装器。--verbosity/--binarylogMSBuild 日志级别与二进制日志开关。--warnAsError/--warnNotAsError控制警告即错误的行为。几个值得注意的默认行为可直接在脚本源码中验证不带任何项目选择参数时脚本默认构建managedC#组及其依赖并打印提示当managed构建开启且 PATH 中检测到node时会自动连带开启 NodeJS 项目构建反之会警告“managed 项目将回退使用上一次构建的 NodeJS 产物可能不是最新”--no-build-native --no-build-managed组合可快速只做工具链初始化与恢复是restore的轻量替代。6.2 常见调用方式命令作用.\build.cmd -Configuration Release以Release配置构建子目录中的项目。可在任意项目子目录运行。.\build.cmd -test运行当前项目的全部单元测试。可在任意项目子目录运行。6.3 仓库级调用虽然更推荐项目级构建脚本但eng目录下的仓库级脚本也支持项目级调用命令作用.\eng\build.cmd -all -pack -arch x64构建仓库中所有 shipping 项目的开发包。必须从仓库根目录运行。.\eng\build.cmd -test -projects .\src\Framework\test\Microsoft.AspNetCore.App.UnitTests.csproj运行Microsoft.AspNetCore.App.UnitTests项目的全部单元测试。.\eng\build.cmd -noBuildNative -noBuildManaged构建仓库但跳过原生与托管项目是./restore.cmd的更快速替代方案。必须从仓库根目录运行。七、仓库依赖完整清单为了支撑仓库内各项目的构建与测试需要安装若干依赖。一部分与你要开发的项目区域无关、始终必需另一部分则按项目可选。大部分必需依赖由restore脚本自动安装或已随现代操作系统默认提供或由 Visual Studio 安装器自动装好。7.1 必需依赖依赖用途Git用于仓库的克隆、分支等源码控制操作。.NET仓库内构建使用的是 .NET SDK 的预览版由restore脚本自动安装安装到仓库内.dotnet目录版本固定在 global.json 中。curl / wget用于从 Web 下载安装文件与资源。tar用于解压安装资源。macOS、Linux 与 Windows 10 及以上系统默认自带。7.2 可选依赖依赖用途备注Selenium运行Components即 Blazor项目的集成测试。Playwright运行ProjectTemplates中的模板测试。Chrome在上述项目中使用 Selenium 或 Playwright 运行测试时必需使用 Playwright 时该依赖会自动安装。Java Development Kitv11 或更新构建 SignalR Java 客户端时需要。Windows 上可用./eng/scripts/InstallJdk.ps1脚本安装。确保JAVA_HOME指向安装目录且PATH包含$(jdkInstallDir)/bin文件夹。Wix处理 Windows 安装器项目 时需要。Node.js构建仓库中的 JavaScript 资源如 Blazor、SignalR 相关。至少需要当前 NodeJS LTS 版本。八、故障排查如果构建过程中遇到常见错误请查阅仓库文档 BuildErrors其中列出了构建仓库时可能遇到的常见问题及对应处理方法。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考