Adding new build/packaging documentation (#13026)

* Adding new APIs not part of NetStandard
* Adding package debugging.

2 files changed, 193 insertions, 0 deletions

diff --git a/Documentation/coding-guidelines/package-projects.md b/Documentation/coding-guidelines/package-projects.md
index 5319dd3723..5fb0c8806a 100644
--- a/Documentation/coding-guidelines/package-projects.md
+++ b/Documentation/coding-guidelines/package-projects.md
@@ -60,6 +60,92 @@ Sample `System.Collections.Concurrent.pkgproj`
 ### Framework-specific library
 Framework specific libraries are effectively the same as the previous example.  The difference is that the src project reference **must** refer to the `.builds` file which will provide multiple assets from multiple projects.
 
+Sample System.Net.Security.pkgproj
+```
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.props))\dir.props" />
+  <ItemGroup>
+    <ProjectReference Include="..\ref\System.Net.Security.builds">
+      <SupportedFramework>net463;netcoreapp1.1;$(AllXamarinFrameworks)</SupportedFramework>
+    </ProjectReference>
+    <ProjectReference Include="..\src\System.Net.Security.builds" />
+  </ItemGroup>
+  <ItemGroup>
+    <InboxOnTargetFramework Include="MonoAndroid10" />
+    <InboxOnTargetFramework Include="MonoTouch10" />
+    <InboxOnTargetFramework Include="xamarinios10" />
+    <InboxOnTargetFramework Include="xamarinmac20" />
+    <InboxOnTargetFramework Include="xamarintvos10" />
+    <InboxOnTargetFramework Include="xamarinwatchos10" />
+
+    <NotSupportedOnTargetFramework Include="netcore50">
+      <PackageTargetRuntime>win7</PackageTargetRuntime>
+    </NotSupportedOnTargetFramework>
+  </ItemGroup>
+  <ItemGroup>
+  </ItemGroup>
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.targets))\dir.targets" />
+</Project>
+```
+
+Sample \ref .builds file defining a constant used to filter API that were added on top of the netstandard1.7 ones and are available only in netcoreapp1.1: 
+
+```
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.props))\dir.props" />
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <NuGetTargetMoniker>.NETStandard,Version=v1.7</NuGetTargetMoniker>
+    <DefineConstants Condition="'$(TargetGroup)' == 'netcoreapp1.1'">$(DefineConstants);netcoreapp11</DefineConstants>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="System.Net.Security.cs" />
+    <Compile Include="System.Net.Security.Manual.cs" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Include="project.json" />
+  </ItemGroup>
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.targets))\dir.targets" />
+</Project>
+```
+
+Conditional compilation using the above-mentioned constant (from `ref\System.Net.Security.cs`):
+
+```
+#if netcoreapp11
+        public virtual void AuthenticateAsClient(string targetHost, System.Security.Cryptography.X509Certificates.X509CertificateCollection clientCertificates, bool checkCertificateRevocation) { }
+#endif
+```
+
+Sample \src .builds file (in this case the implementation is the same in both netcoreapp1.1 and netstandard1.7):
+
+```
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.props))\dir.props" />
+  <ItemGroup>
+    <Project Include="System.Net.Security.csproj">
+      <OSGroup>Unix</OSGroup>
+    </Project>
+    <Project Include="System.Net.Security.csproj">
+      <OSGroup>Windows_NT</OSGroup>
+    </Project>
+    <Project Include="System.Net.Security.csproj">
+      <TargetGroup>net463</TargetGroup>
+    </Project>
+  </ItemGroup>
+  <Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.traversal.targets))\dir.traversal.targets" />
+</Project>
+```
+
+Tests can be similarly filtered grouping the compilation directives under:
+```
+  <ItemGroup Condition="'$(TargetGroup)'=='netcoreapp1.1'">
+```
+(from `\tests\FunctionalTests\System.Net.Security.Tests.csproj`)
+
 ### Platform-specific library
 These packages need to provide a different platform specific implementation on each platform.  They do this by splitting the implementations into seperate packages and associating those platform specific packages with the primary reference package.  Each platform specific package sets `PackageTargetRuntime` to the specific platform RID that it applies.
 
diff --git a/Documentation/debugging/debugging-packages.md b/Documentation/debugging/debugging-packages.md
new file mode 100644
index 0000000000..1fd0d38aa1
--- /dev/null
+++ b/Documentation/debugging/debugging-packages.md
@@ -0,0 +1,107 @@
+Debugging CoreFX build issues
+========================================
+
+## MSBuild debug options
+
+* Enable MSBuild diagnostics log (msbuild.log):
+`msbuild my.csproj /flp:v=diag /t:rebuild`
+* Generate a flat project file (out.pp):
+`msbuild my.csproj /pp:out.pp`
+
+## Steps to debug packaging build issues
+
+(This documentation is work in progress.)
+
+I found the following process to help when investigating some of the build issues caused by incorrect packaging. 
+
+In general, always build the .builds file instead of any of the csproj to ensure that all [Build Pivots](../coding-guidelines/project-guidelines.md#build-pivots) are generated. This applies for running tests as well. For more information, see [Build individual CoreFX DLLs](../project-docs/developer-guide.md#building-individual-corefx-dlls) 
+
+Assuming the current directory is `\src\contractname\`:
+
+1. Build the `\ref` folder: `msbuild /t:rebuild contractname.builds` 
+
+
+Check the logs for output such as:
+```
+Project "S:\c1\src\System.Net.ServicePoint\ref\System.Net.ServicePoint.builds" (1) is building "S:\c1\src\System.Net.ServicePoint\ref\System.Net.ServicePoint.csproj" (2:3) on node 1
+(Build target(s)).
+
+[...]
+
+CopyFilesToOutputDirectory:
+  Copying file from "S:\c1\bin/obj/ref/System.Net.ServicePoint/4.0.0.0/System.Net.ServicePoint.dll" to "S:\c1\bin/ref/System.Net.ServicePoint/4.0.0.0/System.Net.ServicePoint.dll".
+  System.Net.ServicePoint -> S:\c1\bin\ref\System.Net.ServicePoint\4.0.0.0\System.Net.ServicePoint.dll
+  Copying file from "S:\c1\bin/obj/ref/System.Net.ServicePoint/4.0.0.0/System.Net.ServicePoint.pdb" to "S:\c1\bin/ref/System.Net.ServicePoint/4.0.0.0/System.Net.ServicePoint.pdb".
+
+[...]
+
+Project "S:\c1\src\System.Net.ServicePoint\ref\System.Net.ServicePoint.builds" (1) is building "S:\c1\src\System.Net.ServicePoint\ref\System.Net.ServicePoint.csproj" (2:4) on node 1
+(Build target(s)).
+
+[...]
+
+CopyFilesToOutputDirectory:
+  Copying file from "S:\c1\bin/obj/ref/System.Net.ServicePoint/4.0.0.0/netcoreapp1.1/System.Net.ServicePoint.dll" to "S:\c1\bin/ref/System.Net.ServicePoint/4.0.0.0/netcoreapp1.1/System.Net.ServicePoint.dll".
+  System.Net.ServicePoint -> S:\c1\bin\ref\System.Net.ServicePoint\4.0.0.0\netcoreapp1.1\System.Net.ServicePoint.dll
+  Copying file from "S:\c1\bin/obj/ref/System.Net.ServicePoint/4.0.0.0/netcoreapp1.1/System.Net.ServicePoint.pdb" to "S:\c1\bin/ref/System.Net.ServicePoint/4.0.0.0/netcoreapp1.1/System.Net.ServicePoint.pdb".
+```
+
+Using your favourite IL disassembler, ensure that each platform contains the correct APIs. Missing APIs from the contracts is likely caused by not having the right `DefineConstants` tags in the csproj files.
+
+2. Build the `\src` folder: `msbuild /t:rebuild contractname.builds`
+
+Use the same technique above to ensure that the binaries include the correct implementations.
+
+3. Build the `\pkg` folder: `msbuild /t:rebuild contractname.builds`
+
+Ensure that all Build Pivots are actually being built. This should build all .\ref and .\src variations as well as actually creating the NuGet packages.
+
+Verify that the contents of the nuspec as well as the actual package is correct. You can find the packages by searching for the following pattern in the msbuild output: 
+
+```
+GetPkgProjPackageDependencies:
+Skipping target "GetPkgProjPackageDependencies" because it has no inputs.
+CreatePackage:
+  Created 'S:\c1\bin/packages/Debug/System.Net.Security.4.4.0-beta-24625-0.nupkg'
+  Created 'S:\c1\bin/packages/Debug/symbols/System.Net.Security.4.4.0-beta-24625-0.symbols.nupkg'
+Build:
+  System.Net.Security -> S:\c1\bin/packages/Debug/specs/System.Net.Security.nuspec
+```
+
+To validate the content of the nupkg, change the extension to .zip. As before, use an IL disassembler to verify that the right APIs are present within `ref\<platform>\contractname.dll` and the right implementations within the `lib\<platform>\contractname.dll`.
+
+4. Run the tests from `\tests`: `msbuild /t:rebuild,test contractname.Tests.builds`
+
+Ensure that the test is referencing the correct pkg. For example:
+```
+  <ItemGroup>
+    <ProjectReference Include="..\pkg\System.Net.ServicePoint.pkgproj">
+      <Name>System.Net.ServicePoint</Name>
+      <Project>{53D09AF4-0C13-4197-B8AD-9746F0374E88}</Project>
+    </ProjectReference>
+  </ItemGroup>
+```
+
+Ensure that the right `TargetGroup` (what we're testing) and `TestTFM` (the Target Framework of the test code) are correctly set in the .builds file.
+
+To identify which of the combinations failed, search for the following pattern in the output:
+
+```
+Project "S:\c1\src\System.Net.ServicePoint\tests\System.Net.ServicePoint.Tests.builds" (1) is building "S:\c1\src\System.Net.ServicePoint\tests\System.Net.ServicePoint.Tests.csproj"
+(2:5) on node 1 (Build target(s)).
+ResolvePkgProjReferences:
+  Resolved compile assets from .NETStandard,Version=v1.7: S:\c1\bin\ref\System.Net.ServicePoint\4.0.0.0\System.Net.ServicePoint.dll
+  Resolved runtime assets from .NETCoreApp,Version=v1.1: S:\c1\bin\AnyOS.AnyCPU.Debug\System.Net.ServicePoint\System.Net.ServicePoint.dll
+```
+
+To run a test from a single Build Pivot combination, specify all properties and build the `csproj` instead of the `builds` file:
+
+```
+msbuild /t:rebuild,test /p:Outerloop=true "/p:XunitOptions=-showprogress" /p:Configuration=Windows_Debug /p:TargetGroup=netstandard1.7 /p:TestTFM=netcoreapp1.1 .\System.Net.ServicePoint.Tests.csproj
+```
+Will run the test using the following pivot values:
+* Architecture: AnyCPU
+* Flavor: Debug
+* OS: Windows_NT
+* Platform Runtime: netcoreapp1.1
+* Target: netstandard1.7