From 3b6c87d8738d6519473bac2df8b2b09f8d25d072 Mon Sep 17 00:00:00 2001 From: Dongbo Wang Date: Wed, 21 Jun 2017 18:53:39 -0700 Subject: [PATCH] Update host-powershell doc for beta.3 release (#4071) --- docs/host-powershell/README.md | 59 ++++++++++--------- .../MyApp/MyApp.csproj | 16 +++++ .../MyApp/Program.cs | 35 +++++++++++ .../NuGet.config | 8 +++ 4 files changed, 90 insertions(+), 28 deletions(-) create mode 100644 docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/MyApp.csproj create mode 100644 docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/Program.cs create mode 100644 docs/host-powershell/sample-dotnet2.0-powershell.beta.3/NuGet.config diff --git a/docs/host-powershell/README.md b/docs/host-powershell/README.md index e90f4cbfa5..f1b212d616 100644 --- a/docs/host-powershell/README.md +++ b/docs/host-powershell/README.md @@ -1,16 +1,13 @@ # Host PowerShell Core in .NET Core Applications -> This documentation is based on PowerShell Core packages built against .NET Core 1.1 and prior. -> Things may change after we move to .NET Core 2.0. -> -> **Note** PowerShell v6.0.0-beta.1 has been released, which is on top of .NET Core 2.0 ([preview1-002106-00][netcoreapp20-preview1]). -> The existing design of `PowerShell AssemblyLoadContext` is not changed in `beta.1` release, -> so the way to host PowerShell `beta.1` is the same as before from the C# code perspective. -> However, you will need the 2.0 preview version of .NET Core SDK (the version `2.0.0-preview1-005952` is currently used to build PowerShell Core), -> and the `.csproj` file will need to be updated. -> A .NET Core 2.0 version of the sample application project `"MyApp"` can be found under [sample-dotnet2.0-powershell.beta.1](./sample-dotnet2.0-powershell.beta.1) for your reference. +## PowerShell Core v6.0.0-beta.3 and Later -## PowerShell Core targeting .NET Core 1.1 and Prior +PowerShell Core is refactored in v6.0.0-beta.3 to remove the dependency on a customized `AssemblyLoadContext`. +With this change, hosting PowerShell Core in .NET Core will be the same as hosting Windows PowerShell in .NET. + +Please see the [.NET Core Sample Application](#.net-core-sample-application) section for an example that uses PowerShell Core `beta.3` NuGet packages. + +## PowerShell Core v6.0.0-beta.2 and Prior ### Overview @@ -23,16 +20,16 @@ So applications that want to host PowerShell Core (using PowerShell APIs) need t 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, -such as the in-box `powershell.exe` and other native CoreCLR host in Nano Server. -When using this API, instead of setting up a new load context, -`PowerShellAssemblyLoadContextInitializer` will register a handler to the [Resolving][] event of the default load context. -Then PowerShell Core will depend on the default load context to handle TPA and the `Resolving` event to handle other assemblies. + whose Trusted Platform Assemblies (TPA) do not include PowerShell assemblies, + such as the in-box `powershell.exe` and other native CoreCLR host in Nano Server. + When using this API, instead of setting up a new load context, + `PowerShellAssemblyLoadContextInitializer` will register a handler to the [Resolving][] event of the default load context. + 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. -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][]. + where the TPA list includes PowerShell assemblies. + 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, as it's what you need when building a .NET Core application with .NET CLI. @@ -129,10 +126,21 @@ namespace Application.Test } ``` -### .NET Core Sample Application +[CorePsAssemblyLoadContext.cs]: https://github.com/PowerShell/PowerShell/blob/v6.0.0-alpha.17/src/Microsoft.PowerShell.CoreCLR.AssemblyLoadContext/CoreCLR/CorePsAssemblyLoadContext.cs +[Resolving]: https://github.com/dotnet/corefx/blob/ec2a6190efa743ab600317f44d757433e44e859b/src/System.Runtime.Loader/ref/System.Runtime.Loader.cs#L35 +[bootstrapping]: https://github.com/PowerShell/PowerShell/blob/master/src/powershell/Program.cs#L27 -You can find the sample application project `"MyApp"` under [sample-dotnet1.1](./sample-dotnet1.1). -To build the sample project, run the following commands ([.NET Core SDK 1.0.1](https://github.com/dotnet/cli/releases/tag/v1.0.1) is required): +## .NET Core Sample Application + +- [sample-dotnet1.1](./sample-dotnet1.1) - .NET Core `1.1` + PowerShell Core `alpha.17` NuGet packages. + [.NET Core SDK 1.0.1](https://github.com/dotnet/cli/releases/tag/v1.0.1) is required. +- [sample-dotnet2.0-powershell.beta.1](./sample-dotnet2.0-powershell.beta.1) - .NET Core `2.0.0` + PowerShell Core `beta.1` NuGet packages. + .NET Core SDK `2.0.0-preview1-005952` or higher is required. +- [sample-dotnet2.0-powershell.beta.3](./sample-dotnet2.0-powershell.beta.3) - .NET Core `2.0.0` + PowerShell Core `beta.3` NuGet packages. + .NET Core SDK `2.0.0-preview1-005952` or higher is required. + +You can find the sample application project `"MyApp"` in each of the above 3 sample folders. +To build the sample project, run the following commands (make sure the required .NET Core SDK is in use): ```powershell dotnet restore .\MyApp\MyApp.csproj @@ -141,7 +149,7 @@ dotnet publish .\MyApp -c release -r win10-x64 Then you can run `MyApp.exe` from the publish folder and see the results: -``` +```none PS:> .\MyApp.exe Evaluating 'Get-Command Write-Output' in PS Core Runspace @@ -154,13 +162,8 @@ System.Management.Automation.ActionPreference System.Management.Automation.AliasAttribute ``` -### Remaining Issue +## Remaining Issue PowerShell Core builds separately for Windows and Unix, so the assemblies are different between Windows and Unix platforms. Unfortunately, all PowerShell NuGet packages that have been published so far only contain PowerShell assemblies built specifically for Windows. The issue [#3417](https://github.com/PowerShell/PowerShell/issues/3417) was opened to track publishing PowerShell NuGet packages for Unix platforms. - -[netcoreapp20-preview1]: https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.NETCore.App/2.0.0-preview1-002106-00 -[CorePsAssemblyLoadContext.cs]: https://github.com/PowerShell/PowerShell/blob/master/src/Microsoft.PowerShell.CoreCLR.AssemblyLoadContext/CoreCLR/CorePsAssemblyLoadContext.cs -[Resolving]: https://github.com/dotnet/corefx/blob/ec2a6190efa743ab600317f44d757433e44e859b/src/System.Runtime.Loader/ref/System.Runtime.Loader.cs#L35 -[bootstrapping]: https://github.com/PowerShell/PowerShell/blob/master/src/powershell/Program.cs#L27 \ No newline at end of file diff --git a/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/MyApp.csproj b/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/MyApp.csproj new file mode 100644 index 0000000000..6901e37dda --- /dev/null +++ b/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/MyApp.csproj @@ -0,0 +1,16 @@ + + + + netcoreapp2.0 + MyApp + Exe + win10-x64 + + + + + + + + + diff --git a/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/Program.cs b/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/Program.cs new file mode 100644 index 0000000000..207028a2d1 --- /dev/null +++ b/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/MyApp/Program.cs @@ -0,0 +1,35 @@ +/********************************************************************++ +Copyright (c) Microsoft Corporation. All rights reserved. +--********************************************************************/ + +using System; +using System.Management.Automation; + +namespace Application.Test +{ + public class Program + { + /// + /// Managed entry point shim, which starts the actual program + /// + public static int Main(string[] args) + { + using (PowerShell ps = PowerShell.Create()) + { + Console.WriteLine("\nEvaluating 'Get-Command Write-Output' in PS Core Runspace\n"); + var results = ps.AddScript("Get-Command Write-Output").Invoke(); + Console.WriteLine(results[0].ToString()); + + ps.Commands.Clear(); + + Console.WriteLine("\nEvaluating '([S.M.A.ActionPreference], [S.M.A.AliasAttribute]).FullName' in PS Core Runspace\n"); + results = ps.AddScript("([System.Management.Automation.ActionPreference], [System.Management.Automation.AliasAttribute]).FullName").Invoke(); + foreach (dynamic result in results) + { + Console.WriteLine(result.ToString()); + } + } + return 0; + } + } +} diff --git a/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/NuGet.config b/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/NuGet.config new file mode 100644 index 0000000000..58f8d2c9b6 --- /dev/null +++ b/docs/host-powershell/sample-dotnet2.0-powershell.beta.3/NuGet.config @@ -0,0 +1,8 @@ + + + + + + + +