If you're reading these instructions, you're probably a contributor looking to understand how to build this repo locally on your machine so that you can build, debug, and test changes.
To get started, fork this repo and then clone it locally. This workflow assumes that you have git installed on your development machine.
To create your own fork of the repo, sign in to GitHub and click the repo's Fork button. For more information on managing forks, you can review the GitHub docs on working with forks.
Clone the repo locally using the git clone
command. Since this repo contains submodules, include the --recursive
argument to pull the sources for the submodules locally.
git clone --recursive https://github.com/YOUR_USERNAME/aspnetcore
If you've already cloned the repo without passing the --recursive
flag, fetch the submodule sources at any time with:
git submodule update --init --recursive
All other steps below will be against your fork of the aspnetcore repo (e.g.
YOUR_USERNAME/aspnetcore
), not the officialdotnet/aspnetcore
repo.
If you're on Windows, update the PowerShell execution policy on your machine. For more information on execution policies, review the execution policy docs. To do this, open a PowerShell prompt and issue the following command:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
All Windows commands below assume a PowerShell prompt.
If you're on Windows, install Visual Studio (even if you aren't using it to build) to get the required C++ components and native tools. To install Visual Studio on your machine, use the official installer script in the repo.
Even if you have Visual Studio installed on your machine, we recommend running this installation script to make sure that the correct Visual Studio components are installed.
To modify an existing Visual Studio installation, follow the instructions for installing from a configuration file and use the
.vsconfig
file located in the root of the repository:
./eng/scripts/InstallVisualStudio.ps1 Enterprise Preview
Replace Enterprise
with Professional
or Community
if that is your preferred Visual Studio edition.
The preview channel is currently required as it supports the preview version of the SDK that is used.
If you are seeing errors similar to the imported project "....\aspnetcore.tools\msbuild\17.1.0\tools\MSBuild\Microsoft\VC\v170\Microsoft.Cpp.Default.props" was not found
, try installing/updating Visual Studio as above.
The steps you follow next depend on your preferred development environment:
This repo has JavaScript dependencies, so you need Node.js.
Before you open project in Visual Studio, install the required dependencies and set up the repo by running the restore.cmd
script in the root of the repo:
./restore.cmd
You'll typically focus on one project in the repo. You can use the startvs.cmd
command to launch Visual Studio in a particular project area. For example, to launch Visual Studio in the Components
project:
cd src\Components
./startvs.cmd
We have a single .sln file for all of ASP.NET Core, but most people don't work with it directly because Visual Studio doesn't currently handle projects of this scale very well.
Instead, we have many Solution Filter (.slnf) files which include a sub-set of projects. For more information on solution files, you can review the official Visual Studio doc.
These principles guide how we create and manage .slnf files:
You can now build, debug, and test using Visual Studio. For more information on using Visual Studio to build and run projects, you can review the official Visual Studio docs.
These steps also apply to editors other than Visual Studio Code. If you use a different editor, replace
code
in the steps below with your editor's equivalent command.
To use Visual Studio Code for developing in this repo, you need Visual Studio Code installed and the ability to launch code
from the command line.
This repo has JavaScript dependencies, so you need Node.js.
Before you open anything in Visual Studio Code, run the restore
script in the root of the repo to install the required .NET dependencies.
# Linux or Mac
./restore.sh
# Windows
./restore.cmd
After the restore
script finishes, activate the locally installed .NET by running the following command.
# Linux or Mac
source activate.sh
# Windows - note the leading period followed by a space
. ./activate.ps1
After you've activated the locally installed .NET, open the project you want to modify by running the code
command in the project's directory. For example, if you want to modify thesrc/Http
project:
cd src/Http
code .
If you're using a different editor, replace
code
with your editor's equivalent launch command (for example,vim
).
Once you've opened the project in VS Code, you can build and test changes by running the ./build.sh
command in the terminal.
The
build.sh
orbuild.cmd
script will be local to the directory of the project you opened. For example, the script located in thesrc/Http
directory. If you want to build the whole tree, use thebuild.sh
orbuild.cmd
that is located in theeng
directory.
# Linux or Mac
./build.sh
./build.sh -test
# Windows
./build.cmd
./build.cmd -test
Alternatively, you can use the dotnet test
and dotnet build
commands, alongside specific project files, once you've activated the locally installed .NET SDK.
# Linux or Mac
source activate.sh
dotnet build
dotnet test --filter "MySpecificUnitTest"
# Windows
. ./activate.ps1
dotnet build
dotnet test --filter "MySpecificUnitTest"
If you have Codespaces enabled on your GitHub user account, you can use Codespaces to make code changes in the repo by using a cloud-based editor environment.
Navigate to your fork of the repo and select the branch in which you'd like to make your code changes.
If you haven't yet created a working branch, do so by using the GitHub UI or locally by first checking out and then pushing the new branch.
Open a Codespace for your branch by selecting the Code button > Codespaces tab > Create codespace.
The Codespace will spend a few minutes building and initializing. Once it's done, you'll be able to navigate the Codespace in a web-based VS Code environment.
You can use the dotnet build
and dotnet test
commands to build and test specific projects within the repo.
You don't need to activate the locally installed .NET SDK or run the restore
script because it's done during the Codespace initialization process.
See BuildErrors for a description of common issues you might run into while building the repo.
This ASP.NET Core repo contains a top-level build script located at eng/build.cmd
and eng/build.sh
and local build scripts within each directory. The scripts can be used to restore, build, and test the repo with support for a variety of flags. This section documents the common flags and some recommended invocation patterns.
We do not recommend running the top-level build script for the repo. You'll rarely need to build the entire repo; building a sub-project is usually sufficient for your workflow.
Common arguments that can be invoked on the build.cmd
or build.sh
scripts include:
Property | Description |
---|---|
Configuration |
Debug or Release . Default = Debug . |
TargetArchitecture | The CPU architecture to build for (x64, x86, arm, arm64). |
TargetOsName | The base runtime identifier to build for (win, linux, osx, linux-musl). |
Command | What does it do? |
---|---|
.\build.cmd -Configuration Release |
Build projects in a subdirectory using a Release configuration. Can be run in any project subdirectory. |
.\build.cmd -test |
Run all unit tests in the current project. Can be run in any project subdirectory. |
While it's typically better to use the project-specific build scripts, the repo-level build scripts located in the eng
directory can also be used for project-specific invocations.
Command | What does it do? |
---|---|
.\eng\build.cmd -all -pack -arch x64 |
Build development packages for all the shipping projects in the repo. Must be run from the root of the repo. |
.\eng\build.cmd -test -projects .\src\Framework\test\Microsoft.AspNetCore.App.UnitTests.csproj |
Run all the unit tests in the Microsoft.AspNetCore.App.UnitTests project. |
.\eng\build.cmd -noBuildNative -noBuildManage |
Builds the repo and skips native and managed projects, a quicker alternative to ./restore.cmd . Must be run from the root of the repo. |
To support building and testing the projects in the repo, several dependencies must be installed. Some dependencies are required regardless of the project area you want to work in. Other dependencies are optional depending on the project. Most required dependencies are installed automatically by the restore
scripts, included by default in most modern operating systems, or installed automatically by the Visual Studio installer.
Dependency | Use |
---|---|
Git source control | Used for cloning, branching, and other source control-related activities in the repo. |
.NET | A preview version of the .NET SDK is used for building projects within the repo. Installed automatically by the restore script. |
curl/wget | Used for downloading installation files and assets from the web. |
tar | Used for unzipping installation assets. Included by default on macOS, Linux, and Windows 10 and above. |
Dependency | Use | Notes |
---|---|---|
Selenium | Used to run integration tests in the Components (aka Blazor) project. |
|
Playwright | Used to run template tests defined in the ProjectTemplates work. |
|
Chrome | Required when running tests with Selenium or Playwright in the projects above. When using Playwright, the dependency is automatically installed. | |
Java Development Kit (v11 or newer) | Required when building the Java SignalR client. Can be installed using the ./eng/scripts/InstallJdk.ps1 script on Windows. |
Ensure that the JAVA_HOME directory points to the installation and that the PATH has been updated to include the $(jdkInstallDir)/bin folder. |
Wix | Required when working with the Windows installers in the Windows installers project. | |
Node.js | Used for building JavaScript assets in the repo, such as those in Blazor and SignalR. | Required a minimum version of the current NodeJS LTS. |
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。