Content

PowerShell Basics Objects and the Pipeline

By now you would have noticed if you have been reading my other posts where I use PowerShell that it is not your typical Shell and that it behaves in a unique way when it comes to the output generated by the commands we issue in it, this is because PowerShell is an Object based Shell, this means that everything is an object. Those that have programed in Perl, Ruby, Python, C# or any other Objects based language know very well the power of objects, for those that come from a Bash, cmd.exe or any other regular text based shell you will notice that in PowerShell is a lot simpler to parse and use data, typically on one of this shells we are searching for strings, extracting the strings of text that we need and then piping them to something else, this can be very labor intensive.

Lets start by defining what an Object is simple terms, an object is Data and it has 2 types of components:

  • Properties – Information we can retrieve and/or set by name.
  • Method – something we can have happen to the data, it can take arguments to determine what to do or to provide additional information.

To better illustrate Objects and the advantages if offers versus a text based shell lets look at how it is used in PowerShell and why it is one of the foundations for it. Lets look at services. To get a list of services on the system we just do a Get-Service and we get the output, now lets dissect that output:

image

Man time PowerShell will show the output in a table format or in a list format, looking at a table format like the one above we can see each service is represented individually (as rows) and some information of each is shown (as columns). when we look at this each column represents a property and each row an individual object. But wait we know there has to be more to an service than this, right? well yes. PowerShell uses what is known as Format views for certain types of object so as to show what the creator of the cmdlet considers to be the most common pieces of information for use. To look at the Object be it from a command, cmdlet, function workflow ..etc the most common method is to pipe it to the Get-Member cmdlet to get a view

Get-Service | Get-Member

This will produce a list of:

  • Properties – Information about the object.
  • Methods – Things we can do to the objects.
  • ScriptMethods – Pieces of embedded code that will execute when called.
  • Events – Things that happen to an object we can subscribe to be notified when they happen.

It will also tell us what is the .Net Object Class it is being returned.

image

While using this you may noticed that for some outputs of commands you will see more than one Object Class, Get-Member is smart enough to only show the info for the unique classes that are returned. Lets look at the information we can get from a single object, for the example I will use the BITS service so as to not break my machine.  Lets start by saving it in to a variable so it is easier to manipulate. Variables in PowerShell are maded with a $ in the front just like in Perl .

$BITSSrv = Get-Service -Name BITS

Now lets start with the fun part, the methods. To see what we can do with the object we use the Get-Member cmdlet but specify that we want only the methods shown:

PS C:> $BITSSrv | Get-Member -MemberType Method
TypeName: System.ServiceProcess.ServiceController
Name                      MemberType Definition
----                      ---------- ----------
Close                     Method     void Close()
Continue                  Method     void Continue()
CreateObjRef              Method     System.Runtime.Remoting.ObjRef CreateObjRef(type reque...
Dispose                   Method     void Dispose(), void IDisposable.Dispose()
Equals                    Method     bool Equals(System.Object obj)
ExecuteCommand            Method     void ExecuteCommand(int command)
GetHashCode               Method     int GetHashCode()
GetLifetimeService        Method     System.Object GetLifetimeService()
GetType                   Method     type GetType()
InitializeLifetimeService Method     System.Object InitializeLifetimeService()
Pause                     Method     void Pause()
Refresh                   Method     void Refresh()
Start                     Method     void Start(), void Start(string[] args)
Stop                      Method     void Stop()
WaitForStatus             Method     void WaitForStatus(System.ServiceProcess.ServiceContro...

As we can see there are several actions we can take against the service object, we can start, stop, pause, refresh (The object is only the state of what it represents at the given time we retrieved it). Wehn we look at the definitions we can see it shows us that some methods like Pause and Refresh do not take any arguments and others like Start can be called in several ways in some without us giving it arguments in others it tells us the type of class the method will take. Some can be deduce quite easily others we have to look in the MSDN Website for the class information (ServiceController Class)  do the way output is formatted we may loose some of the info we may need. for this we can use one of the Format Cmdlets to make it wrap the line so we can have a better look.

PS C:> $BITSSrv | Get-Member -MemberType Method | Format-Table -Wrap
TypeName: System.ServiceProcess.ServiceController
Name                      MemberType Definition
----                      ---------- ----------
Close                     Method     void Close()
Continue                  Method     void Continue()
CreateObjRef              Method     System.Runtime.Remoting.ObjRef CreateObjRef(type
requestedType)
Dispose                   Method     void Dispose(), void IDisposable.Dispose()
Equals                    Method     bool Equals(System.Object obj)
ExecuteCommand            Method     void ExecuteCommand(int command)
GetHashCode               Method     int GetHashCode()
GetLifetimeService        Method     System.Object GetLifetimeService()
GetType                   Method     type GetType()
InitializeLifetimeService Method     System.Object InitializeLifetimeService()
Pause                     Method     void Pause()
Refresh                   Method     void Refresh()
Start                     Method     void Start(), void Start(string[] args)
Stop                      Method     void Stop()
WaitForStatus             Method     void WaitForStatus(System.ServiceProcess.ServiceControlle
rStatus desiredStatus), void WaitForStatus(System.Service
Process.ServiceControllerStatus desiredStatus, timespan
timeout)    

Lets stop the service:

PS C:> $BITSSrv.Stop()
PS C:> $BITSSrv.Status
Running
PS C:> $BITSSrv.Refresh()
PS C:> $BITSSrv.Status
Stopped

As it can be seen I forgot that when the object is in a variable it is just a representation at the moment it was saved. Let look at Parenthetical execution go get around this, when we wrap the command around ( ) we can use the properties and methods of the object it returns directly. 

PS C:> (Get-Service -Name BITS).Start()
PS C:> (Get-Service -Name BITS).Status
Running

Now since we are poling the information on each command we get the latest information.  You can notice from the examples that Properties do not require ( ) at the end of invocation and Methods do, just something to keep in mind, in fact using tab completion or the ISE it will remind you.

Let look at the properties:

PS C:> Get-Service -Name BITS | Get-Member -MemberType Property
TypeName: System.ServiceProcess.ServiceController
Name                MemberType Definition
----                ---------- ----------
CanPauseAndContinue Property   bool CanPauseAndContinue {get;}
CanShutdown         Property   bool CanShutdown {get;}
CanStop             Property   bool CanStop {get;}
Container           Property   System.ComponentModel.IContainer Container {get;}
DependentServices   Property   System.ServiceProcess.ServiceController[] DependentServices ...
DisplayName         Property   string DisplayName {get;set;}
MachineName         Property   string MachineName {get;set;}
ServiceHandle       Property   System.Runtime.InteropServices.SafeHandle ServiceHandle {get;}
ServiceName         Property   string ServiceName {get;set;}
ServicesDependedOn  Property   System.ServiceProcess.ServiceController[] ServicesDependedOn...
ServiceType         Property   System.ServiceProcess.ServiceType ServiceType {get;}
Site                Property   System.ComponentModel.ISite Site {get;set;}
Status              Property   System.ServiceProcess.ServiceControllerStatus Status {get;}    

You will notice that some of the properties have in the end {get;set} or only {get;} this means we can assign a value to the property of the same type as it is listed in the definition. Since PowerShell will only list some of the properties depending on the formatting it has defined. Do take in to account this is only for the instance of the object, we would not be changing the service it self but the representation we may have in a variable. To change the service itself it would have to be thru a Method.

The formatting of what is displayed is shown following the guidelines shown in the format.pmxml file for each type in the Windows PowerShell folder, for the service it would be in C:WindowsSystem32WindowsPowerShellv1.0 since the view is sometimes limited and we want to do a quick browse of all that is in the properties we can use the formatting cmdlets to exposed all, I tend to use the Format-List cmdlet:

PS C:> Get-Service -Name BITS | Format-List -Property *
Name                : BITS
RequiredServices    : {RpcSs, EventSystem}
CanPauseAndContinue : False
CanShutdown         : False
CanStop             : True
DisplayName         : Background Intelligent Transfer Service
DependentServices   : {}
MachineName         : .
ServiceName         : BITS
ServicesDependedOn  : {RpcSs, EventSystem}
ServiceHandle       : SafeServiceHandle
Status              : Running
ServiceType         : Win32ShareProcess
Site                :
Container           : 

PipeLine

By now you would have noticed in this blogpost and others that the pipeline is used quite a bit in PowerShell. The typical pipeline in other shells will move the standard out of a command to the standard input of another:

image

In the case of PowerShell we are moving objects so there are 2 ways a cmdlet can receive commands from the pipeline:

  1. By Value – this is where the output of a cmdlet must be the same type as what the –InputObject parameter of another takes:
  2. By Property Name – This is when the object has a property that matched the name of a parameter in the other.

So by Value would be:

image

And when we look at the parameters in help we can identify them by looking of they accept from the pipeline and how:

image

 

By Property it would be:

 

image

 

and when we look at the help information for the parameter it would look like:

image

The examples above are from the Service cmdlets so we could just pipe the Get-Service cmdlet any of the other cmdlets for managing services:

PS C:> gcm *service* -Module  Microsoft.PowerShell.Management
CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Cmdlet          Get-Service                                        Microsoft.PowerShell.Man...
Cmdlet          New-Service                                        Microsoft.PowerShell.Man...
Cmdlet          New-WebServiceProxy                                Microsoft.PowerShell.Man...
Cmdlet          Restart-Service                                    Microsoft.PowerShell.Man...
Cmdlet          Resume-Service                                     Microsoft.PowerShell.Man...
Cmdlet          Set-Service                                        Microsoft.PowerShell.Man...
Cmdlet          Start-Service                                      Microsoft.PowerShell.Man...
Cmdlet          Stop-Service                                       Microsoft.PowerShell.Man...
Cmdlet          Suspend-Service                                    Microsoft.PowerShell.Man...

So this would allow us to do:

PS C:> Get-Service -Name BITS | Stop-Service
PS C:> (Get-Service -Name BITS).Status
Stopped
PS C:> Get-Service -Name BITS | Start-Service
PS C:> (Get-Service -Name BITS).Status
Running

I hope that you found this blog post in the series useful and on the next one we will cover how to filter and process the Objects generated so we can glue even more types of cmdlets together.

Carlos Perez

Carlos is currently the Principal Consultant, Team Lead for Research at TrustedSec and well-known for his research on both Metasploit and Windows Powershell. His blog www.darkoperator.com carries the tag line: “Shell Is Only The Beginning”.

Get daily email updates

SC Media's daily must-read of the most current and pressing daily news

By clicking the Subscribe button below, you agree to SC Media Terms and Conditions and Privacy Policy.