Add documentation about hosting PowerShell Core #3409

daxian-dbw · 2017-03-24T01:07:19Z

Fix #2291
Add documentation about how to host PowerShell Core in .NET Core application.

daviwil · 2017-03-24T02:59:29Z

This is really cool!

Quick question: does this tie the application to a specific version of PowerShell Core? Specifically, if I build against Microsoft.PowerShell.SDK of a specific version, is there any way I could get my application to load assemblies from a newer version of PowerShell Core if I have its filesystem path?

I'm asking because I'm re-evaluating whether I could make PowerShell Editor Services a standalone process again, not a module running inside of powershell.exe.

daxian-dbw · 2017-03-24T05:11:09Z

@daviwil When you build your application this way, a specific version (depending on the package version you use) of PowerShell Core assemblies will be published to your publish folder. But your application is not necessarily tied to them. You can just replace them with a newer version of PS Core assemblies, and your application should continue to work as long as the new PS Core assemblies are targeting the same set of .NET Core packages.

There is one problem, though -- we haven't published any powershell core packages for Linux/OSX yet.
PowerShell Core builds separately for Windows and Unix, so the assemblies are different between Windows and Unix platforms. All PowerShell Core packages we published so far contain windows assemblies only ☹️.

There is a workaround. Build your application using the existing powershell core NuGet packages, but replace the powershell assemblies with those from a Linux/OSX package. That hopefully would work.

iSazonov · 2017-03-24T06:40:11Z

docs/host-powershell/sample-dotnet1.1/Logic/Logic.csproj

+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>netstandard1.6</TargetFramework>


Please clarify why "netstandard1.6", not "netcoreapp1.1" as in docs/host-powershell/sample-dotnet1.1/MyApp/MyApp.csproj ?

Becuase Logic.dll is an assembly Library while MyApp.exe is an executable. If you inspect the dependencies of Microsoft.NetCore.App, you will see that it depends on NetStandard.Library and also include the runtime and host related packages.

mirichmo · 2017-03-24T01:10:44Z

docs/host-powershell/README.md

+### Overview
+
+Due to the lack of necessary APIs for manipulating assemblies in .NET Core 1.1 and prior,
+PowerShell Core needs to control assembly loading via our customized `AssemblyLoadContext` in order to do tasks like type resolution.


Maybe add a link to the file here?

mirichmo · 2017-03-24T15:33:18Z

docs/host-powershell/README.md

+`SetPowerShellAssemblyLoadContext` and `InitializeAndCallEntryMethod`.
+They are for different scenarios:
+
+- For `SetPowerShellAssemblyLoadContext`,


I'd like to see the topic set apart from the rest of the sentence to make it a little more obvious that it is the topic of the bullet point. Something like:

SetPowerShellAssemblyLoadContext - It is designed to ...

mirichmo · 2017-03-24T15:33:59Z

docs/host-powershell/README.md

+They are for different scenarios:
+
+- For `SetPowerShellAssemblyLoadContext`,
+it's designed to be used by a native host whose TPA (Trusted Platform Assemblies) list doesn't include powershell assemblies,


TPA should be in parenthesis and follow --> Trusted Platform Assemblies (TPA)

mirichmo · 2017-03-24T15:35:31Z

docs/host-powershell/README.md

+When using this API, `PowerShellAssemblyLoadContextInitializer` will set up a new load context to handle all assemblies.
+PowerShell Core itself also uses this API for [bootstrapping][].
+
+This documentation only covers the `InitializeAndCallEntryMethod` API,


Links to additional background information would be helpful as well. Did the .Net team write up any documentation on consuming these two APIs?

We own those 2 APIs. They are exposed from PowerShellAssemblyLoadContextInitializer.

mirichmo · 2017-03-24T15:38:35Z

docs/host-powershell/README.md

+
+### Example
+
+The following code is how you host Windows PowerShell in an application.  


Suggested rewording:
This example demonstrates how to host Windows PowerShell in an application. Business logic should be inserted within the Main method.

Another thought: What about linking to the MSDN documentation for this? It is a supported scenario for Windows PowerShell.

I don't intend to introduce how to host Windows PowerShell in full .NET application.
The code about hosting Windows PowerShell is used as a comparison to show what you need to do in .NET Core for the same purpose.

But I reworded it as you suggested.

mirichmo · 2017-03-24T16:01:06Z

docs/host-powershell/README.md

+The entry point `'Main'` method shall do one thing only -- let the powershell load context load `'Logic.dll'` and start the execution of the business logic.
+Once the execution starts this way, all further assembly loading requests will be handled by the powershell load context.
+
+So the above example needs to be altered as follows in a .NET Core application:


Suggested rewording:
The following example demonstrates hosting PowerShell Core in a .Net Core Application:

Same here. The code about hosting windows powershell is used as a comparison to show how this familiar code should be altered when it comes to .NET Core 1.1.

mirichmo · 2017-03-24T16:04:27Z

docs/host-powershell/README.md

+This documentation only covers the `InitializeAndCallEntryMethod` API,
+as it's what you need when building a .NET Core application with .NET CLI.
+
+### Example


There should be three sub-headings here:

Hosting Windows PowerShell

Hosting PowerShell in .Net Core

Example .Net Core program

daviwil · 2017-03-24T16:18:21Z

@daxian-dbw thanks for the explanation! Seems like it would be more complex go have my own process hosting PowerShell so I think I'll stick with my current model of being hosted inside of powershell.exe :)

daxian-dbw · 2017-03-24T18:11:00Z

@mirichmo I addressed your comments. Could you please take another look?

joeyaiello

Just a few small changes, otherwise looks really useful to me.

joeyaiello · 2017-03-24T22:05:04Z

docs/host-powershell/README.md

+They are for different scenarios:
+
+- `SetPowerShellAssemblyLoadContext` - It's designed to be used by a native host
+whose Trusted Platform Assemblies (TPA) do not include powershell assemblies,


Properly case "PowerShell"

joeyaiello · 2017-03-24T22:24:03Z

docs/host-powershell/README.md

+Then PowerShell Core will depend on the default load context to handle TPA and the `Resolving` event to handle other assemblies.
+
+- `InitializeAndCallEntryMethod` - It's designed to be used with `dotnet.exe`
+where the TPA list includes powershell assemblies.


Properly case "PowerShell"

joeyaiello · 2017-03-24T22:24:41Z

docs/host-powershell/README.md

+### Comparison - Hosting Windows PowerShell vs. Hosting PowerShell Core
+
+The following code demonstrates how to host Windows PowerShell in an application.  
+As shown below, you can insert your business logic code directly in the `'Main'` method.


No reason to use both backticks and single quotes. Backticks will do here.

joeyaiello · 2017-03-24T22:25:00Z

docs/host-powershell/README.md

+}
+```
+
+However, when it comes to hosting PowerShell Core, there will be a layer of redirection for the powershell load context to take effect.


"PowerShell" casing

joeyaiello · 2017-03-24T22:25:11Z

docs/host-powershell/README.md

+```
+
+However, when it comes to hosting PowerShell Core, there will be a layer of redirection for the powershell load context to take effect.
+In a .NET Core application, the entry point assembly that contains the `'Main'` method is loaded in the default load context,


No single quotes needed

joeyaiello · 2017-03-24T22:25:23Z

docs/host-powershell/README.md

+In a .NET Core application, the entry point assembly that contains the `'Main'` method is loaded in the default load context,
+and thus all assemblies referenced by the entry point assembly, implicitly or explicitly, will also be loaded into the default load context.
+
+In order to have the powershell load context to control assembly loading for the execution of an application,


PowerShell casing

joeyaiello · 2017-03-24T22:25:35Z

docs/host-powershell/README.md

+and thus all assemblies referenced by the entry point assembly, implicitly or explicitly, will also be loaded into the default load context.
+
+In order to have the powershell load context to control assembly loading for the execution of an application,
+the business logic code needs to be extracted out of the entry point assembly and put into a different assembly, say `'Logic.dll'`.


No single quotes

joeyaiello · 2017-03-24T22:25:42Z

docs/host-powershell/README.md

+
+In order to have the powershell load context to control assembly loading for the execution of an application,
+the business logic code needs to be extracted out of the entry point assembly and put into a different assembly, say `'Logic.dll'`.
+The entry point `'Main'` method shall do one thing only -- let the powershell load context load `'Logic.dll'` and start the execution of the business logic.


No single quotes

joeyaiello · 2017-03-24T22:27:20Z

docs/host-powershell/README.md

+```powershell
+dotnet restore .\MyApp\MyApp.csproj
+dotnet publish .\MyApp -c release -r win10-x64
+```


Has this document assumed that the user has installed dotnet-cli? Might it be worth putting a pointer to environment instructions (preferably not owned by us) at the top of the document?

Also, is this the same on Linux with a different RID? Might that be worth calling out?

Unfortunately, as discussed above, all powershell NuGet packages that have been published so far only contain powershell assemblies built specifically for Windows. We need to publish NuGet packages that contain both Windows and Unix assemblies, but dotnet pack doesn't seem to support that.

#3417 is opened to track this.

daxian-dbw · 2017-03-24T23:14:40Z

@joeyaiello @mirichmo All comments have been addressed. Can you please take another look?

joeyaiello

LGTM, thanks!

New commits have been pushed to address the comments.

Add documentation about hosting PowerShell Core

463342e

daxian-dbw assigned mirichmo Mar 24, 2017

daxian-dbw requested a review from joeyaiello March 24, 2017 01:07

msftclas added the cla-not-required label Mar 24, 2017

fix spelling error

9d19138

iSazonov reviewed Mar 24, 2017

View reviewed changes

mirichmo previously requested changes Mar 24, 2017

View reviewed changes

Address review comments

b2b929a

Update .spelling again

56e576b

joeyaiello suggested changes Mar 24, 2017

View reviewed changes

daxian-dbw mentioned this pull request Mar 24, 2017

Publish PowerShell NuGet packages for Linux/OSX platforms #3417

Closed

Address new comments

9bc4782

joeyaiello approved these changes Mar 24, 2017

View reviewed changes

mirichmo approved these changes Mar 25, 2017

View reviewed changes

mirichmo merged commit 8598a51 into PowerShell:master Mar 25, 2017

daxian-dbw deleted the host branch March 25, 2017 02:36

daxian-dbw mentioned this pull request Mar 25, 2017

Provide a way to host PowerShell in a CoreCLR application #2291

Closed

daxian-dbw mentioned this pull request Jul 19, 2017

cmdlet example readme needs to be update to describe how to create a .net core cmdlet with Visual Studio #3081

Closed


		### Example

		The following code is how you host Windows PowerShell in an application.

Add documentation about hosting PowerShell Core #3409

Add documentation about hosting PowerShell Core #3409

Uh oh!

Conversation

daxian-dbw commented Mar 24, 2017

Uh oh!

daviwil commented Mar 24, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

daxian-dbw commented Mar 24, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daviwil commented Mar 24, 2017

Uh oh!

daxian-dbw commented Mar 24, 2017

Uh oh!

joeyaiello left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

daviwil commented Mar 24, 2017 •

edited

Loading

daxian-dbw commented Mar 24, 2017 •

edited

Loading