BuildFromSource.md

Build ASP.NET Core from Source

This document outlines how to build the source in the aspnetcore repo locally for development purposes.

For more info on issues related to build infrastructure and ongoing work, see https://github.com/dotnet/aspnetcore/labels/area-infrastructure.

Step 0: Getting started

This tutorial assumes that you are familiar with:

• Git
• The basics of forking and contributing to GitHub projects
• Command line fundamentals in your operating system of choice

Step 1: Getting the source code

Development is done in your own repo, not directly against the official dotnet/aspnetcore repo. To create your own fork, click the Fork button from our GitHub repo as a signed-in user and your own fork will be created.

💡 All other steps below will be against your fork of the aspnetcore repo (e.g. YOUR_USERNAME/aspnetcore), not the official dotnet/aspnetcore repo.

Cloning your repo locally

ASP.NET Core uses git submodules to include the source from a few other projects. In order to pull the sources of the these submodules when cloning the repo, be sure to pass the --recursive flag to the git clone command.

git clone --recursive https://github.com/YOUR_USERNAME/aspnetcore

If you've already cloned the aspnetcore repo without fetching submodule sources, you can fetch them after cloning by running the following command.

git submodule update --init --recursive

💡 Some ISPs have been known to use web filtering software that has caused issues with git repository cloning, if you experience issues cloning this repo please review https://help.github.com/en/github/authenticating-to-github/using-ssh-over-the-https-port.

Tracking remote changes

The first time you clone your repo locally, you'll want to set an additional Git remote back to the official repo so that you can periodically refresh your repo with the latest official changes.

git remote add upstream https://github.com/dotnet/aspnetcore.git

You can verify the upstream remote has been set correctly.

git remote -v
> origin    https://github.com/YOUR_USERNAME/aspnetcore (fetch)
> origin    https://github.com/YOUR_USERNAME/aspnetcore (push)
> upstream  https://github.com/dotnet/aspnetcore.git (fetch)
> upstream  https://github.com/dotnet/aspnetcore.git (push)

Once configured, the easiest way to keep your repository current with the upstream repository is using GitHub's feature to fetch upstream changes.

Branching

If you ultimately want to be able to submit a PR back to the project or be able to periodically refresh your main branch with the latest code changes, you'll want to do all your work on a new branch.

git checkout -b NEW_BRANCH

Step 2: Install pre-requisites

Developing in the aspnetcore repo requires some additional tools to build the source code and run integration tests.

On Windows

Building ASP.NET Core on Windows (10, version 1803 or newer) requires that you have the following tooling installed.

💡 Be sure you have least 10 GB of disk space and a good Internet connection. The build scripts will download several tools and dependencies onto your machine.

Visual Studio 2022

Visual Studio 2022 (17.1 or above) is required to build the repo locally.

If you don't have Visual Studio installed you can run eng/scripts/InstallVisualStudio.ps1 to install the exact required dependencies. If you do have Visual Studio installed, you can import the configuration from the .vsconfig file at the root of the repository to ensure you have all of the required components.

💡 By default, the script will install Visual Studio Enterprise Edition, however you can use a different edition by passing the -Edition flag. 💡 To install Visual Studio from the preview channel, you can use the -Channel flag to set the channel (-Channel Preview). 💡 Even if you have installed Visual Studio, we still recommend using this script to install again to avoid errors due to missing components. 💡 To update an existing Visual Studio installation or customize the installation path, you can use the -InstallPath flag (-InstallPath "D:\Program Files\Microsoft Visual Studio\2022\Enterprise").

./eng/scripts/InstallVisualStudio.ps1 [-Edition {Enterprise|Community|Professional}] [-Channel {Release|Preview}]

💡 To execute the setup script or other PowerShell scripts in the repo, you may need to update the execution policy on your machine. You can do so by running the Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser command in PowerShell. For more information on execution policies, you can read the execution policy docs.

The global.json file specifies the minimum requirements needed to build using msbuild. The eng/scripts/vs.17.json file provides a description of the components needed to build within Visual Studio. If you plan on developing in Visual Studio, you will need to have these components installed.

💡 The InstallVisualStudio.ps1 script mentioned above reads from the vs.17[.channel].json file to determine what components to install.

Git on Windows

If you're reading this, you probably already have Git installed to support cloning the repo as outlined in Step 1.

NodeJS on Windows

Building the repo requires version 16.11.0 or newer of Node. You can find installation executables for Node at https://nodejs.org.

Yarn on Windows

NodeJS installs the Node package manager (npm) by default. This repo depends on Yarn, an alternate package manager for the Node ecosystem. You can install Yarn from the command line using the following command.

npm install -g yarn

Java Development Kit on Windows

This repo contains some Java source code that depends on an install of the JDK v11 or newer. The JDK can be installed from either:

• OpenJDK https://jdk.java.net/
• Oracle's JDK https://www.oracle.com/technetwork/java/javase/downloads/index.html

Alternatively, you can run eng/scripts/InstallJdk.ps1 to install a version of the JDK that will only be used in this repo.

./eng/scripts/InstallJdk.ps1

NOTE : In order to execute the script you may need to set the right Execution policy. If not you may get an error that the script "cannot be loaded because the execution of scripts is disabled on this system". To get past that you can do the following. As an Administrator, you can set the execution policy by typing this into your PowerShell window:

Set-ExecutionPolicy RemoteSigned

And when you are finished with the script return the execution policy.

Set-ExecutionPolicy Restricted

The build should find any JDK 11 or newer installation on the machine as long as the JAVA_HOME environment variable is set. Typically, your installation will do this automatically. However, if it is not set you can set the environment variable manually:

• Set JAVA_HOME to RepoRoot/.tools/jdk/win-x64/ if you used the InstallJdk.ps1 script.
• Set JAVA_HOME to C:/Program Files/Java/jdk<version>/ if you installed the JDK globally.

You can temporarily set your environmental variable for the scope of the active powershell session using the command

• $env:JAVA_HOME = "C:/[RepoRoot]/.tools/jdk/win-x64/"

Chrome

This repo contains a Selenium-based tests require a version of Chrome to be installed. Download and install it from https://www.google.com/chrome.

Visual Studio Code Extension