How to Implement a Host User Interface

This section shows how to implement a host user interface class that derives from the PSHostUserInterface class. This class provides functionality that is used to perform dialog-oriented and line-oriented interaction, such as writing to, prompting for, and reading from user input. The following host user interface class can be used as a template for creating your own custom host.

To implement a host user interface class

  1. Define the host user interface class that derives from the PSHostUserInterface class. In the Windows PowerShell samples, this class is implemented in a myhostuserinterface.cs file.

    internal class MyHostUserInterface : PSHostUserInterface
    
    
  2. If you are also implementing a PSHostRawUserInterface class, return an instance of the class.

  3. Implement this method to prompt the user for input. In this example, this functionality is not needed so the method throws a NotImplementedException exception.

    public override Dictionary<string, PSObject> Prompt(
                                                        string caption, 
                                                        string message, 
                                                        System.Collections.ObjectModel.Collection<FieldDescription> descriptions)
    {
       throw new NotImplementedException(
           "The method or operation is not implemented.");
    }
    
    
  4. Implement this method to provide a set of choices that enable the user to choose a single option from a set of options. In this example this functionality is not needed so the method throws a NotImplementedException exception.

    public override int PromptForChoice(string caption, string message, System.Collections.ObjectModel.Collection<ChoiceDescription> choices, int defaultChoice)
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }
    
    
  5. Implement this method to prompt the user for credentials. In this example, this functionality is not needed so the method throws a NotImplementedException exception.

    public override PSCredential PromptForCredential(
                                                     string caption, 
                                                     string message, 
                                                     string userName, 
                                                     string targetName)
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }
    
    
  6. Implement this method to prompt the user for credentials and specify which credential types are allowed. In this example, this functionality is not needed so the method throws a NotImplementedException exception.

    public override PSCredential PromptForCredential(
                                                     string caption, 
                                                     string message, 
                                                     string userName, 
                                                     string targetName, 
                                                     PSCredentialTypes allowedCredentialTypes, 
                                                     PSCredentialUIOptions options)
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }
    
    
  7. Implement this method to read the characters that are entered by the user until a newline (carriage return) is encountered.

    public override string ReadLine()
    {
      return Console.ReadLine();
    }
    
    
  8. Implement this method to read the characters that are entered by the user until a newline (carriage return) is encountered and then return the characters as a secure string. In this example this functionality is not needed so the method throws a NotImplementedException exception.

    public override System.Security.SecureString ReadLineAsSecureString()
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }
    
    
  9. Implement this method to write characters to the output display of the custom host.

    public override void Write(string value)
    {
      System.Console.Write(value);
    }
    
    
  10. Implement this method to write characters to the output display of the host and to specify the foreground and background colors of the characters. This implementation ignores the colors.

    public override void Write(
                               ConsoleColor foregroundColor, 
                               ConsoleColor backgroundColor, 
                               string value)
    {
       // Colors are ignored.
       System.Console.Write(value);
    }
    
    
  11. Implement this method to write a debug message.

    public override void WriteDebugLine(string message)
    {
      Console.WriteLine(String.Format(
                                      CultureInfo.CurrentCulture, 
                                      "DEBUG: {0}", 
                                      message));
    }
    
    
  12. Implement this method to write an error message.

    public override void WriteDebugLine(string message)
    {
      Console.WriteLine(String.Format(
                                      CultureInfo.CurrentCulture, 
                                      "DEBUG: {0}", 
                                      message));
    }
    
    
  13. Implement this method to write a newline character (carriage return) to the output display of the custom host.

    public override void WriteLine()
    {
      System.Console.WriteLine();
    }
    
    
  14. Implement this method to write a line of characters and a newline character (carriage return) to the output display of the custom host.

    public override void WriteLine(string value)
    {
      System.Console.WriteLine(value);
    }
    
    
  15. Implement this method to write a line of characters with specific foreground and background colors and a newline character (carriage return) to the output display of the custom host. This implementation ignores the colors.

    public override void WriteLine(ConsoleColor foregroundColor, ConsoleColor backgroundColor, string value)
    {
      // Write to the output stream, ignore the colors
      System.Console.WriteLine(value);
    }
    
    
  16. Implement this method to write a progress report to the output display of the host. In this example, this functionality is not needed so the method silently returns.

    public override void WriteProgress(long sourceId, ProgressRecord record)
    {
    }
    
    
  17. Implement this method to write an error message.

    public override void WriteVerboseLine(string message)
    {
      Console.WriteLine(String.Format(CultureInfo.CurrentCulture, "VERBOSE: {0}", message));
    }
    
    
  18. Implement this method to write a warning message.

Example

The following code is the implementation of the PSHostUserInterface class described in the previous procedure. For an example of how this interface is used in a host application, see Host02 Sample.

namespace Microsoft.Samples.PowerShell.Host
{
  using System;
  using System.Collections.Generic;
  using System.Globalization;
  using System.Management.Automation;
  using System.Management.Automation.Host;
    
  /// <summary>
  /// A sample implementation of the PSHostUserInterface abstract class for 
  /// console applications. Not all members are implemented. Those that are 
  /// not implemented throw a NotImplementedException exception. Members that 
  /// are implemented include those that map easily to Console APIs. 
  /// </summary>
  internal class MyHostUserInterface : PSHostUserInterface
  {
    /// <summary>
    /// An instance of the PSRawUserInterface class.
    /// </summary>
    private MyRawUserInterface myRawUi = new MyRawUserInterface();

    /// <summary>
    /// Gets an instance of the PSRawUserInterface class for this host
    /// application.
    /// </summary>
    public override PSHostRawUserInterface RawUI
    {
      get { return this.myRawUi; }
    }

    /// <summary>
    /// Prompts the user for input. In this example this functionality is not 
    /// needed so the method throws a NotImplementException exception.
    /// </summary>
    /// <param name="caption">The caption or title of the prompt.</param>
    /// <param name="message">The text of the prompt.</param>
    /// <param name="descriptions">A collection of FieldDescription objects that 
    /// describe each field of the prompt.</param>
    /// <returns>Throws a NotImplementedException exception.</returns>
    public override Dictionary<string, PSObject> Prompt(
                                                        string caption, 
                                                        string message, 
                                                        System.Collections.ObjectModel.Collection<FieldDescription> descriptions)
    {
       throw new NotImplementedException(
           "The method or operation is not implemented.");
    }

    /// <summary>
    /// Provides a set of choices that enable the user to choose a 
    /// single option from a set of options. In this example this 
    /// functionality is not needed so the method throws a 
    /// NotImplementException exception.
    /// </summary>
    /// <param name="caption">Text that proceeds (a title) the choices.</param>
    /// <param name="message">A message that describes the choice.</param>
    /// <param name="choices">A collection of ChoiceDescription objects that describes 
    /// each choice.</param>
    /// <param name="defaultChoice">The index of the label in the Choices parameter 
    /// collection. To indicate no default choice, set to -1.</param>
    /// <returns>Throws a NotImplementedException exception.</returns>
    public override int PromptForChoice(string caption, string message, System.Collections.ObjectModel.Collection<ChoiceDescription> choices, int defaultChoice)
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }

    /// <summary>
    /// Prompts the user for credentials with a specified prompt window caption, 
    /// prompt message, user name, and target name. In this example this 
    /// functionality is not needed so the method throws a 
    /// NotImplementException exception.
    /// </summary>
    /// <param name="caption">The caption for the message window.</param>
    /// <param name="message">The text of the message.</param>
    /// <param name="userName">The user name whose credential is to be prompted for.</param>
    /// <param name="targetName">The name of the target for which the credential is collected.</param>
    /// <returns>Throws a NotImplementedException exception.</returns>
    public override PSCredential PromptForCredential(
                                                     string caption, 
                                                     string message, 
                                                     string userName, 
                                                     string targetName)
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }

    /// <summary>
    /// Prompts the user for credentials by using a specified prompt window caption, 
    /// prompt message, user name and target name, credential types allowed to be 
    /// returned, and UI behavior options. In this example this functionality 
    /// is not needed so the method throws a NotImplementException exception.
    /// </summary>
    /// <param name="caption">The caption for the message window.</param>
    /// <param name="message">The text of the message.</param>
    /// <param name="userName">The user name whose credential is to be prompted for.</param>
    /// <param name="targetName">The name of the target for which the credential is collected.</param>
    /// <param name="allowedCredentialTypes">A PSCredentialTypes constant that 
    /// identifies the type of credentials that can be returned.</param>
    /// <param name="options">A PSCredentialUIOptions constant that identifies the UI 
    /// behavior when it gathers the credentials.</param>
    /// <returns>Throws a NotImplementedException exception.</returns>
    public override PSCredential PromptForCredential(
                                                     string caption, 
                                                     string message, 
                                                     string userName, 
                                                     string targetName, 
                                                     PSCredentialTypes allowedCredentialTypes, 
                                                     PSCredentialUIOptions options)
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }

    /// <summary>
    /// Reads characters that are entered by the user until a newline 
    /// (carriage return) is encountered.
    /// </summary>
    /// <returns>The characters that are entered by the user.</returns>
    public override string ReadLine()
    {
      return Console.ReadLine();
    }

    /// <summary>
    /// Reads characters entered by the user until a newline (carriage return) 
    /// is encountered and returns the characters as a secure string. In this 
    /// example this functionality is not needed so the method throws a 
    /// NotImplementException exception.
    /// </summary>
    /// <returns>Throws a NotImplemented exception.</returns>
    public override System.Security.SecureString ReadLineAsSecureString()
    {
      throw new NotImplementedException("The method or operation is not implemented.");
    }

    /// <summary>
    /// Writes characters to the output display of the host.
    /// </summary>
    /// <param name="value">The characters to be written.</param>
    public override void Write(string value)
    {
      System.Console.Write(value);
    }

    /// <summary>
    /// Writes characters to the output display of the host and specifies the 
    /// foreground and background colors of the characters. This implementation 
    /// ignores the colors.
    /// </summary>
    /// <param name="foregroundColor">The color of the characters.</param>
    /// <param name="backgroundColor">The backgound color to use.</param>
    /// <param name="value">The characters to be written.</param>
    public override void Write(
                               ConsoleColor foregroundColor, 
                               ConsoleColor backgroundColor, 
                               string value)
    {
       // Colors are ignored.
       System.Console.Write(value);
    }

    /// <summary>
    /// Writes a debug message to the output display of the host.
    /// </summary>
    /// <param name="message">The debug message that is displayed.</param>
    public override void WriteDebugLine(string message)
    {
      Console.WriteLine(String.Format(
                                      CultureInfo.CurrentCulture, 
                                      "DEBUG: {0}", 
                                      message));
    }

    /// <summary>
    /// Writes an error message to the output display of the host.
    /// </summary>
    /// <param name="value">The error message that is displayed.</param>
    public override void WriteErrorLine(string value)
    {
      Console.WriteLine(String.Format(
                                      CultureInfo.CurrentCulture, 
                                      "ERROR: {0}", 
                                      value));
    }

    /// <summary>
    /// Writes a newline character (carriage return) 
    /// to the output display of the host. 
    /// </summary>
    public override void WriteLine()
    {
      System.Console.WriteLine();
    }

    /// <summary>
    /// Writes a line of characters to the output display of the host 
    /// and appends a newline character(carriage return). 
    /// </summary>
    /// <param name="value">The line to be written.</param>
    public override void WriteLine(string value)
    {
      System.Console.WriteLine(value);
    }

    /// <summary>
    /// Writes a line of characters to the output display of the host 
    /// with foreground and background colors and appends a newline (carriage return). 
    /// </summary>
    /// <param name="foregroundColor">The forground color of the display. </param>
    /// <param name="backgroundColor">The background color of the display. </param>
    /// <param name="value">The line to be written.</param>
    public override void WriteLine(ConsoleColor foregroundColor, ConsoleColor backgroundColor, string value)
    {
      // Write to the output stream, ignore the colors
      System.Console.WriteLine(value);
    }

    /// <summary>
    /// Writes a progress report to the output display of the host.
    /// </summary>
    /// <param name="sourceId">Unique identifier of the source of the record. </param>
    /// <param name="record">A ProgressReport object.</param>
    public override void WriteProgress(long sourceId, ProgressRecord record)
    {
    }

    /// <summary>
    /// Writes a verbose message to the output display of the host.
    /// </summary>
    /// <param name="message">The verbose message that is displayed.</param>
    public override void WriteVerboseLine(string message)
    {
      Console.WriteLine(String.Format(CultureInfo.CurrentCulture, "VERBOSE: {0}", message));
    }

    /// <summary>
    /// Writes a warning message to the output display of the host.
    /// </summary>
    /// <param name="message">The warning message that is displayed.</param>
    public override void WriteWarningLine(string message)
    {
      Console.WriteLine(String.Format(CultureInfo.CurrentCulture, "WARNING: {0}", message));
    }
  }
}

See Also



Show:
© 2014 Microsoft