|
|
@@ -15,13 +15,13 @@ This tutorial assumes that you are familiar with:
|
|
|
|
|
|
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.
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
git clone --recursive https://github.com/dotnet/aspnetcore
|
|
|
```
|
|
|
|
|
|
If you've already cloned the aspnetcore repo without fetching subdmoule sources, you can fetch them after cloning by running the following command.
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
git submodule update --init --recursive
|
|
|
```
|
|
|
|
|
|
@@ -45,61 +45,63 @@ Visual Studio 2019 (16.8) is required to build the repo locally. If you don't ha
|
|
|
> :bulb: To install Visual Studio from the preview channel, you can use the `-Channel` flag to set the channel (`-Channel Preview`).
|
|
|
> :bulb: Even if you have installed Visual Studio, we still recommend using this script to install again to avoid errors due to missing components.
|
|
|
|
|
|
-```ps1
|
|
|
-PS> ./eng/scripts/InstallVisualStudio.ps1 [-Edition {Enterprise|Community|Professional}] [-Channel {Release|Preview}]
|
|
|
+```powershell
|
|
|
+./eng/scripts/InstallVisualStudio.ps1 [-Edition {Enterprise|Community|Professional}] [-Channel {Release|Preview}]
|
|
|
```
|
|
|
|
|
|
> :bulb: 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](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy).
|
|
|
+> in PowerShell. For more information on execution policies, you can read the [execution policy docs](https://docs.microsoft.com/powershell/module/microsoft.powershell.security/set-executionpolicy).
|
|
|
|
|
|
The [global.json](/global.json) file specifies the minimum requirements needed to build using `msbuild`. The [eng/scripts/vs.json](/eng/scripts/vs.json) file provides a description of the components needed to build within VS. If you plan on developing in Visual Studio, you will need to have these components installed.
|
|
|
|
|
|
-> :bulb: The `IntallVisualStudio.ps1` script mentioned above reads from the `vs.json` file to determine what components to install.
|
|
|
+> :bulb: The `InstallVisualStudio.ps1` script mentioned above reads from the `vs.json` file to determine what components to install.
|
|
|
|
|
|
-#### [Git](https://git-scm.org)
|
|
|
+#### [Git](https://git-scm.org) on Windows
|
|
|
|
|
|
If you're reading this, you probably already have Git installed to support cloning the repo as outlined in Step 1.
|
|
|
|
|
|
-#### [NodeJS](https://nodejs.org)
|
|
|
+#### [NodeJS](https://nodejs.org) on Windows
|
|
|
|
|
|
-Building the repo requires version 10.14.2 or newer of Node. You can find installation executables for Node at https://nodejs.org.
|
|
|
+Building the repo requires version 10.14.2 or newer of Node. You can find installation executables for Node at <https://nodejs.org>.
|
|
|
|
|
|
-#### [Yarn](https://yarnpkg.com/)
|
|
|
+#### [Yarn](https://yarnpkg.com/) on Windows
|
|
|
|
|
|
-NodeJS installes 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.
|
|
|
+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.
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
npm install -g yarn
|
|
|
```
|
|
|
|
|
|
-#### Java Development Kit in Windows*
|
|
|
+#### 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>
|
|
|
+
|
|
|
+- 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](/eng/scripts/InstallJdk.ps1) to install a version of the JDK that will only be used in this repo.
|
|
|
|
|
|
-```ps1
|
|
|
-PS> ./eng/scripts/InstallJdk.ps1
|
|
|
+```powershell
|
|
|
+./eng/scripts/InstallJdk.ps1
|
|
|
```
|
|
|
|
|
|
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.
|
|
|
+
|
|
|
+- 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.
|
|
|
|
|
|
#### 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>.
|
|
|
|
|
|
-#### Wix (Optional)
|
|
|
+#### WiX (Optional)
|
|
|
|
|
|
-If you plan on working with the Windows installers defined in [src/Installers/Windows](../src/Installers/Windows), you will need to install the Wix toolkit from https://wixtoolset.org/releases/.
|
|
|
+If you plan on working with the Windows installers defined in [src/Installers/Windows](../src/Installers/Windows), you will need to install the WiX toolkit from <https://wixtoolset.org/releases/>.
|
|
|
|
|
|
### On macOS/Linux
|
|
|
|
|
|
-You can also build ASP.NET Core on macOS or Linux. macOS Sierra or newer is required if you're building on macOS. If you're building on Linux, your machine will need to meet the [.NET Core Linux preequisities](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites).
|
|
|
+You can also build ASP.NET Core on macOS or Linux. macOS Sierra or newer is required if you're building on macOS. If you're building on Linux, your machine will need to meet the [.NET Core Linux prerequisites](https://docs.microsoft.com/dotnet/core/linux-prerequisites).
|
|
|
|
|
|
> :bulb: 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.
|
|
|
|
|
|
@@ -107,42 +109,45 @@ You can also build ASP.NET Core on macOS or Linux. macOS Sierra or newer is requ
|
|
|
|
|
|
`curl` and `wget` are command line tools that can be used to download files from an HTTP server. Either utility will need to be installed in order to complete the setup. Typically, these will be included on your machine by default.
|
|
|
|
|
|
-If neither utility is installed, you can install curl (https://curl.haxx.se) or wget (https://www.gnu.org/software/wget).
|
|
|
+If neither utility is installed, you can install curl (<https://curl.haxx.se>) or wget (<https://www.gnu.org/software/wget>).
|
|
|
|
|
|
-##### Git
|
|
|
+#### Git
|
|
|
|
|
|
If you've made it this far, you've already got `Git` installed. Sit back, relax, and move on to the next requirement.
|
|
|
|
|
|
#### [NodeJS](https://nodejs.org)
|
|
|
|
|
|
-Building the repo requires version 10.14.2 or newer of Node. You can find installation executables for Node at https://nodejs.org.
|
|
|
+Building the repo requires version 10.14.2 or newer of Node. You can find installation executables for Node at <https://nodejs.org>.
|
|
|
|
|
|
#### [Yarn](https://yarnpkg.com/)
|
|
|
|
|
|
-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.
|
|
|
+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.
|
|
|
|
|
|
```bash
|
|
|
-$ npm install -g yarn
|
|
|
+npm install -g yarn
|
|
|
```
|
|
|
|
|
|
#### Java Development Kit
|
|
|
|
|
|
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>
|
|
|
+
|
|
|
+- OpenJDK <https://jdk.java.net/>
|
|
|
+- Oracle's JDK <https://www.oracle.com/technetwork/java/javase/downloads/index.html>
|
|
|
|
|
|
Similar to [the instructions above for Windows](#java-development-kit-in-windows), be sure that the the `JAVA_HOME` environment variable is set to the location of your Java installation.
|
|
|
|
|
|
## Step 3: Build the repo
|
|
|
|
|
|
-Before opening our .sln/.slnf files in Visual Studio or VS Code, you will need to build the repo locally.
|
|
|
+Before opening our .sln/.slnf files in Visual Studio or VS Code, you will need to at least restore the repo locally.
|
|
|
|
|
|
### In Visual Studio
|
|
|
|
|
|
-To set up your project for development on Visual Studio, you'll need to execute the following command.
|
|
|
+To set up your project for development on Visual Studio, you'll need to execute the following command. Building
|
|
|
+subsets of the repo e.g. Java projects may (depending on your scenario) be necessary before building within Visual
|
|
|
+Studio because those projects are not listed in AspNetCore.sln.
|
|
|
|
|
|
-```ps1
|
|
|
-PS1> .\restore.cmd
|
|
|
+```powershell
|
|
|
+.\restore.cmd
|
|
|
```
|
|
|
|
|
|
> :bulb: If you happen to be working on macOS or Linux, you can use the `restore.sh` command.
|
|
|
@@ -154,18 +159,21 @@ to open the .sln file or one of the project specific .slnf files to work on the
|
|
|
> 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.
|
|
|
|
|
|
-Typically, you want to focus on a single project within the monorepo. For example,
|
|
|
+> :bulb: Rerunning the above command or, perhaps, the quicker `.\build.cmd -noBuildNative -noBuildManaged` may be
|
|
|
+> necessary after switching branches, especially if the `$(DefaultNetCoreTargetFramework)` value changes.
|
|
|
+
|
|
|
+Typically, you want to focus on a single project within this large repo. For example,
|
|
|
if you want to work on Blazor WebAssembly, you'll need to launch the solution file for that project by changing into the `src/Components`
|
|
|
directory and executing `startvs.cmd` in that directory like so:
|
|
|
|
|
|
-```ps1
|
|
|
-PS1> cd src\Components
|
|
|
-PS1> .\startvs.cmd
|
|
|
+```powershell
|
|
|
+cd src\Components
|
|
|
+.\startvs.cmd
|
|
|
```
|
|
|
|
|
|
After opening the solution in Visual Studio, you can build/rebuild using the controls in Visual Studio.
|
|
|
|
|
|
-> :exclamation: VS for Mac does not currently support opening .slnf files so you must use VS Code when developing on macOS.
|
|
|
+> :exclamation: VS for Mac does not currently support opening .slnf files. So, you must use VS Code when developing on macOS.
|
|
|
|
|
|
#### A brief interlude on solution files
|
|
|
|
|
|
@@ -173,7 +181,7 @@ We have a single .sln file for all of ASP.NET Core, but most people don't work w
|
|
|
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. See the Visual Studio
|
|
|
-documentation [here](https://docs.microsoft.com/en-us/visualstudio/ide/filtered-solutions?view=vs-2019) for more
|
|
|
+documentation [here](https://docs.microsoft.com/visualstudio/ide/filtered-solutions) for more
|
|
|
information about Solution Filters.
|
|
|
|
|
|
These principles guide how we create and manage .slnf files:
|
|
|
@@ -194,9 +202,8 @@ Use these command to launch VS Code with the right settings.
|
|
|
|
|
|
On Windows (requires PowerShell):
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
# The extra dot at the beginning is required to 'dot source' this file into the right scope.
|
|
|
-
|
|
|
. .\activate.ps1
|
|
|
code .
|
|
|
```
|
|
|
@@ -211,15 +218,15 @@ code .
|
|
|
> :bulb: Note that if you are using the "Remote-WSL" extension in VSCode, the environment is not supplied
|
|
|
> to the process in WSL. You can workaround this by explicitly setting the environment variables
|
|
|
> in `~/.vscode-server/server-env-setup`.
|
|
|
-> See https://code.visualstudio.com/docs/remote/wsl#_advanced-environment-setup-script for details.
|
|
|
+> See <https://code.visualstudio.com/docs/remote/wsl#_advanced-environment-setup-script> for details.
|
|
|
|
|
|
-## Building on command-line
|
|
|
+### Building on command-line
|
|
|
|
|
|
When developing in VS Code, you'll need to use the `build.cmd` or `build.sh` scripts in order to build the project. You can learn more about the command line options available, check out [the section below](using-dotnet-on-command-line-in-this-repo).
|
|
|
|
|
|
On Windows:
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
.\build.cmd
|
|
|
```
|
|
|
|
|
|
@@ -237,16 +244,15 @@ At this point, you will have all the dependencies installed and a code editor to
|
|
|
|
|
|
The section below provides some helpful guides for using the `dotnet` CLI in the ASP.NET Core repo.
|
|
|
|
|
|
-## Using `dotnet` on command line in this repo
|
|
|
+### 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):
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
# The extra dot at the beginning is required to 'dot source' this file into the right scope.
|
|
|
-
|
|
|
. .\activate.ps1
|
|
|
```
|
|
|
|
|
|
@@ -264,7 +270,7 @@ Tests are not run by default. Use the `-test` option to run tests in addition to
|
|
|
|
|
|
On Windows:
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
.\build.cmd -test
|
|
|
```
|
|
|
|
|
|
@@ -298,7 +304,7 @@ These scripts will build and test the projects within a specific directory. Furt
|
|
|
|
|
|
Additional properties can be added as an argument in the form `/property:$name=$value`, or `/p:$name=$value` for short. For example:
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
.\build.cmd -Configuration Release
|
|
|
```
|
|
|
|
|
|
@@ -310,14 +316,18 @@ 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
|
|
|
+### Resx files
|
|
|
+
|
|
|
+If you need to make changes to a .resx file, run `dotnet msbuild t:/Resgen <path to csproj>`. This will update the generated C#.
|
|
|
+
|
|
|
+## Step 5: 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"](./Artifacts.md) for more explanation of the different folders produced by a build.
|
|
|
|
|
|
Building installers does not run as part of `build.cmd` run without parameters, so you should opt-in for building them:
|
|
|
|
|
|
-```ps1
|
|
|
+```powershell
|
|
|
.\build.cmd -all -pack -arch x64
|
|
|
.\build.cmd -all -pack -arch x86 -noBuildJava
|
|
|
.\build.cmd -buildInstallers
|
|
|
@@ -325,8 +335,8 @@ Building installers does not run as part of `build.cmd` run without parameters,
|
|
|
|
|
|
*Note*: Additional build steps listed above aren't necessary on Linux or macOS.
|
|
|
|
|
|
-* Run the installers produced in `artifacts/installers/{Debug, Release}/` for your platform.
|
|
|
-* Add a NuGet.Config to your project directory with the following content:
|
|
|
+- 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
|
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
|
@@ -341,7 +351,7 @@ Building installers does not run as part of `build.cmd` run without parameters,
|
|
|
|
|
|
*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.
|
|
|
+- Update the versions on `PackageReference` items in your .csproj project file to point to the version from your local build.
|
|
|
|
|
|
```xml
|
|
|
<ItemGroup>
|
|
|
@@ -352,55 +362,6 @@ Building installers does not run as part of `build.cmd` run without parameters,
|
|
|
Some features, such as new target frameworks, may require prerelease tooling builds for Visual Studio.
|
|
|
These are available in the [Visual Studio Preview](https://www.visualstudio.com/vs/preview/).
|
|
|
|
|
|
-## Resx files
|
|
|
-
|
|
|
-If you need to make changes to a .resx file, run `dotnet msbuild t:/Resgen <path to csproj>`. This will update the generated C#.
|
|
|
-
|
|
|
## Troubleshooting
|
|
|
|
|
|
-This section contains a troubleshooting guide for common issues you might run into while building the repo.
|
|
|
-
|
|
|
-### Common error: CS0006
|
|
|
-
|
|
|
-Opening solution filters 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 filter 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/slnf files to include the new project. In some cases, it is sometimes the intended behavior of the .slnf which has been crafted to only include a subset of projects.
|
|
|
-
|
|
|
-#### You can fix this in one of three ways
|
|
|
-
|
|
|
-1. Build the project on command line. In most cases, running `build.cmd` on command line solves this problem.
|
|
|
-2. If the project is missing from the .sln file entirely, you can use `dotnet sln add` to add it, or else right click on the solution/folder in Visual Studio and choose Add->Existing Project, and adding it.
|
|
|
-3. If it is present in the .sln, but not the .slnf, you can update the solution filter to include the missing project. You can either do this one by right-clicking on project in Visual Studio and choosing to load it's direct dependencies, and then saving. Alternatively, you can hand edit the .slnf file - it's a fairly simple json format.
|
|
|
-
|
|
|
-### Common error: Unable to locate the .NET Core SDK
|
|
|
-
|
|
|
-Executing `.\restore.cmd` or `.\build.cmd` may produce these errors:
|
|
|
-
|
|
|
-> error : Unable to locate the .NET Core SDK. Check that it is installed and that the version specified in global.json (if any) matches the installed version.
|
|
|
-> error MSB4236: The SDK 'Microsoft.NET.Sdk' specified could not be found.
|
|
|
-
|
|
|
-In most cases, this is because the option _Use previews of the .NET Core SDK_ in VS2019 is not checked. Start Visual Studio, go to _Tools > Options_ and check _Use previews of the .NET Core SDK_ under _Environment > Preview Features_.
|
|
|
-
|
|
|
-### Common error: HTTP Error 500.33 - ANCM Request Handler Load Failure
|
|
|
-
|
|
|
-The [ASP.NET Core Module](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/aspnet-core-module) (ANCM) for IIS is not supported when running projects in this repository.
|
|
|
-
|
|
|
-After using `startvs.cmd` to open a solution in Visual Studio, the Kestrel web host option must be used (name of the project) and not IIS Express.
|
|
|
-
|
|
|
-Example of running the `MvcSandbox` project:
|
|
|
-
|
|
|
-`.\startvs.cmd .\src\Mvc\Mvc.sln`
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-### Common error: error : Unable to load the service index for …
|
|
|
-
|
|
|
-When attempting to restore servicing tags e.g. `v3.1.7`, the NuGet.config file may contain internal feeds that are not accessible. This will result in errors such as
|
|
|
-
|
|
|
-``` text
|
|
|
-...\aspnetcore\.dotnet\sdk\3.1.103\NuGet.targets(123,5): error : Unable to load the service index for source https://pkgs.dev.azure.com/dnceng/_packaging/darc-int-dotnet-extensions-784b0ffa/nuget/v3/index.json. [...\Temp\1gsd3rdo.srb\restore.csproj] [...\.nuget\packages\microsoft.dotnet.arcade.sdk\1.0.0-beta.20213.4\tools\Tools.proj]
|
|
|
-```
|
|
|
-
|
|
|
-The `darc-int-...` feeds in NuGet.config are used only when building internally and are not needed after the tags are created. Delete all such entries in the file and retry.
|
|
|
+See [BuildErrors](./BuildErrors.md) for a description of common issues you might run into while building the repo.
|
Doug Bunting