Skip to content

Add dependency nuget instructions for PowerShell.Core.Instrumentation resource binary #5396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adityapatwardhan merged 9 commits into from
Nov 13, 2017
Merged

Add dependency nuget instructions for PowerShell.Core.Instrumentation resource binary #5396

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c90eaf5
Add dependency nuget packaging instructions for PowerShell.Core.Instr…
dantraMSFT Nov 9, 2017
74bdbb3
Fix markdown MD031 Fenced code blocks errors.
dantraMSFT Nov 9, 2017
8902527
Fix MD022 Headers should be surrounded by blank lines
dantraMSFT Nov 9, 2017
da71450
Add a note about Authenticode Dual-signing requirement.
dantraMSFT Nov 9, 2017
ed2c484
PR Feedback.
dantraMSFT Nov 10, 2017
f60a430
Fix grammar
dantraMSFT Nov 10, 2017
8b150a5
Update copyrigth value
dantraMSFT Nov 10, 2017
51f99f7
Set version to Beta.10
dantraMSFT Nov 11, 2017
ed7fad9
Fix spelling in the document and update .spelling file.
dantraMSFT Nov 12, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .spelling
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ artifact
artifacts
ASP.NET
AssemblyLoadContext
authenticode
authenticodesignature
behavior
behaviors
Expand Down Expand Up @@ -135,6 +136,7 @@ parameterized
patwardhan
powershell
PowerShell
PowerShell.Core.Instrumentation
powershell.exe
PowerShellGet
program.cs
Expand Down
63 changes: 63 additions & 0 deletions docs/building/internals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
12 changes: 12 additions & 0 deletions src/PowerShell.Core.Instrumentation/PowerShell.Core.Instrumentation.nuspec
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
1 change: 1 addition & 0 deletions src/System.Management.Automation/System.Management.Automation.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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*" />
Copy link
Member

@daxian-dbw daxian-dbw Nov 9, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it depended by System.Management.Automation.dll or powershell as a whole? Put it another way, if an application is hosting System.Management.Automation.dll only, does it need the resource dll to work properly?

Copy link
Contributor Author

@dantraMSFT dantraMSFT Nov 10, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

None of the code has a direct dependency on the binary. I chose SMA to pull the nuget package since it contains the event raising code. If the dll is not present or the manifest isn't registered, PowerShell will continue to work without issue but the event log and custom consumers won't be able to decode the events.

Copy link
Member

@daxian-dbw daxian-dbw Nov 10, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification. #Close

</ItemGroup>

<PropertyGroup>
Expand Down