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

@@ -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

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
+```

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>

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>