Migrate to single sln file + slnf files (#23581)

Author: Pilchie

AspNetCore.sln

@@ -72,48 +72,52 @@ 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.
+Before opening our .sln/.slnf files in Visual Studio or VS Code, you need to perform the following actions.
 
 1. Executing the following on command-line:
 
    ```ps1
    .\restore.cmd
    ```
 
-   This will download the 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.
+   This will download the required tools and build the entire repository once. At that point, you should be able
+   to open the .sln file or one of the project specific .slnf files to work on the projects you care about.
 
-   > :bulb: 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.
+   > :bulb: 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 the required environment variables.
+2. Use the `startvs.cmd` script to open Visual Studio .sln/.slnf files. This script first sets the 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 .sln files:
+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. See the Visual Studio
+documentation [here](https://docs.microsoft.com/en-us/visualstudio/ide/filtered-solutions?view=vs-2019) for more
+information about Solution Filters.
+
+These principles guide how we create and manage .slnf files:
 
 1. Solution files are not used by CI or command line build scripts. They are 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.
-
-> :bulb: Pro tip: `dotnet new sln` and `dotnet sln` are one of the easiest ways to create and modify solutions.
+3. Can't find a solution that has the projects you care about? Feel free to make a PR to add a new .slnf file.
 
 ### Common error: CS0006
 
-Opening solution files and building may produce an error code CS0006 with a message such
+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 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.
+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 two ways
+#### 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. Update the solution to include the missing project. You can either do this one by one using `dotnet sln`
-
-   ```ps1
-   dotnet sln add C:\src\AspNetCore\src\Hosting\Abstractions\src\Microsoft.AspNetCore.Hosting.Abstractions.csproj
-   ```
+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
 
@@ -230,7 +234,7 @@ TargetOsName             | The base runtime identifier to build for (win, linux,
 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: 
+Building installers does not run as part of `build.cmd` run without parameters, so you should opt-in for building them:
 
 ```ps1
 .\build.cmd -all -pack -arch x64

docs/BuildFromSource.md

@@ -1,3 +1,3 @@
 @ECHO OFF
 
-%~dp0..\..\startvs.cmd %~dp0tools.sln
+%~dp0..\..\startvs.cmd %~dp0tools.slnf

eng/tools/startvs.cmd

@@ -0,0 +1,9 @@
+{
+  "solution": {
+    "path": "..\\..\\AspNetCore.sln",
+    "projects" : [
+      "eng\\tools\\BaselineGenerator\\BaselineGenerator.csproj",
+      "eng\\tools\\RepoTasks\\RepoTasks.csproj"
+    ]
+  }
+}