Update to the lastest from dotnet/toolset release/3.1xx

documentation/specs/event-source.md

@@ -0,0 +1,25 @@
+# EventSource
+
+[EventSource](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.tracing.eventsource?view=netframework-4.8) is the tool that allows Event Tracing for Windows (ETW) used in MSBuild. Among its useful features, functions with names ending in "start" and "stop" correlate between calls such that it can automatically record how long the event between the two calls took. It also provides an easy way to cheaply opt in or out, log auxiliary messages in addition to time, and add progress updates in the middle of an event as needed.
+
+## EventSource in MSBuild
+EventSource is primarily used to profile code. For MSBuild specifically, a major goal is to reduce the time it takes to run, as measured by the Regression Prevention System (RPS), i.e., running specific scenarios. To find which code segments were likely candidates for improvement, EventSources were added around a mix of processes. Large, high-level processes occur nearly every run of MSBuild andtake a long time. They generally only relatively few times. Smaller methods with well-defined purposes may occur numerous times. Profiling both types of events provides both broad strokes to identify large code segments that underperform and, more specifically, which parts ot them. Profiled functions include:
+
+* XMake: executes MSBuild from the command line.
+* RequestThreadProc: a function to requesting a new builder thread.
+* LoadDocument: loads an XMLDocumentWithLocation from a path.
+* RemoveReferencesMarkedForExclusion: removes blacklisted references from the reference table, putting primary and dependency references in invalid file lists.
+* ComputeClosure: resolves references to, for example, properties to explicit values.
+* EvaluateCondition: checks whether a condition is true and removes false conditionals.
+* Parse: parses an XML document into a ProjectRootElement.
+* Evaluate: Evaluates a project, running several other parts of MSBuild in the process.
+* ExecuteGenerateResource: uses resource APIs to transform resource files into strongly-typed resource classes.
+* SelectItems: identifies a list of files that correspond to an item, potentially with a wildcard.
+* Apply: collects a set of items, mutates them in a specified way, and saves the results.
+* ExecuteTask: executes a task.
+* Save: saves a project to the file system if dirty, creating directories as necessary.
+* LogResults: logs the results from having executed a task.
+
+## Larger context
+
+MSBuild is the build system underlying Visual Studio. As millions of developers use Visual Studio, improvements in MSBuild's efficiency affect millions of developers and their customers.

documentation/specs/event-source.txt

@@ -0,0 +1,32 @@
+# EventSource
+
+[EventSource](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.tracing.eventsource?view=netframework-4.8) is the tool that allows Event Tracing for Windows (ETW) used in MSBuild. Among its useful features, functions with names ending in "start" and "stop" correlate between calls such that it can automatically record how long the event between the two calls took. It also provides an easy way to cheaply opt in or out, log auxiliary messages in addition to time, and add progress updates in the middle of an event as needed.
+
+## EventSource in MSBuild
+EventSource is primarily used to profile code. For MSBuild specifically, a major goal is to reduce the time it takes to run, as measured (among other metrics) by the Regression Prevention System (RPS), i.e., running specific scenarios. To find which code segments were likely candidates for improvement, EventSources were added around a mix of code segments. Larger segments that encompass several steps within a build occur nearly every time MSBuild is run and take a long time. They generally run relatively few times. Smaller methods with well-defined purposes may occur numerous times. Profiling both types of events provides both broad strokes to identify large code segments that underperform and, more specifically, which parts of them. Profiled functions include:
+
+* MSBuildExe: Executes MSBuild from the command line.
+* Build: Sets up a BuildManager to receive build requests.
+* BuildProject: Builds a project file.
+* RequestThreadProc: A function to requesting a new builder thread.
+* LoadDocument: Loads an XMLDocumentWithLocation from a path.
+* RarRemoveReferencesMarkedForExclusion: Removes blacklisted references from the reference table, putting primary and dependency references in invalid file lists.
+* RarComputeClosure: Resolves references from, for example, properties to explicit values. Used in resolving assembly references (RAR).
+* EvaluateCondition: Checks whether a condition is true and removes false conditionals.
+* Parse: Parses an XML document into a ProjectRootElement.
+* Evaluate: Evaluates a project, running several other parts of MSBuild in the process.
+* GenerateResourceOverall: Uses resource APIs to transform resource files into strongly-typed resource classes.
+* ExpandGlob: Identifies a list of files that correspond to an item, potentially with a wildcard.
+* ApplyLazyItemOperations: Collects a set of items, mutates them in a specified way, and saves the results in a lazy way.
+* RarOverall: Initiates the process of resolving assembly references (RAR).
+* Save: Saves a project to the file system if dirty, creating directories as necessary.
+* Target: Executes a target.
+* RarLogResults: Logs the results from having resolved assembly references (RAR).
+
+One can run MSBuild with eventing using the following command:
+
+`PerfView /OnlyProviders=*Microsoft-Build run MSBuild.exe <project to build>`
+
+For example, if PerfView is one level up from my current directory (which has MSBuild.exe), and I want to build MSBuild.sln on Windows, I would use the following command:
+
+`..\PerfView /OnlyProviders=*Microsoft-Build run .\MSBuild.exe .\MSBuild.sln`

documentation/wiki/Mac-Debugging.md

@@ -0,0 +1,42 @@
+#Debugging with MacOS
+* Open terminal 
+  * Hit command-space, type terminal, hit enter. Alternatively, hit magnifying glass (spotlight) in upper-right corner and search for terminal.)
+* Build and run tests
+  * Navigation in terminal is similar to command prompt (cd), although you type `ls` in place of `dir`.
+  * **Use `./build.sh -test` instead of `.\build.cmd -test`.**
+  * If tests fail, they will appear twice in red: once when the test fails and once after all tests have run. As an example, it might say `XUnit : error : Tests failed: /Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Utilities.UnitTests_netcoreapp2.1_x64.html [netcoreapp2.1|x64] [/Users/forgind/Desktop/code/msbuild/src/Utilities.UnitTests/Microsoft.Build.Utilities.UnitTests.csproj]` near the end.
+  * Successful tests appear in white and only once like this: `Tests succeeded: /Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.CommandLine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.CommandLine.UnitTests.dll [netcoreapp2.1|x64]`
+* Choose a set of tests to analyze.
+  * From the previous example, one sample would be `Microsoft.Build.UnitTests_netcoreapp2.1_x64`, that is, the part immediately preceding `.html`.
+* Run `find . -name Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.log`
+  * Note the addition of the extension `.log` in place of `.html`.
+  * This should print out a path (from your current working directory) to the relevant log file.
+* Type `tail -n 1 <path from previous step>`
+  * This prints out the last line of that file.
+  * You can also just open it normally from a finder window.
+  * This file contains the standard output from the last run.
+  * You may notice that the line printed by this command is a single (long) command line statement.
+* Copy the command line statement from the previous step. Remove the portion after the redirection (`>` character not preceded by 2) including that character. You may notice that part redirects output to the file you’re viewing.
+  * The last part (`2>&1`) redirects standard error (using `2>`) to the same place as where standard out is going (`&1`), in this case this log file.
+  * If you would like to rerun all tests from a given class (rather than just a specific method), you can append `-class` and the class's fully qualified name. To run all tests from `TaskBuilder_Tests`, for instance, you would add `-class Microsoft.Build.UnitTests.BackEnd.TaskBuilder_Tests` and run the statement without the following steps. Note that in the example below, standard output is redirected to `/dev/null`, thus only printing the errors.
+* Prepend `./build.sh &&` to the truncated command line statement.
+* Append `-method ` and the name of the method you want to test to the end.
+  * You can find the failing method by opening the html file  (`/Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Utilities.UnitTests_netcoreapp2.1_x64.html` from the above case) in a web browser of choice. You will need to prepend `file://` if you use Safari.
+  * This will show a list of failing methods including why they failed.
+*	Running this statement will run just the one test (after building) and print out both the error and the Console.WriteLine() statements you added to the test/what it calls.
+
+
+Sample statements with outputs below and changes to the output of the second command **bolded** (note that additionally, the last two lines and one character of the second output were deleted):
+
+<pre><code>
+$ find . -name Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.log
+./artifacts/log/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.log
+
+$ tail -n 1 ./artifacts/log/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.log
+"/Users/forgind/Desktop/code/msbuild/.dotnet/dotnet" exec --depsfile "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.deps.json" --runtimeconfig "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.runtimeconfig.json"  "/Users/forgind/.nuget/packages/xunit.runner.console/2.4.1/tools/netcoreapp2.0/xunit.console.dll" "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.dll" -noautoreporters -xml "/Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.xml" -html "/Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.html" -notrait category=nonosxtests -notrait category=netcore-osx-failing -notrait category=nonnetcoreapptests -notrait category=failing > "/Users/forgind/Desktop/code/msbuild/artifacts/log/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.log" 2>&1
+
+$ "/Users/forgind/Desktop/code/msbuild/.dotnet/dotnet" exec --depsfile "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.deps.json" --runtimeconfig "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.runtimeconfig.json"  "/Users/forgind/.nuget/packages/xunit.runner.console/2.4.1/tools/netcoreapp2.0/xunit.console.dll" "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.dll" -noautoreporters -xml "/Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.xml" -html "/Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.html" -notrait category=nonosxtests -notrait category=netcore-osx-failing -notrait category=nonnetcoreapptests -notrait category=failing -class Microsoft.Build.UnitTests.BackEnd.TaskBuilder_Tests > /dev/null
+Microsoft.Build.UnitTests.BackEnd.TaskBuilder_Tests.NullMetadataOnLegacyOutputItems [FAIL]
+
+$ <b>./build.sh &&</b> "/Users/forgind/Desktop/code/msbuild/.dotnet/dotnet" exec --depsfile "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.deps.json" --runtimeconfig "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.runtimeconfig.json"  "/Users/forgind/.nuget/packages/xunit.runner.console/2.4.1/tools/netcoreapp2.0/xunit.console.dll" "/Users/forgind/Desktop/code/msbuild/artifacts/bin/Microsoft.Build.Engine.UnitTests/Debug/netcoreapp2.1/Microsoft.Build.Engine.UnitTests.dll" -noautoreporters -xml "/Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.xml" -html "/Users/forgind/Desktop/code/msbuild/artifacts/TestResults/Debug/Microsoft.Build.Engine.UnitTests_netcoreapp2.1_x64.html" -notrait category=nonosxtests -notrait category=netcore-osx-failing -notrait category=nonnetcoreapptests -notrait category=failing <b>-method Microsoft.Build.UnitTests.BackEnd.TaskBuilder_Tests.NullMetadataOnLegacyOutputItems</b>
+</code></pre>

eng/Packages.props

@@ -1,9 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
 <Project>
 
   <PropertyGroup>
       <MicrosoftNetCompilersVersion>3.4.0-beta3-19521-01</MicrosoftNetCompilersVersion>
       <CompilerToolsVersion>$(MicrosoftNetCompilersVersion)</CompilerToolsVersion>
-      <NuGetPackageVersion>5.3.0-rtm.6251</NuGetPackageVersion>
+      <NuGetPackageVersion>5.4.0-preview.3.6271</NuGetPackageVersion>
       <NuGetBuildTasksVersion Condition="'$(NuGetBuildTasksVersion)' == ''">$(NuGetPackageVersion)</NuGetBuildTasksVersion>
       <NuGetCommandsVersion Condition="'$(NuGetCommandsVersion)' == ''">$(NuGetPackageVersion)</NuGetCommandsVersion>
       <NuGetProtocolVersion Condition="'$(NuGetProtocolVersion)' == ''">$(NuGetPackageVersion)</NuGetProtocolVersion>
@@ -50,7 +51,7 @@
   </ItemGroup>
 
   <ItemGroup Condition="'$(DotNetBuildFromSource)' != 'true'">
-    <GlobalPackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.0-alpha-004" PrivateAssets="All"/>
+    <GlobalPackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.0-alpha-004" PrivateAssets="All" />
   </ItemGroup>
 
   <ItemGroup>

eng/Version.Details.xml

@@ -7,17 +7,17 @@
     </Dependency>
   </ToolsetDependencies>
   <ProductDependencies>
-    <Dependency Name="Microsoft.NET.Sdk" Version="3.1.100-preview1.19506.1">
+    <Dependency Name="Microsoft.NET.Sdk" Version="3.1.100-preview2.19528.2">
       <Uri>https://github.com/dotnet/sdk</Uri>
-      <Sha>357126710492d620198a60ee340ebeca9070f133</Sha>
+      <Sha>334812443d8bb11afa51a7efd2f8de83e321e6e1</Sha>
     </Dependency>
-    <Dependency Name="Microsoft.NET.Sdk.Razor" Version="3.1.0-preview2.19518.7">
+    <Dependency Name="Microsoft.NET.Sdk.Razor" Version="3.1.0-preview2.19528.1">
       <Uri>https://github.com/aspnet/AspNetCore-Tooling</Uri>
-      <Sha>c034007a2d17e04decd619d875307392656ae94f</Sha>
+      <Sha>d273a0f4ccfd17a50b490492929bb3617ca73c32</Sha>
     </Dependency>
-    <Dependency Name="Microsoft.NET.Sdk.Web" Version="3.1.100-preview2.19521.2">
+    <Dependency Name="Microsoft.NET.Sdk.Web" Version="3.1.100-preview2.19529.1">
       <Uri>https://github.com/aspnet/websdk</Uri>
-      <Sha>b79adac75df36d7e1adcacb43e09cea24b765aca</Sha>
+      <Sha>982cc536ce2b3560a13ba87c7406514fd16b825d</Sha>
     </Dependency>
     <Dependency Name="ILLink.Tasks" Version="0.1.6-prerelease.19380.1">
       <Uri>https://github.com/mono/linker</Uri>
@@ -27,13 +27,13 @@
       <Uri>https://github.com/dotnet/core-setup</Uri>
       <Sha>f830769364b45286b638a57176d4a7997dbc5237</Sha>
     </Dependency>
-    <Dependency Name="Microsoft.DotNet.Cli.Runtime" Version="3.1.100-preview2.19521.2">
+    <Dependency Name="Microsoft.DotNet.Cli.Runtime" Version="3.1.100-preview2.19529.1">
       <Uri>https://github.com/dotnet/cli</Uri>
-      <Sha>08f2a44fd1a2ca4363b656c730123370f4f91942</Sha>
+      <Sha>23212e12c98ce4af8f07922c9ef6a20b23f236ea</Sha>
     </Dependency>
-    <Dependency Name="NuGet.Build.Tasks" Version="5.3.0-rtm.6251">
+    <Dependency Name="NuGet.Build.Tasks" Version="5.4.0-preview.3.6271">
       <Uri>https://github.com/NuGet/NuGet.Client</Uri>
-      <Sha>b75150f2f4127a77a166c9552845e86fb24a3282</Sha>
+      <Sha>c1f6915918b82c096bbd666bd9c18528f1f70630</Sha>
     </Dependency>
   </ProductDependencies>
 </Dependencies>

eng/Versions.props

@@ -35,13 +35,13 @@
   <PropertyGroup>
     <DotNetCliVersion>3.0.100</DotNetCliVersion>
     <MicrosoftNetCompilersVersion>3.4.0-beta3-19521-01</MicrosoftNetCompilersVersion>
-    <MicrosoftNETSdkVersion>3.1.100-preview1.19506.1</MicrosoftNETSdkVersion>
-    <MicrosoftNETSdkRazorVersion>3.1.0-preview2.19518.7</MicrosoftNETSdkRazorVersion>
-    <MicrosoftNETSdkWebVersion>3.1.100-preview2.19521.2</MicrosoftNETSdkWebVersion>
-    <NuGetBuildTasksVersion>5.3.0-rtm.6251</NuGetBuildTasksVersion>
+    <MicrosoftNETSdkVersion>3.1.100-preview2.19528.2</MicrosoftNETSdkVersion>
+    <MicrosoftNETSdkRazorVersion>3.1.0-preview2.19528.1</MicrosoftNETSdkRazorVersion>
+    <MicrosoftNETSdkWebVersion>3.1.100-preview2.19529.1</MicrosoftNETSdkWebVersion>
+    <NuGetBuildTasksVersion>5.4.0-preview.3.6271</NuGetBuildTasksVersion>
     <ILLinkTasksVersion>0.1.6-prerelease.19380.1</ILLinkTasksVersion>
     <MicrosoftNETCoreAppVersion>3.1.0-preview2.19521.15</MicrosoftNETCoreAppVersion>
-    <MicrosoftDotNetCliRuntimeVersion>3.1.100-preview2.19521.2</MicrosoftDotNetCliRuntimeVersion>
+    <MicrosoftDotNetCliRuntimeVersion>3.1.100-preview2.19529.1</MicrosoftDotNetCliRuntimeVersion>
   </PropertyGroup>
   <Target Name="OverrideArcadeFileVersion" AfterTargets="_InitializeAssemblyVersion">
     <!-- See https://github.com/dotnet/arcade/issues/3386