From d5a974ffd4ac1b1c64dc029fa0446322bffa1092 Mon Sep 17 00:00:00 2001
From: Dan Travison <dantraMSFT@users.noreply.github.com>
Date: Mon, 13 Nov 2017 10:40:31 -0800
Subject: [PATCH] Add dependency nuget instructions for
 PowerShell.Core.Instrumentation resource binary (#5396)

* Add dependency nuget packaging instructions for PowerShell.Core.Instrumentation ETW resource binary.

* Fix markdown MD031 Fenced code blocks errors.

* Fix MD022 Headers should be surrounded by blank lines

* Add a note about Authenticode Dual-signing requirement.

* PR Feedback.

* Set version to Beta.10
---
 .spelling                                     |  2 +
 docs/building/internals.md                    | 63 +++++++++++++++++++
 .../PowerShell.Core.Instrumentation.nuspec    | 12 ++++
 .../System.Management.Automation.csproj       |  1 +
 4 files changed, 78 insertions(+)
 create mode 100644 src/PowerShell.Core.Instrumentation/PowerShell.Core.Instrumentation.nuspec

diff --git a/.spelling b/.spelling
index 3207ea808f..e5c598f498 100644
--- a/.spelling
+++ b/.spelling
@@ -25,6 +25,7 @@ artifact
 artifacts
 ASP.NET
 AssemblyLoadContext
+authenticode
 authenticodesignature
 behavior
 behaviors
@@ -135,6 +136,7 @@ parameterized
 patwardhan
 powershell
 PowerShell
+PowerShell.Core.Instrumentation
 powershell.exe
 PowerShellGet
 program.cs
diff --git a/docs/building/internals.md b/docs/building/internals.md
index 5c4fea938d..8fdf0fd733 100644
--- a/docs/building/internals.md
+++ b/docs/building/internals.md
@@ -197,3 +197,66 @@ The layout of files should look like this:
 ```
 
 Lastly, run `nuget pack .` from within the folder. Note that you may need the latest `nuget.exe`.
+
+### PowerShell.Core.Instrumentation
+
+To successfully decode PowerShell Core ETW events, the manifest and resource binary need to be registered on the system.
+
+To create a new NuGet package for `PowerShell.Core.Instrumentation.dll`, you will need the `PowerShell.Core.Instrumentation.nuspec` found in the repo under `src\PowerShell.Core.Instrumentation`.
+
+Update the version information for the package.
+
+```none
+<version>6.0.0-RC</version>
+```
+
+Next, create the directory structure needed for the contents of the nuget package structure. The final directory and file layout is listed below.
+
+```powershell
+if (Test-Path -Path c:\mypackage)
+{
+  Remove-Item -Recurse -Force -Path c:\mypackage
+}
+$null = New-Item -Path c:\mypackage\runtimes\win-x64\native -ItemType Directory
+$null = New-Item -Path c:\mypackage\runtimes\win-x86\native -ItemType Directory
+```
+
+You will need to build `PowerShell.Core.Instrumentation.dll` targeting both `win-x64` and `win-x86` on Windows 10.
+The output files will be placed under src\powershell-win-core.
+
+Build the `win-x64` platform and copy the `PowerShell.Core.Instrumentation.dll` to the win-x86 portion of the tree.
+
+```powershell
+## Build targeting win-x64
+Start-BuildNativeWindowsBinaries -Configuration Release -Arch x64
+Copy-Item -Path .\src\powershell-win-core\PowerShell.Core.Instrumentation.dll -Destination c:\mypackage\runtimes\win-x64\native
+```
+
+Next, build the `win-x86` platform and copy `PowerShell.Core.Instrumentation.dll` to the win-x86 portion of the tree.
+
+```powershell
+## Build targeting win-x86
+Start-BuildNativeWindowsBinaries -Configuration Release -Arch x86
+Copy-Item -Path .\src\powershell-win-core\PowerShell.Core.Instrumentation.dll -Destination c:\mypackage\runtimes\win-x86\native
+```
+
+The layout of files looks like this:
+
+```none
+└── runtimes
+    ├── win-x64
+    │   └── native
+    │       └── PowerShell.Core.Instrumentation.dll
+    │
+    ├── win-x86
+    │   └── native
+    │       └── PowerShell.Core.Instrumentation.dll
+```
+
+NOTE: Since these are native binaries used on Windows, they need to be `authenticode dual signed` before creating the nuget package.
+
+Lastly, run the following command from the root of the repo to create the nuget package. The nuget package is placed at `.\src\powershell-win-core`.  Note that you may need the latest `nuget.exe`.
+
+```powershell
+nuget pack .\src\PowerShell.Core.Instrumentation\PowerShell.Core.Instrumentation.nuspec -BasePath c:\mypackage -OutputDirectory .\src\powershell-win-core
+```
diff --git a/src/PowerShell.Core.Instrumentation/PowerShell.Core.Instrumentation.nuspec b/src/PowerShell.Core.Instrumentation/PowerShell.Core.Instrumentation.nuspec
new file mode 100644
index 0000000000..3d27acf63b
--- /dev/null
+++ b/src/PowerShell.Core.Instrumentation/PowerShell.Core.Instrumentation.nuspec
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
+  <metadata>
+    <id>PowerShell.Core.Instrumentation</id>
+    <version>6.0.0-beta.10</version>
+    <authors>Microsoft</authors>
+    <owners>Microsoft</owners>
+    <requireLicenseAcceptance>false</requireLicenseAcceptance>
+    <description>PowerShell Core ETW resource binary</description>
+    <copyright>(c) Microsoft Corporation. All rights reserved.</copyright>
+  </metadata>
+</package>
diff --git a/src/System.Management.Automation/System.Management.Automation.csproj b/src/System.Management.Automation/System.Management.Automation.csproj
index 98cc8af08f..67fc45727c 100644
--- a/src/System.Management.Automation/System.Management.Automation.csproj
+++ b/src/System.Management.Automation/System.Management.Automation.csproj
@@ -16,6 +16,7 @@
     <PackageReference Include="System.Security.Permissions" Version="4.4.0" />
     <PackageReference Include="System.Text.Encoding.CodePages" Version="4.4.0" />
     <PackageReference Include="Microsoft.Management.Infrastructure" Version="1.0.0-alpha*" />
+    <PackageReference Include="PowerShell.Core.Instrumentation" Version="6.0.0-beta*" />
   </ItemGroup>
 
   <PropertyGroup>