Refresh BuildFromSource docs

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846
+	// for the documentation about the extensions.json format
+	"recommendations": [
+		"ms-dotnettools.csharp",
+		"k--kato.docomment"
+	]
+}

docs/BuildScript.md

@@ -0,0 +1,26 @@
+# A Guide to the Build Script
+
+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 page documents the common flags and some recommended invocation patterns.
+
+It is _not_ recommended to run the top-level build script for the repo. You'll rarely need to build the entire repo and building a particular sub-project is usually sufficient for your workflow.
+
+## Common Arguments
+
+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). |
+
+## Common Invocations
+
+| Command                                                      | What does it do?                                             |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| `.\eng\build.cmd -all -pack -arch x64`                       | Build development packages for all the shipping projects in 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. |
+| `.\build.cmd -Configuration Release`                         | Build projects in a subdirectory using a `Release` configuration. |
+| `.\eng\build.cmd -noBuildNative -noBuildManage`              | Builds the repo and skips native and managed projects, a quicker alternative to `./restore.cmd` |
+| `.\eng\build.cmd -buildInstallers`                           | Builds Windows installers for the ASP.NET Core runtime.      |
+

docs/RepoDependencies.md

@@ -0,0 +1,25 @@
+# Repo Dependencies
+
+To support building and testing all the projects in the repo, various dependencies need to be installed. Some dependencies are required regardless of what project area you want to work in. Other dependencies are optional depending on the project 
+
+## Required Dependencies
+
+| Dependency                                                   | Use                                                          |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| [Git source control](https://git-scm.org/)                   | Used for cloning, branching, and other source control-related activities in the repo. |
+| [.NET](https://dotnet.microsoft.com/)                        | A preview version of the .NET SDK is used for building projects within the repo. |
+| [NodeJS]()                                                   | Used for building JavaScript assets in the repo.             |
+| [Yarn](https://yarnpkg.com/)                                 | Used for installing JavaScript dependencies in the repo.     |
+| [curl](https://curl.haxx.se/)/[wget](https://www.gnu.org/software/wget) | Used for downloading installation files and assets from the web. |
+| [tar](http://gnuwin32.sourceforge.net/packages/gtar.htm)     | Used for unzipping installation assets. Included by default on macOS, Linux, and Windows 10 and above. |
+
+## Optional Dependencies
+
+| Dependency                                                   | Use                                                          |
+| ------------------------------------------------------------ | ------------------------------------------------------------ |
+| [Selenium](https://www.selenium.dev/)                        | Used to run integration tests in the `Components` (aka Blazor) project. |
+| [Playwright](https://playwright.dev/)                        | Used to run template tests defined in the `ProjectTemplates` work. |
+| [Chrome](https://www.google.com/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)](https://jdk.java.net/) | Required when building the Java SignalR client. Can be installed using the `./eng/scripts/InstallJdk.ps1` script on Windows. |
+| [Wix](https://wixtoolset.org/releases/)                      | Required when working with the Windows installers in the [Windows installers project](https://github.com/dotnet/aspnetcore/tree/main/src/Installers/Windows). |
+

docs/UsingBuildResults.md

@@ -0,0 +1,34 @@
+# Using Build Results
+
+Typically, you'll want to validate changes made in the repo by writing unit tests, integration tests, and manually verifying in the sample app. There are some scenarios where it is also helpful to validate changes in larger, more complex apps.
+
+For these scenarios, you can build development versions of the packages shipped from the repo then consume those development versions in your test app.
+
+To start, build the packages with your changes locally on your repo.
+
+```
+.\build.cmd -all -pack -arch x64
+```
+
+The packages are built into the `aspnetcore\artifacts\packages\Debug\Shipping` directory within the repo. 
+
+Within your test app, creating a `nuget.config` file if it doesn't exist already and add the following package source to the config.
+
+```
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+    <packageSources>
+        <clear />
+        <add key="MyBuildOfAspNetCore" value="C:\src\aspnet\AspNetCore\artifacts\packages\Debug\Shipping\" />
+        <add key="NuGet.org" value="https://api.nuget.org/v3/index.json" />
+    </packageSources>
+</configuration>
+```
+
+In the project files for your repo, update the package versions to target the development version. For example, if you want to validate changes to the `Microsoft.AspNetCore.Components.WebAssembly` package. You can make the following changes to the PackageReference.
+
+```diff
+- <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="5.0.0" />
++ <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="7.0.0-dev" />
+```
+

src/Components/Web.JS/package.json

@@ -43,5 +43,8 @@
   "resolutions": {
     "**/set-value": "^3.0.2",
     "url-parse": ">=1.5.0"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/Components/WebAssembly/Authentication.Msal/src/Interop/package.json

@@ -27,5 +27,8 @@
   },
   "dependencies": {
     "@azure/msal-browser": "^2.16.1"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/Components/WebAssembly/WebAssembly.Authentication/src/Interop/package.json

@@ -27,5 +27,8 @@
   },
   "dependencies": {
     "oidc-client": "^1.11.5"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/Components/test/E2ETest/package.json

@@ -19,5 +19,8 @@
     "@types/node": "^13.1.7",
     "ts-node": "^8.6.2",
     "typescript": "^3.7.5"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/JSInterop/Microsoft.JSInterop.JS/src/package.json

@@ -29,5 +29,8 @@
     "rimraf": "^3.0.2",
     "tslint": "^6.1.3",
     "typescript": "^4.2.2"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/ProjectTemplates/BlazorTemplates.Tests/package.json

@@ -12,5 +12,8 @@
   "license": "MIT",
   "dependencies": {
     "selenium-standalone": "^7.1.0"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/ProjectTemplates/test/package.json

@@ -12,5 +12,8 @@
   "license": "MIT",
   "dependencies": {
     "selenium-standalone": "^7.1.0"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/SignalR/clients/ts/FunctionalTests/package.json

@@ -57,5 +57,8 @@
     "url-parse": ">=1.5.0"
   },
   "author": "",
-  "license": "MIT"
+  "license": "MIT",
+  "engines": {
+    "node": "16.x"
+  }
 }

src/SignalR/clients/ts/common/package.json

@@ -30,5 +30,8 @@
     "webpack": "^5.24.1",
     "webpack-cli": "^4.5.0"
   },
-  "dependencies": {}
+  "dependencies": {},
+  "engines": {
+    "node": "16.x"
+  }
 }

src/SignalR/clients/ts/package.json

@@ -12,5 +12,8 @@
     "coverage": "node ./common/node_modules/jest/bin/jest.js --config ./jest.config.js --coverage"
   },
   "author": "Microsoft",
-  "license": "MIT"
+  "license": "MIT",
+  "engines": {
+    "node": "16.x"
+  }
 }

src/SignalR/clients/ts/signalr-protocol-msgpack/package.json

@@ -50,5 +50,8 @@
   "devDependencies": {},
   "resolutions": {
     "url-parse": ">=1.5.0"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }

src/SignalR/clients/ts/signalr/package.json

@@ -59,5 +59,8 @@
     "fetch-cookie": "^0.11.0",
     "node-fetch": "^2.6.1",
     "ws": "^7.4.5"
+  },
+  "engines": {
+    "node": "16.x"
   }
 }