PSHost Class

Definition

Namespace:

System.Management.Automation.Host

Assembly:

System.Management.Automation.dll

Package:

System.Management.Automation v7.4.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).

See also

• PSHostRawUserInterface
• Runspace
• PSHostUserInterface