From a1ff4a711a076b1651ae75f1359b91d96bb04c68 Mon Sep 17 00:00:00 2001
From: Nate McMaster <nate.mcmaster@microsoft.com>
Date: Tue, 1 May 2018 11:10:07 -0700
Subject: [PATCH] Add documentation and comments to explain what
 Microsoft.DotNet.GlobalTools.Sdk is used for

---
 modules/BundledPackages/BundledPackages.proj  |  5 +++
 modules/BundledPackages/module.targets        |  4 ++
 .../Microsoft.DotNet.GlobalTools.Sdk.nuspec   |  1 +
 .../README.md                                 | 43 +++++++++++++++++++
 4 files changed, 53 insertions(+)
 create mode 100644 src/Microsoft.DotNet.GlobalTools.Sdk/README.md

diff --git a/modules/BundledPackages/BundledPackages.proj b/modules/BundledPackages/BundledPackages.proj
index 03c59af93..5b04bc598 100644
--- a/modules/BundledPackages/BundledPackages.proj
+++ b/modules/BundledPackages/BundledPackages.proj
@@ -15,6 +15,11 @@
       RemoveProperties="PublishDir" />
 
     <PropertyGroup>
+      <!--
+        This is a workaround for https://github.com/Microsoft/msbuild/issues/2914.
+        Currently, the only way to configure the NuGetSdkResolver is with NuGet.config, which is not generally used in aspnet org projects.
+        This project is restored so that it pre-populates the NuGet cache with SDK packages.
+      -->
       <BundledPackageRestorerContent>
 <![CDATA[
 <Project Sdk="Microsoft.NET.Sdk">
diff --git a/modules/BundledPackages/module.targets b/modules/BundledPackages/module.targets
index 2a5d7754b..1a00e8cf6 100644
--- a/modules/BundledPackages/module.targets
+++ b/modules/BundledPackages/module.targets
@@ -3,6 +3,10 @@
     <PrepareDependsOn>PreinstallBundledPackages;$(PrepareDependsOn)</PrepareDependsOn>
   </PropertyGroup>
 
+  <!--
+    This is a workaround for https://github.com/Microsoft/msbuild/issues/2914.
+    This pre-populates the NuGet cache with bundled packages.
+  -->
   <Target Name="PreinstallBundledPackages">
     <MSBuild Targets="Restore"
       Projects="$(MSBuildThisFileDirectory)BundledPackageRestorer.csproj"
diff --git a/src/Microsoft.DotNet.GlobalTools.Sdk/Microsoft.DotNet.GlobalTools.Sdk.nuspec b/src/Microsoft.DotNet.GlobalTools.Sdk/Microsoft.DotNet.GlobalTools.Sdk.nuspec
index 3b10aa7d6..ed9dcdc83 100644
--- a/src/Microsoft.DotNet.GlobalTools.Sdk/Microsoft.DotNet.GlobalTools.Sdk.nuspec
+++ b/src/Microsoft.DotNet.GlobalTools.Sdk/Microsoft.DotNet.GlobalTools.Sdk.nuspec
@@ -8,6 +8,7 @@
     <description>Provides additional support to .NET Core teams producing global CLI tools. This package is only intended for internal Microsoft use.</description>
     <copyright>$copyright$</copyright>
     <packageTypes>
+      <!-- This project needs to be MSBuildSdk because its targets need to influence the way /t:Restore works -->
       <packageType name="MSBuildSdk" />
     </packageTypes>
   </metadata>
diff --git a/src/Microsoft.DotNet.GlobalTools.Sdk/README.md b/src/Microsoft.DotNet.GlobalTools.Sdk/README.md
new file mode 100644
index 000000000..354368374
--- /dev/null
+++ b/src/Microsoft.DotNet.GlobalTools.Sdk/README.md
@@ -0,0 +1,43 @@
+Microsoft.DotNet.GlobalTools.Sdk
+================================
+
+Provides additional support to .NET Core teams producing global CLI tools. This package is only intended for internal Microsoft use.
+
+## Usage
+Projects that need to bundle and sign the global CLI tool shim should add this to their .csproj file. This will include files in the .nupkg.
+
+```xml
+<!-- In MyTool.csproj -->
+<Project>
+  <Sdk Name="Microsoft.NET.Sdk" />
+  <Sdk Name="Microsoft.DotNet.GlobalTools.Sdk" />
+
+  <PropertyGroup>
+    <PackAsTool>true</PackAsTool>
+    <GenerateToolShims>true</GenerateToolShims>
+  </PropertyGroup>
+</Project>
+```
+
+```js
+// in global.json
+{
+    "msbuild-sdks": {
+        "Microsoft.DotNet.GlobalTools.Sdk": "2.1.0-rtm-12345"
+    }
+}
+```
+
+### Additional options
+
+#### `GenerateToolShims` (property)
+
+A boolean flag. When `true`, tool shims will be generated for each RID listed in `GeneratedShimRuntimeIdentifiers` and included in the .nupkg.
+
+Default value = `false`
+
+#### `GeneratedShimRuntimeIdentifiers` (property)
+
+A semi-colon separate list of RIDs for which to generate and pack the shim.
+
+Default value = `win-x86;win-x64;osx-x64`