PowerShell Remoting Project Home

Wednesday, July 12, 2006

Why There Is an Out-Default Cmdlet

PowerShell have a couple of output control cmdlets:
> gcm out-*

CommandType     Name                            Definition
-----------     ----                            ----------
Cmdlet          Out-Default                     Out-Default [-InputObject <P...
Cmdlet          Out-File                        Out-File [-FilePath] <String...
Cmdlet          Out-Host                        Out-Host [-Paging] [-InputOb...
Cmdlet          Out-Null                        Out-Null [-InputObject <PSOb...
Cmdlet          Out-Printer                     Out-Printer [[-Name] <String...
Cmdlet          Out-String                      Out-String [-Stream] [-Width...
Out-Default cmdlet is one of the most mysterious one.
> help out-default

NAME
    Out-Default

SYNOPSIS
    The default controller of output.

DETAILED DESCRIPTION
    The standard treatment at the end of a pipeline is to send all objects to o
    ut-default.  Out-default then sends them all to format-default. It takes th
    e objects that return and sends them to the default destination.  For this
    reason, it is functionally equivalent to out-host but is not called from th
e console.
The help message does not help at all. Luckily enough, Jeffrey Snover has a blog entry talking about this cmdlet.  In summary, It will "figure out how to format and output the object stream" and send them to host via Out-host cmdlet.

Here is my two cents:
1. Out-Default cmdlet is NOT for interactive console User.
Every interactive command from console will have Out-Default appended automatically by Monad engine. Add Out-Default in the middle of pipline could even cause unexpected output.
> gps | format-table
> gps | out-default | format-table      # format-table will not work.
2. Out-Default cmdlet is for Monad hosting application.
To have a full-blown Monad hosting application, you have to create your own "Host" (System.Management.Automation.Host.PSHost) which implement interface to process output (If you don't have your PSHost output interface implemented, your will get an exception when Out-default finally called out-host.). Every interactive command from user input should have Out-Default appended. Then the output of user command were assessed by out-default, formatted by format-* cmdlet, and eventually sent to user interface by out-host cmdlet.
using System.Management.Automation;
using System.Management.Automation.Host;
using System.Management.Automation.Runspaces;

namespace HostingExample
{
    class TestHost
    {
        static void Main(string[] args)
        {
            string command = "gps";
            PSHost myhost = new MyHost();
            Runspace myRunspace = RunspaceFactory.CreateRunspace(myhost);
            myRunspace.Open();
            Pipeline pipeline1 = myRunspace.CreatePipeline(command, true);
            pipeline1.Commands[0].MergeMyResults(PipelineResultTypes.Error, PipelineResultTypes.Output);
            pipeline1.Commands.Add("out-default");
            Pipeline1.Invoke();
        }
    }

    Class MyHost : PSHost
    {
            // MyHost class should be derived from PSHost abstract class.
    }
}
Although you don't have to (and probably should not) type "Out-Default" at the end of your command, it is always there working for you. Given this reason, Out-Default cmdlet is registered and loaded as default cmdlets.

You see it is there, you do not use it, but it is definitely important.

Tags:       


Comments:
PSMDTAG:FAQ: When do I use out-default?

PSMDTAG:CMDLET: Out-Default

Jeffrey Snover [MSFT]
Windows PowerShell/Aspen Architect
Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx
 
This bit gets me confused:

pipeline1.Commands[0].MergeMyResults(PipelineResultTypes.Error, PipelineResultTypes.Output);

and i find that even with out-default, objects don't always come back in a way that is easily converted to text.
 

Post a Comment





<< Home