PSHost Class

 

Updated: April 27, 2016

Applies To: Windows PowerShell

Contains the base functionality for creating a custom host. A host provides communications between the Windows PowerShell engine and the user.

Namespace:   System.Management.Automation.Host
Assembly:  System.Management.Automation (in System.Management.Automation.dll)

System.Object
  System.Management.Automation.Host.PSHost

public abstract class PSHost

NameDescription
System_CAPS_protmethodPSHost()

Initializes a new instance of the PSHost class. Derived classes typically call this constructor (directly or implicitly) from their own constructors.

NameDescription
System_CAPS_pubpropertyCurrentCulture

Gets the culture that the runspace uses to set the current culture on new threads.

System_CAPS_pubpropertyCurrentUICulture

Gets the UI culture that the runspace and cmdlets use to load resources.

System_CAPS_pubpropertyDebuggerEnabled

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

System_CAPS_pubpropertyInstanceId

Gets the identifier that uniquely identifies this instance of the host.

System_CAPS_pubpropertyName

Gets the user friendly name of the host.

System_CAPS_pubpropertyPrivateData

Gets private data that the host can pass through the runspace.

System_CAPS_pubpropertyUI

Gets the implementation of the PSHostUserInterface class that defines user interaction for this host.

System_CAPS_pubpropertyVersion

Gets the version number of the host.

NameDescription
System_CAPS_pubmethodEnterNestedPrompt()

When overridden in a derived class, instructs the host to interrupt the currently running pipeline and start a new nested input loop.

System_CAPS_pubmethodEquals(Object)

(Inherited from Object.)

System_CAPS_pubmethodExitNestedPrompt()

When overridden in a derived class, instructs the host to exit the currently running input loop.

System_CAPS_protmethodFinalize()

(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

(Inherited from Object.)

System_CAPS_pubmethodGetType()

(Inherited from Object.)

System_CAPS_protmethodMemberwiseClone()

(Inherited from Object.)

System_CAPS_pubmethodNotifyBeginApplication()

When overridden in a derived class, notifies the host that the Windows PowerShell runtime is about to execute a legacy command-line application. A legacy application is defined as a console-mode executable that can perform any of the following operations: read from stdin, write to stdout, write to stderr, or use any of the Windows console functions.

System_CAPS_pubmethodNotifyEndApplication()

When overridden in a derived class, notifies the host that the Windows PowerShell engine has completed the execution of a legacy command. A legacy application is defined as a console-mode executable that can perform any of the following operations: read from stdin, write to stdout, write to stderr, or use any of the Windows console functions.

System_CAPS_pubmethodSetShouldExit(Int32)

When overridden in a derived class, requests to end the current runspace. The Windows PowerShell engine calls this method to request that the host application shut down and terminate the host root runspace.

System_CAPS_pubmethodToString()

(Inherited from Object.)

A host application can pass an instance of the derived class to variants of the CreateRunspace and CreateRunspacePool methods. The Windows PowerShell engine can then communicate with the user operating within the runspace. For more information about host applications, see Writing a Windows PowerShell Host Application.

There must always be a one-to-one relationship between an instance of the host class and the runspace instance to which it is passed. That is, you cannot pass the same instance of the host class to more than one call to the CreateRunspace and CreateRunspacePool methods. Looked at another way, you can call those methods multiple times, but you must always pass a unique instance of the derived host class to each call.

The methods of the host class have the following characteristics.

  • Host methods can be called by the runspace or by any cmdlet and script that is running within that runspace.

  • The methods of the host class can be called in any order and from any thread.

  • The host must define the host class methods in a thread-safe fashion.

  • An implementation of the host class should not depend on the method execution order.

The instance of the host class that is passed to the runspace is available to the cmdlets, scripts, and providers that are executed in that runspace. Scripts access the host class through the $Host variable. Cmdlets that derive from the PSCmdlet class access the host through the Host property of the cmdlet class.

The following code is a basic implementation of a custom host class. Those elements that are not implemented throw an exception or return nothing. (For more information about adding a custom host to a host application, see How to Add a Custom Host.)

namespace Microsoft.Samples.PowerShell.Host
{
    using System;
    using System.Globalization;
    using System.Management.Automation.Host;

    /// <summary>
    /// This is a sample implementation of the PSHost abstract class for 
    /// console applications. Not all members are implemented. Those that 
    /// are not implemented throw a NotImplementedException exception or 
    /// return nothing.
    /// </summary>
    internal class MyHost : PSHost
    {
        /// <summary>
        /// A reference to the PSHost implementation.
        /// </summary>
        private Host01 program;

        /// <summary>
        /// The culture information of the thread that created
        /// this object.
        /// </summary>
        private CultureInfo originalCultureInfo =
            System.Threading.Thread.CurrentThread.CurrentCulture;

        /// <summary>
        /// The UI culture information of the thread that created
        /// this object.
        /// </summary>
        private CultureInfo originalUICultureInfo =
            System.Threading.Thread.CurrentThread.CurrentUICulture;

        /// <summary>
        /// The identifier of this PSHost implementation.
        /// </summary>
        private Guid myId = Guid.NewGuid();

        /// <summary>
        /// Initializes a new instance of the MyHost class. Keep
        /// a reference to the host application object so that it 
        /// can be informed of when to exit.
        /// </summary>
        /// <param name="program">
        /// A reference to the host application object.
        /// </param>
        public MyHost(Host01 program)
        {
            this.program = program;
        }

        /// <summary>
        /// Return the culture information to use. This implementation 
        /// returns a snapshot of the culture information of the thread 
        /// that created this object.
        /// </summary>
        public override System.Globalization.CultureInfo CurrentCulture
        {
            get { return this.originalCultureInfo; }
        }

        /// <summary>
        /// Return the UI culture information to use. This implementation 
        /// returns a snapshot of the UI culture information of the thread 
        /// that created this object.
        /// </summary>
        public override System.Globalization.CultureInfo CurrentUICulture
        {
            get { return this.originalUICultureInfo; }
        }

        /// <summary>
        /// This implementation always returns the GUID allocated at 
        /// instantiation time.
        /// </summary>
        public override Guid InstanceId
        {
            get { return this.myId; }
        }

        /// <summary>
        /// Return a string that contains the name of the host implementation. 
        /// Keep in mind that this string may be used by script writers to
        /// identify when your host is being used.
        /// </summary>
        public override string Name
        {
            get { return "MySampleConsoleHostImplementation"; }
        }

        /// <summary>
        /// This sample does not implement a PSHostUserInterface component so
        /// this property simply returns null.
        /// </summary>
        public override PSHostUserInterface UI
        {
            get { return null; }
        }

        /// <summary>
        /// Return the version object for this application. Typically this
        /// should match the version resource in the application.
        /// </summary>
        public override Version Version
        {
            get { return new Version(1, 0, 0, 0); }
        }

        /// <summary>
        /// Not implemented by this example class. The call fails with
        /// a NotImplementedException exception.
        /// </summary>
        public override void EnterNestedPrompt()
        {
            throw new NotImplementedException(
                "The method or operation is not implemented.");
        }

        /// <summary>
        /// Not implemented by this example class. The call fails
        /// with a NotImplementedException exception.
        /// </summary>
        public override void ExitNestedPrompt()
        {
            throw new NotImplementedException(
                "The method or operation is not implemented.");
        }

        /// <summary>
        /// This API is called before an external application process is 
        /// started. Typically it is used to save state so the parent can 
        /// restore state that has been modified by a child process (after 
        /// the child exits). In this example, this functionality is not  
        /// needed so the method returns nothing.
        /// </summary>
        public override void NotifyBeginApplication()
        {
            return;  
        }

        /// <summary>
        /// This API is called after an external application process finishes.
        /// Typically it is used to restore state that a child process may
        /// have altered. In this example, this functionality is not  
        /// needed so the method returns nothing.
        /// </summary>
        public override void NotifyEndApplication()
        {
           return; 
        }

        /// <summary>
        /// Indicate to the host application that exit has
        /// been requested. Pass the exit code that the host
        /// application should use when exiting the process.
        /// </summary>
        /// <param name="exitCode">The exit code to use.</param>
        public override void SetShouldExit(int exitCode)
        {
            this.program.ShouldExit = true;
            this.program.ExitCode = exitCode;
        }
    }
}

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: