Skip to content
Branch: master
Find file Copy path
Find file Copy path
7 contributors

Users who have contributed to this file

@natemcmaster @Tratcher @pranavkm @jkotalik @JamesNK @dotnet-maestro-bot @ajaybhargavb
224 lines (161 sloc) 8.79 KB

Build ASP.NET Core from Source

Building ASP.NET Core from source allows you tweak and customize ASP.NET Core, and to contribute your improvements back to the project.

See for known issues and to track ongoing work.

Install pre-requistes


Building ASP.NET Core on Windows requires:


Building ASP.NET Core on macOS or Linux requires:

Clone the source code

ASP.NET Core uses git submodules to include source from a few other projects.

For a new copy of the project, run:

git clone --recursive

To update an existing copy, run:

git submodule update --init --recursive

Building in Visual Studio

Before opening our .sln files in Visual Studio or VS Code, you need to perform the following actions.

  1. Executing the following on command-line:


    This will download required tools and build the entire repository once. At that point, you should be able to open .sln files to work on the projects you care about.

    💡 Pro tip: you will also want to run this command after pulling large sets of changes. On the master branch, we regularly update the versions of .NET Core SDK required to build the repo. You will need to restart Visual Studio every time we update the .NET Core SDK.

  2. Use the startvs.cmd script to open Visual Studio .sln files. This script first sets required environment variables.

Solution files

We don't have a single .sln file for all of ASP.NET Core because Visual Studio doesn't currently handle projects of this scale. Instead, we have many .sln files which include a sub-set of projects. These principles guide how we create and manage .slns:

  1. Solution files are not used by CI or command line build scripts. They are for meant for use by developers only.
  2. Solution files group together projects which are frequently edited at the same time.
  3. Can't find a solution that has the projects you care about? Feel free to make a PR to add a new .sln file.

💡 Pro tip: dotnet new sln and dotnet sln are one of the easiest ways to create and modify solutions.

Common error: CS0006

Opening solution files and building may produce an error code CS0006 with a message such

Error CS0006 Metadata file 'C:\src\aspnet\AspNetCore\artifacts\bin\Microsoft.AspNetCore.Metadata\Debug\netstandard2.0\Microsoft.AspNetCore.Metadata.dll' could not be found

The cause of this problem is that the solution you are using does not include the project that produces this .dll. This most often occurs after we have added new projects to the repo, but failed to update our .sln files to include the new project. In some cases, it is sometimes the intended behavior of the .sln which has been crafted to only include a subset of projects.

You can fix this in one of two ways

  1. Build the project on command line. In most cases, running build.cmd on command line solve this problem.
  2. Update the solution to include the missing project. You can either do this one by one using dotnet sln
    dotnet sln add C:\src\AspNetCore\src\Hosting\Abstractions\src\Microsoft.AspNetCore.Hosting.Abstractions.csproj
    Or you can use this script to automatically traverse the project reference graph, which then invokes dotnet sln for you: eng/scripts/AddAllProjectRefsToSolution.ps1.
    ./eng/scripts/AddAllProjectRefsToSolution.ps1 -WorkingDir src/Mvc/

Building with Visual Studio Code

Using Visual Studio Code with this repo requires setting environment variables on command line first. Use these command to launch VS Code with the right settings.

On Windows (requires PowerShell):

# The extra dot at the beginning is required to 'dot source' this file into the right scope.

. .\activate.ps1
code .

On macOS/Linux:

code .

Building on command-line

You can also build the entire project on command line with the build.cmd/.sh scripts.

On Windows:


On macOS/Linux:


Using dotnet on command line in this repo

Because we are using pre-release versions of .NET Core, you have to set a handful of environment variables to make the .NET Core command line tool work well. You can set these environment variables like this

On Windows (requires PowerShell):

# The extra dot at the beginning is required to 'dot source' this file into the right scope.

. .\activate.ps1

On macOS/Linux:

source ./

Running tests on command-line

Tests are not run by default. Use the -test option to run tests in addition to building.

On Windows:

.\build.cmd -test

On macOS/Linux:

./ --test

Building a subset of the code

This repository is large. Look for build.cmd/.sh scripts in subfolders. These scripts can be used to invoke build and test on a smaller set of projects.

Furthermore, you can use flags on build.cmd/.sh to build subsets based on language type, like C++, TypeScript, or C#. Run --help or build.cmd -help for details.

Build properties

Additional properties can be added as an argument in the form /property:$name=$value, or /p:$name=$value for short. For example:

.\build.cmd /p:Configuration=Release

Common properties include:

Property Description
BuildNumberSuffix (string). A specific build number, typically from a CI counter, which is appended to the pre-release label.
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).

Use the result of your build

After building ASP.NET Core from source, you will need to install and use your local version of ASP.NET Core. See "Artifacts" for more explanation of the different folders produced by a build.

  • Run the installers produced in artifacts/installers/{Debug, Release}/ for your platform.

  • Add a NuGet.Config to your project directory with the following content:

    <?xml version="1.0" encoding="utf-8"?>
            <clear />
            <add key="MyBuildOfAspNetCore" value="C:\src\aspnet\AspNetCore\artifacts\packages\Debug\Shipping\" />
            <add key="" value="" />

    NOTE: This NuGet.Config should be with your application unless you want nightly packages to potentially start being restored for other apps on the machine.

  • Update the versions on PackageReference items in your .csproj project file to point to the version from your local build.

      <PackageReference Include="Microsoft.AspNetCore.SpaServices" Version="3.0.0-dev" />

Some features, such as new target frameworks, may require prerelease tooling builds for Visual Studio. These are available in the Visual Studio Preview.

Resx files

If you need to make changes to a .resx file, run dotnet msbuild /t:Resx <path to csproj>. This will update the generated C#.

You can’t perform that action at this time.