PowerShellTunnel - script your app from PowerShell at runtime

UPDATED WIKI: PowerShellTunnel Considerations

MatHobbs — Thu, 03 Apr 2008 04:56:27 GMT

PowerShellTunnel - Considerations

A) If you don't want to connect to an existing embedded runspace but instead want to remote-connect to new PowerShell 'consoles' on remote clients, refer instead to PowerShell 2.0 or the "PowerShell Remoting" project. PowerShellTunnel is designed for connecting to an existing console or runspace.

B) The PowerTab project could make tab expansion integration cleaner.

C) Serialization: PowerShellTunnel uses ordinary serialization by serialized pipied input or output objects to a stream and sending a raw byte array to and from the tunnel host. If the class is not serializable then just the type name will be sent. PowerShellTunnel does not use WCF data contract serialization for the piped objects themselves.

D) TODO: Add 'help', 'verbose', functionality to cmdlets.

E) Security Warning: once connected to the tunnel host, the tunnel has access to all of the tunnel host's exposed objects and functionality (c.f. Skynet). (Future Powershell runspaces may be restrictable to limit what objects can be accessed.)

F) Multiple hosts/clients: You can create multiple tunnel hosts and multiple tunnels, e.g. a host may be accessed by multiple clients. A client may use multiple tunnels (to different hosts) and use: "select-tunnel" to switch between them or use the "-tunnel" parameter of "invoke-tunnel".

G) Threading: Be aware of threading considerations given that the tunnel host executes on a WCF worker thread (e.g. on a .NET Thread Pool thread).

H) No Ctrl-C? If you invoke-tunnel a script, Ctrl-C from the client does not interrupt it, so beware of infinite loops or long operations.

I) After 'select-tunnel' (or add-tunnel without the -noselect switch), tab expansion is intercepted to to tab expansion on the tunnel host. This is useful when typing the script block of the invoke-tunnel but not especially elsewhere. Use select-tunnel without a parameter to turn off the tab expansion interception (and requires invoke-tunnel to specify a '-tunnel xyz' parameter).

J) There might be ways to streamline the user syntax/experience further. In the meanwhile, consider using an alias to Invoke-Tunnel, e.g.
Set-Alias T Invoke-Tunnel
Set-Alias TP Invoke-Tunnel -pipeoutput
or
function T1 { Invoke-Tunnel -tunnel $mytunnel1 $args}

CREATED ISSUE: Increase WCF Default Message Size Limits

MatHobbs — Wed, 19 Mar 2008 03:16:40 GMT

The default WCF mssage receive size limit of 65536 bytes can be easily hit. Increase this to 1000000000 bytes by default. Also increase WCF data contract serializer setting MaxItemsInObjectGraph and set PreserveReferences to true.

NEW POST: Using invoke-tunnel on XP SP2

MatHobbs — Wed, 19 Mar 2008 03:13:47 GMT

Hi Marco, ah yes: WCF's default limits. Your $x probably referenced an object that would be serialized to > 65536 bytes. I uploaded a new PowerShellTunnel release ("1.01") that bumps up two important WCF settings so you should not get this any more unless your objects is > 1000000000 bytes!

Cheers,
-Mat

CREATED RELEASE: PowerShellTunnel v1.01 Source (Mar 18, 2008)

Wed, 19 Mar 2008 03:09:02 GMT

Additions only for the default WCF behavior:
1) Increase the default MaxReceivedMessageSize so large objects can be serialized and piped without a WCF error.
2) Add a custom data contract serializer behavior to increase MaxItemsInObjectGraph too.

UPDATED WIKI: PowerShellTunnel Quick Start

MatHobbs — Wed, 19 Mar 2008 03:00:05 GMT

PowerShellTunnel - Quick Start

With PowerShellTunnel you create a tunnel between two endpoints: the tunnel 'host' and the tunnel 'client' - you need to start both. You send scripts from the client to execute on the host as if you had typed them directly into the host (including tab expansion), so you have access to all the objects and capabilities of the host from the client. Objects can be piped into or out of the tunnel (ordinary serialization is used).

If you want to follow through the quick start, you'll need to first go through PowerShellTunnel How to Build and PowerShellTunnel How to Install.

This quick-start works through two scenarios:

Console -> Console: Two PowerShell consoles, one acts as a tunnel host, the other as a tunnel client.
Console -> Application: One ordinary .NET console application with an embedded PowerShell runspace (which exposes some application objects as ordinary PowerShell variables) which hosts a tunnel, and an ordinary PowerShell console which acts as a tunnel client to interact with the application's objects while the application is running.

Console -> Console

In this scenario, the tunnel host will be a PowerShell console with a couple of objects which we will try to access from another PowerShell console (the tunnel client).

Step 1) Create the Tunnel Host.

1-a) Start a PowerShell console.

1-b) Enter the following commands to add the snapin, add a tunnel host (use the address you specified when you did the install, or refer to PowerShellTunnel How to Install to add an http permission for your user if necessary), and create a couple of ordinary objects:

add-pssnapin PowerShellTunnel
$tunnelhost = add-tunnelhost "http://localhost:8000/PowerShellTunnel/Host1"
$x = dir
$y = $x[0]

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin and add a tunnel to the tunnel host (using the same address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

2-c) Access the objects on the host. Note that tab expansion works correctly, e.g. on the Name property of $y, i.e. $y.N{TAB} becomes $y.Name. The pipeline should work (both in and out) so long as types are WCF-OK (standard types or types made known to WCF ...).

Examples:

invoke-tunnel { $x }
invoke-tunnel { $y.Name }
$yLocal = invoke-tunnel { $y }; $yLocal # $yLocal is set to a local (serialized & deserialized) copy of $y
invoke-tunnel { $z = "This variable is set on the host!" }

Example piping objects in and out:

"write line #1", "write line #2", ("write", "line", "#3" ) | invoke-tunnel { $input | foreach { write-host $_; "$_".Length } }
$myx = invoke-tunnel { $x } -pipe    #sets $myx to a list of DirectoryInfo and FileInfo objects piped from the host

Example sending a script file:

'$z = 4; $z = $z*$z; write-host "On Host: $z"; "Return to client: $z" ' > test.ps1
type test.ps1 | invoke-tunnel { invoke-expression $input }
del test.ps1

Note: if there are multiple tunnels, then select-tunnel can be used to change the current invoke-tunnel default (and redirect tab expansion), or invoke-tunnel can be called with a '-tunnel xyz' parameter.

Step 3) Switch back to the host console and verify that you see:

write line #1
write line #2
write line #3

and verify that $z was created:

$z  #You'll see "This variable is set on the host!"

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Remove-Tunnel $tunnel
Remove-PSSnapin PowerShellTunnel

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Remove-TunnelHost $tunnelhost
Remove-PSSnapin PowerShellTunnel

Console -> Application

In this scenario, the tunnel host will be a PowerShell runspace hosted (embedded) within a console application (PowerShellTunnel.Embeddable.Example.exe) which 'exposes' a few of its objects as PowerShell variables in the hosted runspace. The client will be an ordinary PowerShell console as before.

Step 1) Create the Tunnel Host.

First, if you are re-using the same host address from before, close the tunnel host console from the 'Console -> Console' walkthrough if it is still open.

Build and run PowerShellTunnel.Embeddable.Example.exe. This is a console application that outputs some information and waits on a Console.Readline() where pressing Enter exits the application. A PowerShell runspace is hosted and a tunnel host created in the runspace at address "http://localhost:8000/PowerShellTunnel/Host1" (or change this value in program.cs).

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin, add a tunnel to connect to the above tunnel host (using the address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

2-c) Access the objects on the host. Note that tab expansion works correctly, e.g. on the Name property of $y, i.e. $y.N<TAB> becomes $y.Name. The pipeline should work (both in and out) so long as the piped types are serializable.

invoke-tunnel { $myvar1 }
invoke-tunnel { $myvar2 }
invoke-tunnel { $myvar3 }

The same kinds of access is available as before with some warnings:

The example hosted runspace does not have a console so any scripts which access the console in any way will fail (you can create a more advanced host).
The tunnel host gets its requests on WCF worker threads, so be aware of multi-threading issues on whatever is exposed via the runspace.
Be aware that the client has access to anything that the hosted runspace has.
You may want to configure WCF security in the general case.

General Notes

Refer to PowerShellTunnel Considerations.

EDITED ISSUE: Increase WCF Default Message Size Limits

MatHobbs — Wed, 19 Mar 2008 00:17:32 GMT

NEW POST: Using invoke-tunnel on XP SP2

marcoshaw — Fri, 14 Mar 2008 17:28:56 GMT

Following your guides:

PSH> invoke-tunnel { $x }
Invoke-Tunnel : The maximum message size quota for incoming messages (65536) has been exceeded. To increase the quota,
use the MaxReceivedMessageSize property on the appropriate binding element.
At line:1 char:14
+ invoke-tunnel <<<< { $x }

Still appears things are working.

UPDATED WIKI: Home

MatHobbs — Thu, 13 Mar 2008 02:34:31 GMT

PowerShellTunnel

Host a PowerShell runspace and expose application objects as ordinary PowerShell variables. Add a 'tunnel host', then use an ordinary (local or remote) PowerShell console (or runspace) to 'tunnel' (connect using WCF) to your application's runspace at runtime and script away.

Home - where you are now.
PowerShellTunnel Quick Start - a quick step-by-step walk-through of PowerShellTunnel.
PowerShellTunnel How to Install - a guide to requirements and installing PowerShellTunnel.
PowerShellTunnel How to Uninstall - a guide to uninstalling PowerShellTunnel.
PowerShellTunnel How to Build - a guide to building PowerShellTunnel.
PowerShellTunnel Reference - a guide to the cmdlets and PowerShellTunnel.sln.
PowerShellTunnel Considerations - notes on various issues relating to PowerShellTunnel.

PowerShellTunnel, what is it and why is it..

While using PowerShell to construct and manipulate .NET objects, did you ever think that it would be pretty cool to be able to open a PowerShell console and connect to and directly access the objects of a running application (at least the objects it exposes)? (You can't do this with Remoting in PowerShell 2.0 where you can only open new remote consoles.)

For example you might want to do:

Ad-hoc debugging, diagnostics, or monitoring.
Change object properties or calling methods at runtime.
Ad-hoc (or scripted) unit, system, or integrity tests on a live application.
Simulate events and actions.
Allow automation of your application without explicit interface contracts (ad-hoc or prototyping APIs).
Perhaps even adding or changing functionality on-the-fly.
... probably many other things you might think of.

There is an existing PowerShell Remoting project which uses a remote service to which you connect to to create a PowerShell host that you talk to through your client connection. This isn't quite what what I was after and after hearing that PowerShell 2.0 was coming, decided to wait and see. So PowerShell 2.0 CTP is here and does have Remoting ability but this is also focused on the administrative desire to summon a PowerShell console on a remote host and control it from the client, but neither approach can connect to an existing application's embedded PowerShell runspace.

So, after some reading and playing, PowerShellTunnel was created. PowerShellTunnel is a single VS2005 solution containing:

Server-side cmdlets allowing you to start a 'tunnel host' from a PowerShell console or runspace. A 'tunnel host' allows 'tunnels' (tunnel clients) to access your console/runspace.
Client-side cmdlets allowing you to start a 'tunnel' (connection) from a PowerShell console or runspace to an existing tunnel host (local or remote) and send scripts to onvoke on the tunnel host console/runspace. This includes piping objects in and out.
Tab-expansion 'works' on the client: pressing tab will return tab expansion results from the tunnel host's runspace. A gotcha (for now) is that as long as you have a 'current tunnel' selected, tab expansion always diverts to the current tunnel's host.
An ordinary 'embeddable' PowerShell runspace class (hostable by any .NET app) where you explicitly specify what objects to expose (specifying which PowerShell variable names) and any tunnel hosts to host.
An example of a console application with a few simple objects that you can use to connect to from an ordinary PowerShell console.

Note that:

WCF is used to do all the legwork of the underlying connection, by default the code uses http. By using WCF we avoid having to code for transport options, security, and other issues as this should be all achievable through WCF.
Serializable objects can be piped into and out of the tunnel.
The cmdlets also allow an ordinary PowerShell console to act as a tunnel host. This is the easiest way to start playing with PowerShellTunnel: use one PowerShell console as the tunnel host and another as the tunnel client. Similarly an embedded runspace could start a tunnel to any tunnel host too.
Any console or runspace can have multiple tunnel hosts and/or can have multiple tunnels open.

To make a long story short, review the PowerShellTunnel Quick Start to see if this suits you. Use the Issue Tracker for any bugs or suggestions.
Use the Discussions tab for questions, comments, ideas, or to share how you have used PowerShellTunnel.

Cheers,
-Matthew Hobbs
(Very) Intermittent Blog

UPDATED RELEASE: PowerShellTunnel v1.0 Source (Mar 02, 2008)

Mon, 03 Mar 2008 04:34:18 GMT

First release (source only) including the source required to build the PowerShellTunnel assembly (PowerShellTunnel.dll) and an example application host (PowerShellTunnel.Embeddable.Example.exe).

RELEASED: PowerShellTunnel v1.0 Source (Mar 02, 2008)

Mon, 03 Mar 2008 04:34:18 GMT

First release (source only) including the source required to build the PowerShellTunnel assembly (PowerShellTunnel.dll) and an example application host (PowerShellTunnel.Embeddable.Example.exe).

UPDATED RELEASE: PowerShellTunnel - Initial Release (Source) (Mar 02, 2008)

Mon, 03 Mar 2008 04:32:41 GMT

Initial source-only release including the source required to build the PowerShellTunnel assembly (PowerShellTunnel.dll) and an example application host (PowerShellTunnel.Embeddable.Example.exe).

UPDATED RELEASE: PowerShellTunnel - Initial Release (Source) (Mar 02, 2008)

Mon, 03 Mar 2008 04:31:24 GMT

Initial source-only release including the PowerShellTunnel assembly (PowerShellTunnel.dll) and an example application host (PowerShellTunnel.Embeddable.Example.exe).

CREATED RELEASE: PowerShellTunnel - Initial Release (Source) (Mar 02, 2008)

Mon, 03 Mar 2008 04:29:10 GMT

Initial source-only release including the PowerShellTunnel assembly (PowerShellTunnel.dll) and an example application host (PowerShellTunnel.Embeddable.Example.exe).

UPDATED WIKI: PowerShellTunnel Considerations

MatHobbs — Mon, 03 Mar 2008 04:13:25 GMT

PowerShellTunnel - Considerations

A) If you don't want to connect to an existing embedded runspace but instead want to remote-connect to new PowerShell 'consoles' on remote clients, refer instead to PowerShell 2.0 or the "PowerShell Remoting" project. PowerShellTunnel is designed for connecting to an existing console or runspace.

B) The PowerTab project could make tab expansion integration cleaner.

C) Serialization: PowerShellTunnel uses ordinary serialization by serialized pipied input or output objects to a stream and sending a raw byte array to and from the tunnel host. If the class is not serializable then just the type name will be sent. PowerShellTunnel does not use WCF data contract serialization for the piped objects themselves.

D) TODO: Add 'help', 'verbose', functionality to cmdlets.

E) Security Warning: once connected to the tunnel host, the tunnel has access to all of the tunnel hosts exposed objects and functionality.

F) Multiple hosts/clients: You can create multiple tunnel hosts and multiple tunnels, e.g. a host may be accessed by multiple clients. A client may use multiple tunnels (to different hosts) and use: "select-tunnel" to switch between them or use the "-tunnel" parameter of "invoke-tunnel".

G) Threading: Be aware of threading considerations given that the tunnel host executes on a WCF worker thread (e.g. on a .NET Thread Pool thread).

H) No Ctrl-C? If you invoke-tunnel a script, Ctrl-C from the client does not interrupt it, so beware of infinite loops or long operations.

I) After 'select-tunnel' (or add-tunnel without the -noselect switch), tab expansion is intercepted to to tab expansion on the tunnel host. This is useful when typing the script block of the invoke-tunnel but not especially elsewhere. Use select-tunnel without a parameter to turn off the tab expansion interception (and requires invoke-tunnel to specify a '-tunnel xyz' parameter).

J) There might be ways to streamline the user syntax/experience further. In the meanwhile, consider using an alias to Invoke-Tunnel, e.g.
Set-Alias T Invoke-Tunnel
Set-Alias TP Invoke-Tunnel -pipeoutput
or
function T1 { Invoke-Tunnel -tunnel $mytunnel1 $args}

UPDATED WIKI: PowerShellTunnel Considerations

MatHobbs — Mon, 03 Mar 2008 04:10:50 GMT

PowerShellTunnel - Considerations

A) If you don't want to connect to an existing embedded runspace but instead want to remote-connect to new PowerShell 'consoles' on remote clients, refer instead to PowerShell 2.0 or the "PowerShell Remoting" project. PowerShellTunnel is designed for connecting to an existing console or runspace.

B) The PowerTab project could make tab expansion integration cleaner.

C) Serialization: PowerShellTunnel uses ordinary serialization by serialized pipied input or output objects to a stream and sending a raw byte array to and from the tunnel host. If the class is not serializable then just the type name will be sent. PowerShellTunnel does not use WCF data contract serialization for the piped objects themselves.

D) TODO: Add 'help', 'verbose', functionality to cmdlets.

E) Security Warning: once connected to the tunnel host, the tunnel has access to all of the tunnel hosts exposed objects and functionality.

F) Multiple hosts/clients: You can create multiple tunnel hosts and multiple tunnels, e.g. a host may be accessed by multiple clients. A client may use multiple tunnels (to different hosts) and use: "select-tunnel" to switch between them or use the "-tunnel" parameter of "invoke-tunnel".

G) Threading: Be aware of threading considerations given that the tunnel host executes on a WCF worker thread (e.g. on a .NET Thread Pool thread).

H) No Ctrl-C? If you invoke-tunnel a script, Ctrl-C from the client does not interrupt it, so beware of infinite loops or long operations.

I) After 'select-tunnel' (or add-tunnel without the -noselect switch), tab expansion is intercepted to to tab expansion on the tunnel host. This is useful when typing the script block of the invoke-tunnel but not especially elsewhere. Use select-tunnel without a parameter to turn off the tab expansion interception (and requires invoke-tunnel to specify a '-tunnel xyz' parameter).

J) There might be ways to streamline the user syntax/experience further. In the meanwhile, consider using an alias to Invoke-Tunnel, e.g.
Set-Alias T Invoke-Tunnel
or
function T1 { Invoke-Tunnel -tunnel $mytunnel1 $args}

UPDATED WIKI: PowerShellTunnel Reference

MatHobbs — Mon, 03 Mar 2008 04:09:48 GMT

PowerShellTunnel Reference

There is a single Visual Studio 2005 solution (PowerShellTunnel.sln) containing two projects.

The first project is the main PowerShellTunnel.dll project which consists of: a) the server (tunnel host) PowerShell cmdlets (Host folder); b) the client (tunnel) PowerShell cmdlets (Client folder); and c) an example embedded PowerShell runspace class for use within a .NET application (Embeddable folder).

The second project (PowerShellTunnel.Embeddable.Example.exe) is an example of a .NET application (a console app) hosting an embedded runspace which you can communicate to from an ordinary PowerShell console window (using a tunnel).

Note that there are assembly references to System.Management.Automation.dll which is a PowerShell SDK assembly - ref the Vista SDK.

Glossary

PowerShell console or runspace - a PowerShell console is an ordinary PowerShell shell windos, a PowerShell runspace is a non-visual PowerShell 'console'. (A PowerShell console contains a PowerShell runspace.)

Tunnel Host - a (WCF) service host listening for requests to run a script (allowing objects to be piped in) and returning any piped output objects. A Tunnel Host is instantiated by a PowerShell console or runspace against which any arriving scripts are invoked.

Tunnel - a (WCF implemented) connection to a Tunnel Host (local or remote) through which scripts can be sent (along with any objects to be piped in) and receiving any response (incliuding any output piped objects).

PowerShellTunnel Assembly

PowerShellTunnel.dll contains the host and client PowerShell cmdlets and an example embedded PowerShell runspace class.
Before using any of the PowerShell cmdlets you need to:

First: install PowerShellTunnel (see PowerShellTunnel How to Install) - this is a one-off step.
Secondly: each time you open a console (or runspace) you need to add the snapin:

=add-pssnapin PowerShellTunnel

Tunnel Hosting Cmdlets

Tunnel hosting cmdlets are run from a PowerShell console or runspace to add (instantiate) or remove a tunnel host. Each tunnel host is tied to a WCF endpoint address from which it receives each incoming script request (on a .NET thread pool thread) and invokes the script on the PowerShell console or runspace and manages the serialization (using standard serialization to and from a byte array so the types must be known at each end) of objects piped into or out of the invocation.

Add-TunnelHost

Only one parameter is input (which may be a pipeline input), the base address to listen on.
A tunnel host (a WCF service host: System.ServiceModel.ServiceHost) instance is returned.
In the current code only Http is used but any WCF-supported transport is possible.
Refer to PowerShellTunnel How to Install for help on any setup configuration you need to do.
Any security or configurability we can defer entrely to WCF.

Example
$tunnelhost = Add-TunnelHost "http://localhost:8000/PowerShellTunnel/Host1"

Remove-TunnelHost

An added tunnel host should clean itself up when the PowerShell console or runspace's process is closed. Remove-TunnelHost can be used to do this beforehand.

Only one parameter is input (which may be a pipeline input), the tunnel host (WCF service host) to remove (close).

Example
Remove-TunnelHost $tunnelhost

Tunnel cmdlets

Tunnel cmdlets are run from a PowerShell console or runspace to make a connection to an already existing local or remote tunnel host (local or remote). Each tunnel is a WCF connection to one tunnel host. A script can be invoked on the tunnel (Invoke-Tunnel) whereby it is executed on the tunnel hosts' PowerShellconsole or runspace. The tunnel handles serialization (using standard serialization to and from a byte array so types must be known at each end) of objects piped into or out of the script invocation (see PowerShellTunnel Serialization).

Add-Tunnel

There are three parameters:

HostAddress (mandatory) - the address (e.g. "http://...") of the tunnel host.
Binding - optional Binding object if not using the default WsHttpBinding.
NoSelect - optional switch to prevent the new tunnel from automatically being selected as the default (i.e. bypass doing an automatic Select-Tunnel).

Example
$tunnel = Add-Tunnel "http://localhost:8000/PowerShellTunnel/Host1"

A new tunnel instance is returned (if you only ever plan on using one tunnel in the session you don't need to retain this value).

Unless "-NoSelect" is explicitly specified, the newly created tunnel will be 'selected' - see Select-Tunnel below.

Select-Tunnel

Example
Select-Tunnel $tunnel

If you use Add-Tunnel without specifying "-NoSelect" then the newly added tunnel be be automatically 'selected'.

'Selecting' a tunnel has two effects:

Redirect tab-expansion - pressing TAB will normally call function:tabexpansion, Select-Tunnel renames this and substitutes code to pass tab expansion onto the tunnel host instead.
Default tunnel for Invoke-Tunnel - when calling Invoke-Tunnel (see below) a tunnel does not need to be explicitly specified, instead the 'selected' tunnel is used.

If switching between multiple tunnels you could use Select-Tunnel each time in order to redirect tab expansion each time.

Invoke-Tunnel

Invokes a script on the tunnel host of the optionally specified tunnel. If no tunnel is specified, the currently 'selected' tunnel (as specified by the last call to Select-Tunnel or Add-Tunnel without specifying the -NoSelect switch) is used.

There are three parameters:

ScriptBlock (mandatory) - the script to execute on the tunnel host's PowerShell console or runspace..
Tunnel - optional tunnel instance on which to invoke the script (defaults to the current'y 'selected' tunnel).
-PipeOutput (optional switch) - return serialized (if possible) output to the client. If not provided (the default) then any output will be first formatted on the host (using Out-String -stream) and the resulting strings output to the client.

Examples:

invoke-tunnel { $x }
invoke-tunnel { $y.Name }
$yLocal = invoke-tunnel -p { $y }; $yLocal # $yLocal is set to a local (serialized & deserialized) copy of $y
invoke-tunnel { $z = "This variable is set on the host!" }

Example piping objects in and out:
"write line #1", "write line #2", ("write", "line", "#3" ) | invoke-tunnel -p { $input | foreach { write-host $_; "$_".Length } }

Example sending a script file:

'$z = 4; $z = $z*$z; write-host "On Host: $z"; "Return to client: $z" ' > test.ps1
type test.ps1 | invoke-tunnel { invoke-expression $input }
del test.ps1

Remove-Tunnel

An added tunnel should clean itself up when the PowerShell console or runspace's process is closed. Remove-Tunnel can be used to do this beforehand.

Only one parameter is input (which may be a pipeline input), the tunnel to remove (close).

Example
Remove-Tunnel $tunnel

EmbeddableRunspace

The EmbeddableRunspace folder in the PowerShellTunnel project contains several classes implementing an example hidden or embeddable PowerShell runspace EmbeddableRunspace (with no console input or output - though it could be readily extended to log output). There is nothing special in PowerShellTunnel's implementation of these classes except that there is a useful EmbeddableRunspaceExecute helper class which allows you to easily host a runspace on its own thread and specify what application objects to expose (make available to the embedded PowerShell runspace as ordinary PowerShell variables). See the example PowerShellTunnel.Embeddable.Example project to see how this can be done in practice.

EmbeddableRunspaceExecute.Startup()

Use Startup() to start a thread hosting the the embeddable runspace.

EmbeddableRunspaceExecute.ExposeObject()

Use ExposeObject() for each object you want to 'publish' to the hosted runspace, e.g.

ExposeObject("myvar1", obj)

which will set a runspace variable $myvar1 to obj where it will be available for any tunnels.

EmbeddableRunspaceExecute.AddTunnelHost()

Use AddTunnelHost() to effectively do an Add-TunnelHost (to allow client tunnels to connect to the runspace).

Use another PowerShell console to tunnel (connect) into the embedded runspace using add-tunnel, and then invoke-tunnel.

EmbeddableRunspaceExecute.Shutdown()

Use Shutdown() to close the embedded runspace and join the thread.

Assumption

As we are using WCF Http by default, we assume that access has been granted (from an admin console), e.g. (note that this only needs to be done once).

netsh http add urlacl url="...your host address..." user="YOURMACHINENAME\YOURUSERNAME"

Note that this embeddable runspace example application requires access to PowerShellTunnel.dll but it does not require that it be installed (it does not use any PowerShellTunnel cmdlets).

Install (SnapIn.cs)

SnapIn.cs provides the necessary hooks to allow PowerShell to detect the included cmdlets.

PowerShellTunnel.Embeddable.Example

PowerShellTunnel.Embeddable.Example.exe is built by compiling the PowerShellTunnel.Embeddable.Example project in PowerShellTunnel.sln. It is an ordinary Windows console application. Running the application writes some instructions to the console window and stops by waiting on a Console.ReadLine(). PowerShellTunnel.Embeddable.Example embeds an instance of EmbeddableRunspace and exposes three application objects as PowerShell variables:

$myvar1 = a StringBuilder containing the text 'hi there'
$myvar2 = a DateTime of 2008/1/3
$myvar3 = 45.6 as a decimal data type

A tunnel host is hosted at a default address (change this accordingly).

Note that hosting the EmbeddableRunspace does not need to be on a new thread. Whether or not you use a separate thread, be aware of threading issues of incoming tunnel client requests (scripts) operating on your exposed objects. Note that incoming tunnel client requests (scripts) run on WCF threads - normally .NET thread pool worker threads.

You can then open an ordinary PowerShell console window and Add-Tunnel to connect a running PowerShellTunnel.Embeddable.Example.exe instance's runspace's tunnel host and then Invoke-Tunnel scripts on the application's exposed objects, e.g.

invoke-tunnel { $myvar1 }
invoke-tunnel { $myvar2 }
invoke-tunnel { $myvar3 }

You can set or change variables on the hosted runspace as well as call methods on the objects, and pipe in or out objects in the usual PowerShell way.

UPDATED WIKI: PowerShellTunnel Quick Start

MatHobbs — Mon, 03 Mar 2008 03:50:41 GMT

PowerShellTunnel - Quick Start

Console -> Console: Two PowerShell consoles, one acts as a tunnel host, the other as a tunnel client.
Console -> Application: One ordinary .NET console application with an embedded PowerShell runspace (which exposes some application objects as ordinary PowerShell variables) which hosts a tunnel, and an ordinary PowerShell console which acts as a tunnel client to interact with the application's objects while the application is running.

Console -> Console

In this scenario, the tunnel host will be a PowerShell console with a couple of objects which we will try to access from another PowerShell console (the tunnel client).

Step 1) Create the Tunnel Host.

add-pssnapin PowerShellTunnel
$tunnelhost = add-tunnelhost "http://localhost:8000/PowerShellTunnel/Host1"
$x = dir
$y = $x[0]

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin and add a tunnel to the tunnel host (using the same address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $x }
invoke-tunnel { $y.Name }
$yLocal = invoke-tunnel { $y }; $yLocal # $yLocal is set to a local (serialized & deserialized) copy of $y
invoke-tunnel { $z = "This variable is set on the host!" }

Example piping objects in and out:
"write line #1", "write line #2", ("write", "line", "#3" ) | invoke-tunnel { $input | foreach { write-host $_; "$_".Length } }

Example sending a script file:

'$z = 4; $z = $z*$z; write-host "On Host: $z"; "Return to client: $z" ' > test.ps1
type test.ps1 | invoke-tunnel { invoke-expression $input }
del test.ps1

Step 3) Switch back to the host console and verify that you see:

write line #1
write line #2
write line #3

and verify that $z was created:

$z  #You'll see "This variable is set on the host!"

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Remove-Tunnel $tunnel
Remove-PSSnapin PowerShellTunnel

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Remove-TunnelHost $tunnelhost
Remove-PSSnapin PowerShellTunnel

Console -> Application

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin, add a tunnel to connect to the above tunnel host (using the address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $myvar1 }
invoke-tunnel { $myvar2 }
invoke-tunnel { $myvar3 }

The same kinds of access is available as before with some warnings:

The example hosted runspace does not have a console so any scripts which access the console in any way will fail (you can create a more advanced host).
The tunnel host gets its requests on WCF worker threads, so be aware of multi-threading issues on whatever is exposed via the runspace.
Be aware that the client has access to anything that the hosted runspace has.
You may want to configure WCF security in the general case.

General Notes

Refer to PowerShellTunnel Considerations.

UPDATED WIKI: PowerShellTunnel Quick Start

MatHobbs — Mon, 03 Mar 2008 03:47:14 GMT

PowerShellTunnel - Quick Start

Console -> Console: Two PowerShell consoles, one acts as a tunnel host, the other as a tunnel client.
Console -> Application: One ordinary .NET console application with an embedded PowerShell runspace (which exposes some application objects as ordinary PowerShell variables) which hosts a tunnel, and an ordinary PowerShell console which acts as a tunnel client to interact with the application's objects while the application is running.

Console -> Console

In this scenario, the tunnel host will be a PowerShell console with a couple of objects which we will try to access from another PowerShell console (the tunnel client).

Step 1) Create the Tunnel Host.

add-pssnapin PowerShellTunnel
$tunnelhost = add-tunnelhost "http://localhost:8000/PowerShellTunnel/Host1"
$x = dir
$y = $x[0]

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin and add a tunnel to the tunnel host (using the same address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $x }
invoke-tunnel { $y.Name }
$yLocal = invoke-tunnel { $y }; $yLocal # $yLocal is set to a local (serialized & deserialized) copy of $y
invoke-tunnel { $z = "This variable is set on the host!" }

Example piping objects in and out:
"write line #1", "write line #2", ("write", "line", "#3" ) | invoke-tunnel { $input | foreach { write-host $_; "$_".Length } }

Example sending a script file:

'$z = 4; $z = $z*$z; write-host "On Host: $z"; "Return to client: $z" ' > test.ps1
type test.ps1 | invoke-tunnel { invoke-expression $input }
del test.ps1

Step 3) Switch back to the host console and verify that you see:

write line #1
write line #2
write line #3

and verify that $z was created:

$z  #You'll see "This variable is set on the host!"

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Remove-Tunnel $tunnel
Remove-PSSnapin PowerShellTunnel

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Remove-TunnelHost $tunnelhost
Remove-PSSnapin PowerShellTunnel

Console -> Application

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin, add a tunnel to connect to the above tunnel host (using the address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $myvar1 }
invoke-tunnel { $myvar2 }
invoke-tunnel { $myvar3 }

The same kinds of access is available as before with some warnings:

The hosted runspace does not have a console (there is more and does not have prompting ability, so any scripts which access the console in any way will fail.
The tunnel host gets requests on WCF worker threads, so be aware of multi-threading issues on whatever is exposed via the runspace.
Be aware that the client has access to anything that the runspace has.
You may want to configure WCF security in the general case.

General Notes

Refer to PowerShellTunnel Considerations.

UPDATED WIKI: PowerShellTunnel Quick Start

MatHobbs — Mon, 03 Mar 2008 03:40:54 GMT

PowerShellTunnel - Quick Start

Console -> Console: Two PowerShell consoles, one acts as a tunnel host, the other as a tunnel client.
Console -> Application: One ordinary .NET console application with an embedded PowerShell runspace (which exposes some application objects as ordinary PowerShell variables) which hosts a tunnel, and an ordinary PowerShell console which acts as a tunnel client to interact with the application's objects while the application is running.

Console -> Console

In this scenario, the tunnel host will be a PowerShell console with a couple of objects which we will try to access from another PowerShell console (the tunnel client).

Step 1) Create the Tunnel Host.

add-pssnapin PowerShellTunnel
$tunnelhost = add-tunnelhost "http://localhost:8000/PowerShellTunnel/Host1"
$x = dir
$y = $x[0]

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin and add a tunnel to the tunnel host (using the same address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $x }
invoke-tunnel { $y.Name }
$yLocal = invoke-tunnel { $y }; $yLocal # $yLocal is set to a local (serialized & deserialized) copy of $y
invoke-tunnel { $z = "This variable is set on the host!" }

Example piping objects in and out:
"write line #1", "write line #2", ("write", "line", "#3" ) | invoke-tunnel { $input | foreach { write-host $_; "$_".Length } }

Example sending a script file:

'$z = 4; $z = $z*$z; write-host "On Host: $z"; "Return to client: $z" ' > test.ps1
type test.ps1 | invoke-tunnel { invoke-expression $input }
del test.ps1

Step 3) Switch back to the host console and verify that you see:

write line #1
write line #2
write line #3

and verify that $z was created:

$z  #You'll see "This variable is set on the host!"

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Remove-Tunnel $tunnel
Remove-PSSnapin PowerShellTunnel

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Remove-TunnelHost $tunnelhost
Remove-PSSnapin PowerShellTunnel

Console -> Application

Step 1) Create the Tunnel Host.

First, close the tunnel host console from the 'Console -> Console' walkthrough if it it still open (we will re-use the same host address for this example).

Build and running PowerShellTunnel.Embeddable.Example.exe. This is a console application that outputs some information and waits on a Console.Readline() where pressing Enter exits the application. A PowerShell runspace is hosted and a tunnel host created in the runspace at address "http://localhost:8000/PowerShellTunnel/Host1" (if you want to change that address, change the hostAddress constant in program.cs).

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin, add a tunnel to connect to the above tunnel host (using the address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $myvar1 }
invoke-tunnel { $myvar2 }
invoke-tunnel { $myvar3 }

The same kinds of access is available as before with some warnings:

The hosted runspace does not have a console (there is more and does not have prompting ability, so any scripts which access the console in any way will fail.
The tunnel host gets requests on WCF worker threads, so be aware of multi-threading issues on whatever is exposed via the runspace.
Be aware that the client has access to anything that the runspace has.
You may want to configure WCF security in the general case.

General Notes

Refer to PowerShellTunnel Considerations.

UPDATED WIKI: PowerShellTunnel Quick Start

MatHobbs — Mon, 03 Mar 2008 03:39:41 GMT

PowerShellTunnel - Quick Start

Console -> Console: Two PowerShell consoles, one acts as a tunnel host, the other as a tunnel client.
Console -> Application: One ordinary .NET console application with an embedded PowerShell runspace (which exposes some application objects as ordinary PowerShell variables) which hosts a tunnel, and an ordinary PowerShell console which acts as a tunnel client to interact with the application's objects while the application is running.

Console -> Console

In this scenario, the tunnel host will be a PowerShell console with a couple of objects which we will try to access from another PowerShell console (the tunnel client).

Step 1) Create the Tunnel Host.

add-pssnapin PowerShellTunnel
$tunnelhost = add-tunnelhost "http://localhost:8000/PowerShellTunnel/Host1"
$x = dir
$y = $x[0]

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin, add a tunnel to connect to the above tunnel host (using the address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $x }
invoke-tunnel { $y.Name }
$yLocal = invoke-tunnel { $y }; $yLocal # $yLocal is set to a local (serialized & deserialized) copy of $y
invoke-tunnel { $z = "This variable is set on the host!" }

Example piping objects in and out:
"write line #1", "write line #2", ("write", "line", "#3" ) | invoke-tunnel { $input | foreach { write-host $_; "$_".Length } }

Example sending a script file:

'$z = 4; $z = $z*$z; write-host "On Host: $z"; "Return to client: $z" ' > test.ps1
type test.ps1 | invoke-tunnel { invoke-expression $input }
del test.ps1

Step 3) Switch back to the host console and verify that you see:

write line #1
write line #2
write line #3

and verify that $z was created:

$z  #You'll see "This variable is set on the host!"

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Remove-Tunnel $tunnel
Remove-PSSnapin PowerShellTunnel

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Remove-TunnelHost $tunnelhost
Remove-PSSnapin PowerShellTunnel

Console -> Application

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

2-a) Start a PowerShell console.

2-b) Enter the following commands to add the snapin, add a tunnel to connect to the above tunnel host (using the address that you used for the host).

add-pssnapin PowerShellTunnel
$tunnel = add-tunnel "http://localhost:8000/PowerShellTunnel/Host1"

invoke-tunnel { $myvar1 }
invoke-tunnel { $myvar2 }
invoke-tunnel { $myvar3 }

The same kinds of access is available as before with some warnings:

The hosted runspace does not have a console (there is more and does not have prompting ability, so any scripts which access the console in any way will fail.
The tunnel host gets requests on WCF worker threads, so be aware of multi-threading issues on whatever is exposed via the runspace.
Be aware that the client has access to anything that the runspace has.
You may want to configure WCF security in the general case.

General Notes

Refer to PowerShellTunnel Considerations.

PowerShellTunnel - script your app from PowerShell at runtime

UPDATED WIKI: PowerShellTunnel Considerations

PowerShellTunnel - Considerations

CREATED ISSUE: Increase WCF Default Message Size Limits

NEW POST: Using invoke-tunnel on XP SP2

CREATED RELEASE: PowerShellTunnel v1.01 Source (Mar 18, 2008)

UPDATED WIKI: PowerShellTunnel Quick Start

PowerShellTunnel - Quick Start

Console -> Console

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

Step 3) Switch back to the host console and verify that you see:

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Console -> Application

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

General Notes

EDITED ISSUE: Increase WCF Default Message Size Limits

NEW POST: Using invoke-tunnel on XP SP2

UPDATED WIKI: Home

PowerShellTunnel

Contents

PowerShellTunnel, what is it and why is it..

UPDATED RELEASE: PowerShellTunnel v1.0 Source (Mar 02, 2008)

RELEASED: PowerShellTunnel v1.0 Source (Mar 02, 2008)

UPDATED RELEASE: PowerShellTunnel - Initial Release (Source) (Mar 02, 2008)

UPDATED RELEASE: PowerShellTunnel - Initial Release (Source) (Mar 02, 2008)

CREATED RELEASE: PowerShellTunnel - Initial Release (Source) (Mar 02, 2008)

UPDATED WIKI: PowerShellTunnel Considerations

PowerShellTunnel - Considerations

UPDATED WIKI: PowerShellTunnel Considerations

PowerShellTunnel - Considerations

UPDATED WIKI: PowerShellTunnel Reference

PowerShellTunnel Reference

Glossary

PowerShellTunnel Assembly

Tunnel Hosting Cmdlets

Add-TunnelHost

Remove-TunnelHost

Tunnel cmdlets

Add-Tunnel

Select-Tunnel

Invoke-Tunnel

Remove-Tunnel

EmbeddableRunspace

EmbeddableRunspaceExecute.Startup()

EmbeddableRunspaceExecute.ExposeObject()

EmbeddableRunspaceExecute.AddTunnelHost()

EmbeddableRunspaceExecute.Shutdown()

Assumption

Install (SnapIn.cs)

PowerShellTunnel.Embeddable.Example

UPDATED WIKI: PowerShellTunnel Quick Start

PowerShellTunnel - Quick Start

Console -> Console

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

Step 3) Switch back to the host console and verify that you see:

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Console -> Application

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

General Notes

UPDATED WIKI: PowerShellTunnel Quick Start

PowerShellTunnel - Quick Start

Console -> Console

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

Step 3) Switch back to the host console and verify that you see:

Step 4) Switch back to the client console and remove (close) the Tunnel and remove the snapin.

Step 5) Switch back to the host console and remove (close) the Tunnel Host and remove the snapin.

Console -> Application

Step 1) Create the Tunnel Host.

Step 2) Create the Tunnel Client.

General Notes

UPDATED WIKI: PowerShellTunnel Quick Start

PowerShellTunnel - Quick Start

Console -> Console