PSHost Class

  • Reference

Definition

Namespace:
System.Management.Automation.Host
Assembly:
System.Management.Automation.dll
Package:
Microsoft.PowerShell.5.1.ReferenceAssemblies v1.0.0
Package:
System.Management.Automation v7.0.13
Package:
System.Management.Automation v7.1.7
Package:
System.Management.Automation v7.2.12
Package:
System.Management.Automation v7.3.5
Package:
System.Management.Automation v7.4.0
Package:
Microsoft.WSMan.Runtime v6.1.0
Package:
Microsoft.WSMan.Runtime v6.2.0

Defines the properties and facilities providing by an application hosting PowerShell Runspace.

public ref class PSHost abstract
public abstract class PSHost
type PSHost = class
Public MustInherit Class PSHost
Inheritance
Object
PSHost

Remarks

A hosting application derives from this class and overrides the abstract methods and properties. The hosting application creates an instance of its derived class and passes it to the RunspaceFactory CreateRunspace method.

From the moment that the instance of the derived class (the "host class") is passed to CreateRunspace, the PowerShell runtime can call any of the methods of that class. The instance must not be destroyed until after the Runspace is closed.

There is a 1:1 relationship between the instance of the host class and the Runspace instance to which it is passed. In other words, it is not legal to pass the same instance of the host class to more than one call to CreateRunspace. (It is perfectly legal to call CreateRunspace more than once, as long as each call is supplied a unique instance of the host class.)

Methods of the host class can be called by the Runspace or any cmdlet or script executed in that Runspace in any order and from any thread. It is the responsibility of the hosting application to define the host class methods in a threadsafe fashion. An implementation of the host class should not depend on method execution order.

The instance of the host class that is passed to a Runspace is exposed by the Runspace to the cmdlets, scripts, and providers that are executed in that Runspace. Scripts access the host class via the $Host built-in variable. Cmdlets access the host via the Host property of the Cmdlet base class.

Constructors

PSHost()

Protected constructor which does nothing. Provided per .Net design guidelines section 4.3.1.

Properties

CurrentCulture

Gets the host's culture: the culture that the runspace should use to set the CurrentCulture on new threads.
CurrentUICulture

Gets the host's UI culture: the culture that the runspace and cmdlets should use to do resource loading.

The runspace will set the thread current ui culture to this value each time it starts a pipeline.
DebuggerEnabled

This property enables and disables the host debugger if debugging is supported.
InstanceId

Gets a GUID that uniquely identifies this instance of the host. The value should remain invariant for the lifetime of this instance.
Name

Gets the hosting application's identification in some user-friendly fashion. This name can be referenced by scripts and cmdlets to identify the host that is executing them. The format of the value is not defined, but a short, simple string is recommended.
PrivateData

Used to allow the host to pass private data through a Runspace to cmdlets running inside that Runspace's runspace. The type and nature of that data is entirely defined by the host, but there are some caveats:
UI

Gets the hosting application's implementation of the PSHostUserInterface abstract base class. A host that does not want to support user interaction should return null.
Version

Gets the version of the hosting application. This value should remain invariant for a particular build of the host. This value may be referenced by scripts and cmdlets.

Methods

EnterNestedPrompt()

Instructs the host to interrupt the currently running pipeline and start a new, "nested" input loop, where an input loop is the cycle of prompt, input, execute.
ExitNestedPrompt()

Causes the host to end the currently running input loop. If the input loop was created by a prior call to EnterNestedPrompt, the enclosing pipeline will be resumed. If the current input loop is the top-most loop, then the host will act as though SetShouldExit was called.
NotifyBeginApplication()

Called by the engine to notify the host that it is about to execute a "legacy" command line application. A legacy application is defined as a console-mode executable that may do one or more of the following: . reads from stdin . writes to stdout . writes to stderr . uses any of the win32 console APIs.
NotifyEndApplication()

Called by the engine to notify the host that the execution of a legacy command has completed.
SetShouldExit(Int32)

Request by the engine to end the current engine runspace (to shut down and terminate the host's root runspace).

Applies to

See also