Category Archives: Object

Where-Object

February 26, 2014 Adam

SYNOPSIS
Creates a filter that controls which objects will be passed along a command pipeline.

SYNTAX
Where-Object [-FilterScript] <scriptblock> [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Where-Object cmdlet selects objects from the set of objects that are passed to it. It uses a script block as a filter and evaluates the script block for each object. If the result of the evaluation is True, the object is returned. If the result of the evaluation is not True, the object is ignored.

PARAMETERS
-FilterScript <scriptblock>
Specifies the script block that is used to filter the objects. Enclose the script block in braces ( {} ).

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the objects to be filtered. You can also pipe the objects to Where-Object.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
System.Management.Automation.PSObject
You can pipe the objects to be filtered to Where-Object.

OUTPUTS

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>Get-Service | Where-Object {$_.Status -eq “Stopped”}

    Description
    ———–
    This command gets a list of all services that are currently stopped. The “$” symbol represents each object that is passed to the Where-Object cmdlet.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Process | Where-Object {$_.workingset -gt 25000*1024}

    Description
    ———–
    This command lists processes that have a working set greater than 25,000 kilobytes (KB). Because the value of the WorkingSet property is stored in bytes, the value of 25,000 is multiplied by 1,024.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Process | Where-Object { $_.ProcessName -match “^p.*” }

    Description
    ———–
    This command gets the processes with a ProcessName property that begins with the letter “p”. The match operator enables you to use regular expressions within a Where clause.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Process -name svchost | Where-Object {$True}

    Description
    ———–
    This command lists all of the processes named “svchost”.

The Where-Object cmdlet evaluates the script block, which typically includes a reference to the object currently in the pipeline ($_), and casts the results to a Boolean type: True or False. If the result is True, the object is returned. Otherwise, it is discarded.

In this case, the script block just returns True, so all the objects are returned.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113423

cmdlet, Object, Tee

Tee-Object

February 26, 2014 Adam

NAME
Tee-Object

SYNOPSIS
Saves command output in a file or Variable, and displays it in the console.

SYNTAX
Tee-Object [-FilePath] <string> [-InputObject <psobject>] [<CommonParameters>]

Tee-Object -Variable <string> [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Tee-Object cmdlet sends the output of a command in two directions (like the letter “T”). It stores the output in a file or Variable and also sends it down the pipeline. If Tee-Object is the last command in the pipeline, the command output is displayed in the console.

PARAMETERS
-FilePath <string>
Specifies the file where the cmdlet stores the object. Accepts wildcards that resolve to a single file.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the object input to the cmdlet. Enter a Variable that contains the objects or type a command or expression that gets the objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Variable <string>
Assigns a reference to the input objects to the specified Variable.

        Required?                    true
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe objects to be redirected to Tee-Object.

OUTPUTS
System.Management.Automation.PSObject
Tee-Object returns the object that it redirected.

NOTES

You can also use the Out-File cmdlet or the redirection operator, both of which save the output in a file but do not send it down the pipeline.

Tee-Object uses Unicode encoding when it writes to files. As a result, the output might not be formatted properly in files with a different encoding. To specify the encoding, use the Out-File cmdlet.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Process | Tee-Object -FilePath C:\Test1\testfile2.txt

    Handles NPM(K)    PM(K)     WS(K) VM(M) CPU(s)    Id ProcessName
    ——- ——    —–     —– —– ——    — ———–
     83     4     2300     4520    39     0.30    4032 00THotkey
     272     6     1400     3944    34     0.06    3088 alg
     81     3     804     3284    21     2.45     148 ApntEx
     81     4     2008     5808    38     0.75    3684 Apoint
    …

    Description
    ———–
    This command gets a list of the processes running on the computer and sends the result to a file. Because a second path is not specified, the result will be displayed in the console.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Process notepad | Tee-Object -variable proc | Select-Object processname,handles

    ProcessName                             Handles
    ———–                             ——-
    notepad                                 43
    notepad                                 37
    notepad                                 38
    notepad                                 38

    Description
    ———–
    This command gets a list of the processes running on the computer and sends the result to a Variable named “proc”. It then pipes the resulting objects along to Select-Object, which selects the ProcessName and Handles property. Note that the $proc Variable includes the default information returned by Get-Process.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113417
    about_Redirection
    Select-Object

cmdlet, Object, Sort

Sort-Object

February 26, 2014 Adam

NAME
Sort-Object

SYNOPSIS
Sorts objects by property values.

SYNTAX
Sort-Object [[-Property] <Object[]>] [-CaseSensitive] [-Culture <string>] [-Descending] [-InputObject <psobject>] [-Unique] [<CommonParameters>]

DESCRIPTION
The Sort-Object cmdlet sorts objects in ascending or descending order based on the values of properties of the object.

You can specify a single property or multiple properties (for a multi-key sort), and you can select a case-sensitive or case-insensitive sort. You can also direct Sort-Object to display only the objects with a unique value for a particular property.

PARAMETERS
-CaseSensitive [<SwitchParameter>]
Indicates that the sort should be case sensitive. By default, sorting is not case sensitive.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Culture <string>
Specifies the cultural configuration to use when sorting.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Descending [<SwitchParameter>]
Sorts the objects in descending order. The default is ascending order.

The Descending parameter applies to all properties. To sort by some properties in
ascending order and others in descending order, you must specify their property values by using a hash table. For details, see the examples.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the objects to be sorted.

When you use the InputObject parameter to submit a collection of items, Sort-Object receives one object that represents the collection. Because one object cannot be sorted, Sort-Object returns the entire collection unchanged.

To sort objects, pipe them to Sort-Object.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Property <Object[]>
Specifies the properties to use when sorting. Objects are sorted based on the values of these properties. Enter the names of the properties. Wildcards are permitted.

If you specify multiple properties, the objects are first sorted by the first property. If more than one object has the same value for the first property, those objects are sorted by the second property. This process continues until there are no more specified properties or no groups of objects.

If you do not specify properties, the cmdlet sorts based on default properties for the object type.

The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Expression <string> or <script block>
        — Ascending <Boolean>
        — Descending <Boolean>

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? true

-Unique [<SwitchParameter>]
Eliminates duplicates and returns only the unique members of the collection. You can use this parameter instead of using the Get-Unique cmdlet.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe the objects to be sorted to Sort-Object.

OUTPUTS
System.Management.Automation.PSObject
Sort-Object returns the sorted objects.

NOTES

Sort-Object sorts objects based on the properties that you specify or the default sort properties for objects of that type.

If an object does not have one of the specified properties, the property value for that object is interpreted by the cmdlet as NULL and is placed at the end of the sort order.

When sorting objects, Sort-Object uses the Compare method for each property. If a property does not implement IComparable, the cmdlet converts the property value to a string and uses the Compare method for System.String.

The Sort-Object cmdlet sorts objects in ascending or descending order based on the values of properties of the object.

If you sort on a property whose value is an enumeration, Sort-Object sorts the enumeration values in numeric order; it does not sort the enumeration member names. For example, if you sort services by status, services with a status of “Stopped” appear before services with a status of “Running”, because the value of Status is a ServiceControllerStatus enumeration, in which “Stopped” has a value of 1 and “Running” has a value of 4.

————————– EXAMPLE 1 ————————–

C:\PS>Get-ChildItem | Sort-Object

    Mode                LastWriteTime     Length Name
    —-                ————-     —— —-
    -a—         9/13/2005 4:24 PM         0 0
    -a—         9/6/2005 4:19 PM         12 a.csv
    -a—         9/21/2005 3:49 PM        529 a.Ps
    -a—         8/22/2005 4:14 PM         22 a.pl
    -a—         9/27/2005 10:33 AM         24 a.txt
    -a—         9/15/2005 10:31 AM        398 a.vbs
    -a—         7/21/2005 12:39 PM     37066 a.xml
    -a—         8/28/2005 11:30 PM     5412 a.xslt
    -a—        10/25/2005 1:59 PM        125 AdamTravel.txt
    -a—         7/21/2005 9:49 AM         59 add2Num.Ps
    -a—         8/29/2005 5:42 PM     7111 Add-Content.xml
    -a—         9/21/2005 12:46 PM     8771 aliens.Ps
    -a—         8/10/2005 2:10 PM        798 array.xml
    -a—         8/4/2004 5:00 AM        110 AUTORUN.INF
    -a—         9/6/2005 4:20 PM        245 b.csv
    …

    Description
    ———–
    This command sorts the subdirectories and files in the current directory. Because no properties are specified, the files and directories are sorted in ascending alphabetical order by their default sort property, Name.

————————– EXAMPLE 2 ————————–

C:\PS>Get-ChildItem | Sort-Object -Property length

    Mode                LastWriteTime     Length Name
    —-                ————-     —— —-
    -a—         12/3/2006 5:35 PM         2 pref.txt
    -a—         9/6/2006 3:33 PM         15 count.txt
    -a—         7/26/2006 10:01 AM         30 filenoext
    -a—         8/18/2006 9:02 AM         52 temp.ps1
    -a—         8/18/2006 9:02 AM         52 temp.msh
    -a—         9/6/2006 3:33 PM         56 fivewords.txt
    -a—         7/26/2006 9:28 AM         80 date.csv
    -a—         7/29/2006 7:15 PM         84 test2.txt
    -a—         7/29/2006 7:15 PM         84 test.ps1

    Description
    ———–
    This command displays the files in the current directory in ascending order by file length.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Process | Sort-Object -Property WS | Select-Object -last 5

    Handles NPM(K)    PM(K)     WS(K) VM(M) CPU(s)     Id ProcessName
    ——- ——    —–     —– —– ——     — ———–
     1105     25    44236     18932 197    93.81 2032 iexplore
     2526     66    37668     36836 221 393.27    868 svchost
        974     19    22844     45928 371    88.39 3952 WINWORD
     1371     22    42192     61872 323    75.75 1584 INFOPATH
     2145     58    93088     70680 619 396.69 3908 OUTLOOK

    Description
    ———–
    This command displays the five processes on the computer with the greatest memory use based on the size of their working sets.

The command uses the Get-Process cmdlet to get a list of processes. It uses a pipeline operator (|) to send the results to the Sort-Object cmdlet, which sorts the objects in working-set order.

Another pipeline operator sends the results to the Select-Object, which displays only the last five items in the list.

————————– EXAMPLE 4 ————————–

C:\PS>Get-History | Sort-Object -Descending

    Description
    ———–
    This command sorts HistoryInfo objects using the Id property as the default key.

————————– EXAMPLE 5 ————————–

    C:\PS>C:\PS> Get-Service | Sort-Object -Property `
    @{Expression=”Status”;Descending=$true}, `
    @{Expression=”DisplayName”;Descending=$false}

    Status Name             DisplayName
    —— —-             ———–
    Running ALG                Application Layer Gateway Service
    Running Ati HotKey Poller Ati HotKey Poller
    Running wuauserv         Automatic Updates
    Running BITS             Background Intelligent Transfer Ser…
    Running Client for NFS     Client for NFS
    …
    Stopped clr_optimizatio… .NET Runtime Optimization Service v…
    Stopped Alerter            Alerter
    Stopped AppMgmt            Application Management
    Stopped aspnet_state     ASP.NET State Service
    Stopped ATI Smart         ATI Smart
    Stopped ClipSrv            ClipBook

    Description
    ———–
    This command displays the services on the computer in descending Status order and ascending DisplayName order.

The command uses the Get-Service cmdlet to get the services on the computer. It uses a pipeline operator (|) to send services to the Sort-Object cmdlet.

To sort one property in ascending order and another property in descending order, the command uses a hash table for the value of the Property parameter. The hash table uses an Expression key to specify the property name and an Ascending or Descending key to specify the sort order.

The resulting display, which sorts the Status values in descending order, lists properties with a Status value of “Running” before those with a Status value of “Stopped”. When sorted in ascending order, “Stopped” appears before “Running”, because Status is an enumerated property in which the value of “Stopped” (1) is less than the value of “Running” (4).

————————– EXAMPLE 6 ————————–

C:\PS>Get-ChildItem *.txt | Sort-Object -Property @{Expression={$_.LastWriteTime – $_.CreationTime}; Ascending=$false} | Format-Table LastWriteTime, CreationTime

    LastWriteTime                         CreationTime
    ————-                         ————
    2/21/2006 10:22:20 AM                 10/3/2005 4:19:40 PM
    2/27/2006 8:14:24 AM                    2/23/2006 10:41:08 PM
    2/24/2006 1:26:19 PM                    2/23/2006 11:23:36 PM
    1/5/2006 12:01:35 PM                    1/5/2006 11:35:30 AM
    2/24/2006 9:25:40 AM                    2/24/2006 9:22:24 AM
    2/24/2006 9:40:01 AM                    2/24/2006 9:39:41 AM
    2/21/2006 10:21:30 AM                 2/21/2006 10:21:30 AM

    Description
    ———–
    This command sorts text files in descending order by the time span between CreationTime and LastWriteTime.

————————– EXAMPLE 7 ————————–

C:\PS>Get-Content servers.txt

    localhost
    test01
    server01
    server02
    localhost
    server01

    C:\PS> Get-Content servers.txt | Sort-Object -Unique
    localhost
    server01
    server02
    test01

    Description
    ———–
    These commands sort the names of servers in a text file. The second command uses the Sort-Object cmdlet with the Unique parameter to return a sorted list without duplicates.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113403
Group-Object

cmdlet, Object, Select

Select-Object

February 26, 2014 Adam

NAME
Select-Object

SYNOPSIS
Selects specified properties of an object or set of objects. It can also select unique objects from an array of objects, or it can select a specified number of objects from the beginning or end of an array of objects.

SYNTAX
Select-Object [[-Property] <Object[]>] [-ExcludeProperty <string[]>] [-ExpandProperty <string>] [-First <int>] [-InputObject <psobject>] [-Last <int>] [-Skip <int>] [-Unique] [<CommonParameters>]

Select-Object [-Index <Int32[]>] [-InputObject <psobject>] [-Unique] [<CommonParameters>]

DESCRIPTION
The Select-Object cmdlet gets only the specified properties of an object or set of objects. It can also select unique objects from an array of objects, or it can select a specified number of objects from the beginning or end of an array of objects.

If you use Select-Object to select specified properties, it copies the values of those properties from the input objects and creates new objects that have the specified properties and copied values.

Use the Property parameter to specify the properties you want to select. Or, use the First, Last, Unique, Skip, and Index parameters to select particular objects from an array of input objects. For more specific object filtering, use the Where-Object cmdlet.

PARAMETERS
-ExcludeProperty <string[]>
Removes the specifies properties from the selection. Wildcards are permitted. This parameter is effective only when the command also includes the Property parameter.

The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are:

— Name or Label <string>
— Expression <string> or <scriptblock>

For more information, see the examples.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? true

-ExpandProperty <string>
Specifies a property to select, and indicates that an attempt should be made to expand that property. Wildcards are permitted in the property name.

For example, if the specified property is an array, each value of the array is included in the output. If the property contains an object, the properties of that object are displayed in the output.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? true

-First <int>
Specifies the number of objects to select from the beginning of an array of input objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Index <Int32[]>
Selects objects from an array based on their index values. Enter the indexes in a comma-separated list.

Indexes in an array begin with 0, where 0 represents the first value and (n-1) represents the last value.

        Required?                    false
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies objects to send to the cmdlet through the pipeline. This parameter enables you to pipe objects to Select-Object.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Last <int>
Specifies the number of objects to select from the end of an array of input objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Property <Object[]>
Specifies the properties to select. Wildcards are permitted.

        The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:
        — Name (or Label) <string>
        — Expression <string> or <script block>

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? true

-Skip <int>
Skips (does not select) the specified number of items. By default, the Skip parameter counts from the beginning of the array or list of objects, but if the command uses the Last parameter, it counts from the end of the list or array.

Unlike the Index parameter, which starts counting from 0, the Skip parameter begins at 1.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Unique [<SwitchParameter>]
Specifies that if a subset of the input objects has identical properties and values, only a single member of the subset will be selected.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe any object to Select-Object.

OUTPUTS
System.Management.Automation.PSObject

NOTES

You can also refer to Select-Object by its built-in Alias, “select”. For more information, see about_aliases.

————————– EXAMPLE 1 ————————–

C:\PS>Get-Process | Select-Object ProcessName,Id,WS

    Description
    ———–
    This command displays a list of processes. Only the name, ID, and working set (WS) properties of the processes are displayed.

————————– EXAMPLE 2 ————————–

C:\PS>Get-Process | Select-Object processname -ExpandProperty modules |
Format-List

    ProcessName     : 00THotkey
    Size             : 256
    Company         : TOSHIBA Corporation
    FileVersion     : 1, 0, 0, 27
    ProductVersion    : 6, 2, 0, 0
    Description     : THotkey
    Product         : TOSHIBA THotkey
    ModuleName        : 00THotkey.exe
    FileName         : C:\WINDOWS\system32\00THotkey.exe
    BaseAddress     : 4194304

    Description
    ———–
    This command displays information about the modules used by the processes running on a computer. It uses the ExpandProperty parameter to display the details contained within the modules property.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Process | Sort-Object -Property WS | Select-Object -Last 5

    Handles NPM(K)    PM(K)     WS(K) VS(M) CPU(s)     Id ProcessName
    ——- ——    —–     —– —– ——     — ———–
     2866     320    33432     45764 203 222.41 1292 svchost
        577     17    23676     50516 265    50.58 4388 WINWORD
        826     11    75448     76712 188    19.77 3780 Ps
     1367     14    73152     88736 216    61.69    676 Ps
     1612     44    66080     92780 380 900.59 6132 INFOPATH

    Description
    ———–
    This command displays the five processes that are using the most memory. The Sort-Object cmdlet is used to sort the processes according to memory (working set) usage, and the Select-Object cmdlet is used to select only the last five members of the resulting array of objects.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Process | Select-Object -Property ProcessName,@{Name=”Start Day”; Expression = {$_.StartTime.DayOfWeek}}

    ProcessName StartDay
    —-         ——–
    alg         Wednesday
    ati2evxx     Wednesday
    ati2evxx     Thursday
    …

    Description
    ———–
    This command displays the name and start day of the processes running on a computer.

The values of the Property parameter are ProcessName and a calculated property named “Start Day.” The “Start Day” property is added by using a hash table with Name and Expression keys.

————————– EXAMPLE 5 ————————–

C:\PS>”a”,”b”,”c”,”a”,”a”,”a” | Select-Object -Unique

    a
    b
    c

    Description
    ———–
    This command displays unique characters from an array of characters.

————————– EXAMPLE 6 ————————–

C:\PS>$a = Get-Eventlog -log “Windows PowerShell”

C:\PS> $a | Select-Object -index 0, ($a.count – 1)

    Description
    ———–
    These commands get the first (newest) and last (oldest) events in the Windows Powershell event log.

The first command uses the Get-EventLog cmdlet to get all events in the Windows Powershell log. It saves the events in the $a Variable.

The second command uses a pipeline operator (|) to send the events in $a to the Select-Object cmdlet. The Select-Object command uses the Index parameter to select items by their index number. The index for the first event is 0. The index for the last event is the number of items in $a minus 1.

————————– EXAMPLE 7 ————————–

C:\PS>New-PSSession -computername (Get-Content servers.txt | Select-Object -Skip 1)

    Description
    ———–
    This command creates a new PSSession on each of the computers listed in the Servers.txt files, except for the first one.

This command uses the Select-Object cmdlet to select all but the first computer in a list of computer names. The resulting list of computers is set as the value of the ComputerName parameter of the New-PSSession cmdlet.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113387
    Where-Object
    Group-Object
    Sort-Object

cmdlet, New, Object

New-Object

February 26, 2014 Adam

NAME
New-Object

SYNOPSIS
Creates an instance of a Microsoft .NET Framework or COM object.

SYNTAX
New-Object -ComObject <string> [-Strict] [-Property <hashtable>] [<CommonParameters>]

New-Object [-TypeName] <string> [[-ArgumentList] <Object[]>] [-Property <hashtable>] [<CommonParameters>]

DESCRIPTION
The New-Object cmdlet creates an instance of a .NET Framework or COM object.

You can specify either the type of a .NET Framework class or a ProgID of a COM object. By default, you type the fully qualified name of a .NET Framework class and the cmdlet returns a reference to an instance of that class. To create an instance of a COM object, use the ComObject parameter and specify the ProgID of the object as its value.

PARAMETERS
-ArgumentList <Object[]>
Specifies a list of arguments to pass to the constructor of the .NET Framework class. Separate elements in the list by using commas (,). The Alias for ArgumentList is Args.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-ComObject <string>
Specifies the programmatic identifier (ProgID) of the COM object.

        Required?                    true
        Position?                    named
        Default value                None
        Accept pipeline input?     false
        Accept wildcard characters? false

-Property <hashtable>
Sets property values and invokes methods of the new object.

Enter a hash table in which the keys are the names of properties or methods and the values are property values or method arguments. New-Object creates the object and sets each property value and invokes each method in the order that they appear in the hash table.

If the new object is derived from the PSObject class, and you specify a property that does not exist on the object, New-Object adds the specified property to the object as a NoteProperty. If the object is not a PSObject, the command generates a non-terminating error.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Strict [<SwitchParameter>]
Specifies that an error should be raised if the COM object that you attempt to create uses an interop assembly. This enables you to distinguish actual COM objects from .NET Framework objects with COM-callable wrappers.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-TypeName <string>
Specifies the fully qualified name of the .NET Framework class. You cannot specify both the TypeName parameter and the ComObject parameter.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
Object
New-Object returns the object that is created.

NOTES

New-Object provides the most commonly-used Functionality of the VBScript CreateObject Function. A statement like Set objShell = CreateObject(“Shell.Application”) in VBScript can be translated to $objShell = New-Object -comobject “Shell.Application” in Windows PowerShell.

New-Object expands upon the Functionality available in the Windows Script Host Environment by making it easy to work with .NET Framework objects from the command line and within scripts.

————————– EXAMPLE 1 ————————–

C:\PS>New-Object -TypeName System.Version -ArgumentList “1.2.3.4”

    Major Minor Build Revision
    —– —– —– ——–
    1     2     3     4

    Description
    ———–
    This command creates a System.Version object using the string “1.2.3.4” as the constructor.

————————– EXAMPLE 2 ————————–

C:\PS>$ie = New-Object -comobject InternetExplorer.Application -Property @{navigate2=”www.microsoft.com”; visible = $true}

    Description
    ———–
    This command creates an instance of the COM object that represents the Internet Explorer application. It uses the Property parameter to call the Navigate2 method and to set the Visible property of the object to $true to make the application visible.

This command is the equivalent of the following:

    $ie = New-Object -comobject InternetExplorer.Application
    $ie.navigate2(“www.microsoft.com”)
    $ie.visible = $true

————————– EXAMPLE 3 ————————–

C:\PS>$a=New-Object -comobject Word.Application -strict -Property @{visible=$true}

    New-Object : The object written to the pipeline is an instance of the type
    “Microsoft.Office.Interop.Word.ApplicationClass” from the component’s prima
    ry interop assembly. If this type exposes different members than the IDispa
    tch members, scripts written to work with this object might not work if the
     primary interop assembly is not installed.
    At line:1 char:14
    + $a=New-Object <<<< -COM Word.Application -Strict; $a.visible=$true

    Description
    ———–
    This command demonstrates that specifying the Strict parameter causes the New-Object cmdlet to generate a non-terminating error when the COM object that is created uses an interop assembly.

————————– EXAMPLE 4 ————————–

C:\PS>$objshell = New-Object -comobject “Shell.Application”

C:\PS> $objshell | Get-Member

C:\PS> $objshell.ToggleDesktop()

    Description
    ———–
    The command uses the ComObject parameter to create a COM object with the “Shell.Application” ProgID. It stores the resulting object in the $objShell Variable.

The second command pipes the $objShell Variable to the Get-Member cmdlet, which displays the properties and methods of the COM object.

The third command calls the ToggleDesktop method of the object to minimize the open windows on your desktop.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113355
    Compare-Object
    Select-Object
    Sort-Object
    ForEach-Object
    Group-Object
    Measure-Object
    Tee-Object
    Where-Object

cmdlet, Measure, Object

Measure-Object

February 26, 2014 Adam

NAME
Measure-Object

SYNOPSIS
Calculates the numeric properties of objects, and the characters, words, and lines in string objects, such as files of text.

SYNTAX
Measure-Object [-Average] [-Maximum] [-Minimum] [-Sum] [[-Property] <string[]>] [-InputObject <psobject>] [<CommonParameters>]

Measure-Object [-Character] [-IgnoreWhiteSpace] [-Line] [-Word] [[-Property] <string[]>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The Measure-Object cmdlet calculates the property values of certain types of object. Measure-Object performs three types of measurements, depending on the parameters in the command.
The Measure-Object cmdlet performs calculations on the property values of objects. It can count objects and calculate the minimum, maximum, sum, and average of the numeric values. For text objects, it can count and calculate the number of lines, words, and characters.

PARAMETERS
-Average [<SwitchParameter>]
Displays the average value of the specified properties.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Character [<SwitchParameter>]
Counts the number of characters in the input object.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-IgnoreWhiteSpace [<SwitchParameter>]
Ignores white space in word counts and character counts. By default, white space is not ignored.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the objects to be measured. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Line [<SwitchParameter>]
Counts the number of lines in the input object.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Maximum [<SwitchParameter>]
Displays the maximum value of the specified properties.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Minimum [<SwitchParameter>]
Displays the minimum value of the specified properties.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Property <string[]>
Specifies one or more numeric properties to measure. The default is the Count (Length) property of the object.

        Required?                    false
        Position?                    1
        Default value                Count
        Accept pipeline input?     false
        Accept wildcard characters? false

-Sum [<SwitchParameter>]
Displays the sum of the values of the specified properties.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Word [<SwitchParameter>]
Counts the number of words in the input object.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe objects to Measure-Object.

OUTPUTS
GenericMeasureInfo or TextMeasureInfoObject

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>Get-ChildItem | Measure-Object

    Description
    ———–
    This command counts the files and folders in the current directory.

————————– EXAMPLE 2 ————————–

C:\PS>Get-ChildItem | Measure-Object -Property length -Minimum -Maximum -Average

    Description
    ———–
    This command displays the minimum, maximum, and sum of the sizes of all files in the current directory, and the average size of a file in the directory.

————————– EXAMPLE 3 ————————–

C:\PS>Get-Content C:\test.txt | Measure-Object -character -line -word

    Description
    ———–
    This command displays the number of characters, words, and lines in the Text.txt file.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Process | Measure-Object -Property workingset -Minimum -Maximum -Average

    Description
    ———–
    This command displays the minimum, maximum, and average sizes of the working sets of the processes on the computer.

————————– EXAMPLE 5 ————————–

C:\PS>Import-Csv d:\test\serviceyrs.csv | Measure-Object -Property years -Minimum -Maximum -Average

    Description
    ———–
    This command calculates the average years of service of the employees of a company.

The ServiceYrs.csv file is a CSV file that contains the employee number and years of service of each employee. The first row in the table is a header row of “EmpNo, Years”.

When you use Import-Csv to import the file, the result is a PSCustomObject with note properties of EmpNo and Years. You can use Measure-Object to calculate the values of these properties, just like any other property of an object.

————————– EXAMPLE 6 ————————–

C:\PS>Get-ChildItem | Measure-Object -Property psiscontainer -max -Sum -min -Average

    Count    : 126
    Average : 0.0634920634920635
    Sum     : 8
    Maximum : 1
    Minimum : 0
    Property : PSIsContainer

    Description
    ———–
    This example demonstrates the Measure-Object can measure Boolean values. In this case, it uses the PSIsContainer Boolean property to measure the incidence of folders (vs. files) in the current directory.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113349
    Compare-Object
    ForEach-Object
    Group-Object
    New-Object
    Select-Object
    Sort-Object
    Tee-Object
    Where-Object

cmdlet, Group, Object

Group-Object

February 26, 2014 Adam

NAME
Group-Object

SYNOPSIS
Groups objects that contain the same value for specified properties.

SYNTAX
Group-Object [-AsHashTable] [-AsString] [[-Property] <Object[]>] [-CaseSensitive] [-Culture <string>] [-InputObject <psobject>] [-NoElement] [<CommonParameters>]

DESCRIPTION
The Group-Object cmdlet displays objects in groups based on the value of a specified property. Group-Object returns a table with one row for each property value and a column that displays the number of items with that value.

If you specify more than one property, Group-Object first groups them by the values of the first property, and then, within each property group, it groups by the value of the next property.

PARAMETERS
-AsHashTable [<SwitchParameter>]
Returns the group as a hash table. The keys of the hash table are the property values by which the objects are grouped. The values of the hash table are the objects that have that property value.

By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.

        Required?                    false
        Position?                    named
        Default value                GroupInfo object
        Accept pipeline input?     false
        Accept wildcard characters? false

-AsString [<SwitchParameter>]
Converts the hash table keys to strings. By default, the hash table keys are instances of the grouped object. This parameter is valid only when used with the AsHashTable parameter.

        Required?                    false
        Position?                    named
        Default value                GroupInfo objects
        Accept pipeline input?     false
        Accept wildcard characters? false

-CaseSensitive [<SwitchParameter>]
Makes the grouping case-sensitive. Without this parameter, the property values of objects in a group might have different cases.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Culture <string>
Specifies the culture to use when comparing strings.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Specifies the objects to group. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

When you use the InputObject parameter to submit a collection of objects to Group-Object, Group-Object receives one object that represents the collection. As a result, it creates a single group with that object as its member.

To group the objects in a collection, pipe the objects to Group-Object.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-NoElement [<SwitchParameter>]
Omits the members of a group from the results.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Property <Object[]>
Specifies the properties for grouping. The objects are arranged into groups based on the value of the specified property.

The value of the Property parameter can be a new calculated property. To create a calculated, property, create a hash table with an Expression key that specifies a string or script block value.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe any object to Group-Object

OUTPUTS
Microsoft.PowerShell.Commands.GroupInfo or System.Collections.Hashtable
When you use the AsHashTable parameter, Group-Object returns a hash table. Otherwise, it returns a GroupInfo object.

NOTES

You can also use the GroupBy parameter of the formatting cmdlets (such as Format-Table [m2] and Format-List [m2]) to group objects. Unlike Group-Object, which creates a single table with a row for each property value, the GroupBy parameters create a table for each property value with a row for each item that has the property value.

Group-Object does not require that the objects being grouped be of the same Microsoft .NET Framework type. When grouping objects of different .NET Framework types, Group-Object uses the following rules:

— Same Property Names and Types: If the objects have a property with the specified name, and the property values have the same .NET Framework type, the property values are grouped by using the same rules that would be used for objects of the same type.

— Same Property Names, Different Types: If the objects have a property with the specified name, but the property values have a different .NET Framework type in different objects, Group-Object uses the .NET Framework type of the first occurrence of the property as the .NET Framework type for that property group. When an object has a property with a different type, the property value is converted to the type for that group. If the type conversion fails, the object is not included in the group.

— Missing Properties: Objects that do not have a specified property are considered ungroupable. Ungroupable objects appear in the final GroupInfo object output in a group named AutomationNull.Value.

————————– EXAMPLE 1 ————————–

C:\PS>Get-ChildItem *.doc | Group-Object -Property length

    Description
    ———–
    This command gets the files in the current location that have a .doc extension and groups them by size.

————————– EXAMPLE 2 ————————–

C:\PS>Get-ChildItem | Sort-Object -Property extension | Group-Object -Property extension

    Description
    ———–
    This command gets the files in the current location, sorts them by file name extension, and then groups them by file name extension. Note that the files are sorted before they are grouped.

————————– EXAMPLE 3 ————————–

C:\PS>1..35 | Group-Object -Property {$_ % 2},{$_ % 3}

    Description
    ———–
    This example shows how to use script blocks as the value of the Property parameter.

This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3.

————————– EXAMPLE 4 ————————–

C:\PS>$events = Get-Eventlog -logname system -newest 1000

C:\PS> $events | Group-Object -Property eventID

    Count Name                     Group
    —– —-                     —–
     44 Information             {System.Diagnostics.EventLogEntry,
        5 Error                     {System.Diagnostics.EventLogEntry,
        1 Warning                 {System.Diagnostics.EventLogEntry}

    Description
    ———–
    These commands display the 1,000 most recent entries in the System event log, grouped by Event ID.

The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $events Variable.

The second command uses a pipeline operator (|) to send the events in the $events Variable to the Group-Object cmdlet. The command uses the Property parameter to specify that the events should be grouped according to the value of their EventID property.

In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group.

————————– EXAMPLE 5 ————————–

C:\PS>Get-Process | Group-Object -Property priorityclass

    Count Name                Group
    —– —-                —–
     55 Normal             {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia…
        1                     {System.Diagnostics.Process (Idle)}
        3 High                {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D…
        2 BelowNormal         {System.Diagnostics.Process (winperf),

    C:\PS>Get-Process | Group-Object -Property company -NoElement
    Count Name
    —– —-
     55 Normal
        1
        3 High
        2 BelowNormal

    Description
    ———–
    This example demonstrates the effect of the NoElement parameter. These commands group the processes on the computer by priority class.

The first command uses the Get-Process cmdlet to get the processes on the computer. It uses a pipeline operator (|) to send the results to Group-Object, which groups the objects by the value of the PriorityClass property of the process.

The second command is identical to the first, except that it uses the NoElement parameter to eliminate the members of the group from the output. The result is a table with only the count and property value name.

The results are shown in the following sample output.

————————– EXAMPLE 6 ————————–

C:\PS>Get-Eventlog -logname system -newest 1000 | Group-Object -Property {$_.TimeWritten – $_.TimeGenerated}

    Description
    ———–
    This command demonstrates how to provide the value of the Property parameter as a script block.

This command displays the most recent 1,000 entries from the system event log, grouped according to the time between when they were generated and when they were written to the log.

The command uses the Get-EventLog cmdlet to get the event log entries. It uses a pipeline operator (|) to send the entries to the Group-Object cmdlet. The value of the Property parameter is specified as a script block (an expression in braces). The result of evaluating the script block is the time between when the log entry was generated and when it was written to the log. That value is used to group the 1,000 most recent events.

————————– EXAMPLE 7 ————————–

C:\PS>Get-ChildItem | Group-Object extension -NoElement

    Count Name
    —– —-
     21
     82 .txt
        9 .cmd
        5 .log
     12 .xml
        5 .htm
     36 .ps1
        1 .psc1
        3 .exe
        6 .csv
        1 .psd1
        2 .bat

    Description
    ———–
    This command groups the items in the current directory by file name extension. It uses the NoElement parameter to omit the members of the group.

The results are shown in the following sample output.

————————– EXAMPLE 8 ————————–

C:\PS>”a”, “b”, “c”, “c”, “d” | Get-Unique

    a
    b
    c
    d

    C:\PS> “a”, “b”, “c”, “c”, “d” | Group-Object -NoElement | where {$_.Count -gt 1}
    Count Name
    —– —-
        2 c

    C:\PS> Get-Process | Group-Object -Property Name -NoElement | where {$_.count -gt 1}
    Count Name
    —– —-
        2 csrss
        5 svchost
        2 winlogon
        2 wmiprvse

    Description
    ———–
    This example shows how to find the unique and non-unique (repeated) property values in a collection.

The first command gets the unique elements of an array by piping the array to the Get-Unique cmdlet.

The second command gets the non-unique elements of an array. It pipes the array to the Group-Object cmdlet, which groups the objects by value. The resulting groups are piped to the Where-Object cmdlet, which selects objects with groups with more than one member.

The third command shows a practical use for this technique. It uses the same method to find processes on the computer that have the same process name.

The results are shown in the following sample output.

————————– EXAMPLE 9 ————————–

C:\PS>$a = Get-Command get-*, set-* -type cmdlet | Group-Object -Property verb -AsHashTable -AsString

C:\PS> $a

    Name    Value
    —-    —–
    Get     {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession…}
    Set     {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration…}

C:\PS> $a.get

    CommandType     Name                 Definition
    ———–     —-                 ———-
    Cmdlet         Get-PSCallStack     Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction <ActionPrefer…
    Cmdlet         Get-PSBreakpoint     Get-PSBreakpoint [[-Id] <Int32[]>] [-Verbose] [-Debug] [-ErrorA…
    Cmdlet         Get-PSDrive         Get-PSDrive [[-Name] <String[]>] [-Scope <String>] [-PSProvider…
    …

    Description
    ———–
    This example uses the AsHashTable and AsString parameters to return the groups in a hash table, that is, as a collection of key-value pairs.

In the resulting hash table, each property value is a key, and the group elements are the values. Because each key is a property of the hash table object, you can use dot notation to display the values.

The first command gets the Get and Set cmdlets in the session, groups them by verb, returns the groups as a hash table, and saves the hash table in the $a Variable.

The second command displays the hash table in $a. There are two key-value pairs, one for the Get cmdlets and one for the Set cmdlets.

The third command uses dot notation to display the values of the Get key in $a. The values are CmdletInfo object. The AsString parameter does not convert the objects in the groups to strings.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113338

cmdlet, ForEach, Object

ForEach-Object

February 26, 2014 Adam

NAME
ForEach-Object

SYNOPSIS
Performs an operation against each of a set of input objects.

SYNTAX
ForEach-Object [-Process] <ScriptBlock[]> [-Begin <scriptblock>] [-End <scriptblock>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
The ForEach-Object cmdlet performs an operation on each of a set of input objects. The input objects can be piped to the cmdlet or specified by using the InputObject parameter.

The operation to perform is described within a script block that is provided to the cmdlet as the value of the Process parameter. The script block can contain any Windows PowerShell script.

Within the script block, the current input object is represented by the $_ Variable.
In addition to using the script block that describes the operations to be carried out on each input object, you can provide two additional script blocks. One, specified as the value of the Begin parameter, runs before the first input object is processed. The other, specified as the value of the End parameter, runs after the last input object is processed.

The results of the evaluation of all the script blocks, including the ones specified with Begin and End, are passed down the pipeline.

PARAMETERS
-Begin <scriptblock>
Specifies a script block to run before processing any input objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-End <scriptblock>
Specifies a script block to run after processing all input objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-InputObject <psobject>
Accepts an object that the script block specified in the process parameter will act upon. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-Process <ScriptBlock[]>
Specifies the script block that is applied to each incoming object.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe any object to ForEach-Object.

OUTPUTS
System.Management.Automation.PSObject
The objects that ForEach-Object returns are determined by the input.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>30000,56798,12432 | ForEach-Object -Process {$_/1024}

    Description
    ———–
    This command accepts an array of integers, divides each one of them by 1024, and displays the results.

————————– EXAMPLE 2 ————————–

C:\PS>Get-ChildItem C:\ | ForEach-Object -Process { $_.length / 1024 }

    Description
    ———–
    This command retrieves the files and directories in the root of the C: drive, and it returns and displays the size of each of them. The zeros represent directories in which no file size was available.

————————– EXAMPLE 3 ————————–

C:\PS>$events = Get-Eventlog -logname system -newest 1000

C:\PS> $events | ForEach-Object -Begin {Get-Date} -Process {Out-File -filepath events.txt -append -InputObject $_.message} -End {Get-Date}

    Description
    ———–
    This command retrieves the 1000 most recent events from the system log and stores them in the $events Variable. It then pipes the events to the ForEach-Object cmdlet. The Begin parameter displays the current date and time. Next, the Process parameter uses the Out-File cmdlet to create a text file named events.txt and stores the message property of each of the events in that file. Last, the End parameter is used to display the date and time after all of the processing has completed.

————————– EXAMPLE 4 ————————–

C:\PS>Get-Itemproperty -path hkcu:\Network\* | ForEach-Object {Set-Itemproperty -path $_.pspath -name RemotePath -value $_.RemotePath.ToUpper();}

    Description
    ———–
    This command changes the value of the RemotePath Registry entry in all of the subkeys under the HKCU:\Network key to uppercase text. You can use this format to change the form or content of a Registry entry value.

Each subkey in the Network key represents a mapped network drive that will reconnect at logon. The RemotePath entry contains the UNC path of the connected drive. For example, if you map the E: drive to \\Server\Share, there will be an E subkey of HKCU:\Network and the value of the RemotePath Registry entry in the E subkey will be \\Server\Share.

The command uses the Get-ItemProperty cmdlet to get all of the subkeys of the Network key and the Set-ItemProperty cmdlet to change the value of the RemotePath Registry entry in each key. In the Set-ItemProperty command, the path is the value of the PSPath property of the Registry key. (This is a property of the Microsoft .NET Framework object that represents the Registry key; it is not a Registry entry.) The command uses the ToUpper() method of the RemotePath value, which is a string (REG_SZ).

Because Set-ItemProperty is changing the property of each key, the ForEach-Object cmdlet is required to access the property.

RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113300

cmdlet, Compare, Object

Compare-Object

February 26, 2014 Adam

NAME
Compare-Object

SYNOPSIS
Compares two sets of objects.

SYNTAX
Compare-Object [-ReferenceObject] <PSObject[]> [-DifferenceObject] <PSObject[]> [-CaseSensitive] [-Culture <string>] [-ExcludeDifferent] [-IncludeEqual] [-PassThru] [-Property <Object[]>] [-SyncWindow <int>] [<CommonParameters>]

DESCRIPTION
The Compare-Object cmdlet compares two sets of objects. One set of objects is the Reference set, and the other set is the Difference set.

The result of the comparison indicates whether a property value appeared only in the object from the Reference set (indicated by the <= symbol), only in the object from the Difference set (indicated by the => symbol) or, if the IncludeEqual parameter is specified, in both objects (indicated by the == symbol).

PARAMETERS
-CaseSensitive [<SwitchParameter>]
Indicates that comparisons should be case-sensitive.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Culture <string>
Specifies the culture to use for comparisons.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-DifferenceObject <PSObject[]>
Specifies the objects that are compared to the reference objects.

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?     true (ByValue)
        Accept wildcard characters? false

-ExcludeDifferent [<SwitchParameter>]
Displays only the characteristics of compared objects that are equal.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-IncludeEqual [<SwitchParameter>]
Displays characteristics of compared objects that are equal. By default, only characteristics that differ between the reference and difference objects are displayed.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-PassThru [<SwitchParameter>]
Passes the objects that differed to the pipeline. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-Property <Object[]>
Specifies the properties of the reference and difference objects to compare.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-ReferenceObject <PSObject[]>
Objects used as a reference for comparison.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

-SyncWindow <int>
Defines a search region in which an attempt is made to re-synchronize the order if there is no match. The default value is [Int32]::MaxValue.

        Required?                    false
        Position?                    named
        Default value                [Int32]::MaxValue
        Accept pipeline input?     false
        Accept wildcard characters? false

INPUTS
System.Management.Automation.PSObject
You can pipe a DifferenceObject object to Compare-Object.

OUTPUTS
None, or the objects that are different
When you use the PassThru parameter, Compare-Object returns the objects that differed. Otherwise, this cmdlet does not generate any output.

NOTES

————————– EXAMPLE 1 ————————–

C:\PS>Compare-Object -ReferenceObject $(Get-Content C:\test\testfile1.txt) -DifferenceObject $(Get-Content C:\test\testfile2.txt)

    Description
    ———–
    This command compares the contents of two text files. It displays only the lines that appear in one file or in the other file, not lines that appear in both files.

————————– EXAMPLE 2 ————————–

C:\PS>Compare-Object -ReferenceObject $(Get-Content C:\Test\testfile1.txt) -DifferenceObject $(Get-Content C:\Test\testfile2.txt) -IncludeEqual

    Description
    ———–
    This command compares each line of content in two text files. It displays all lines of content from both files, indicating whether each line appears in only Textfile1.txt or Textfile2.txt or whether each line appears in both files.

————————– EXAMPLE 3 ————————–

C:\PS>$processes_before = Get-Process

C:\PS> notepad

C:\PS> $processes_after = Get-Process

C:\PS> Compare-Object -ReferenceObject $processes_before -DifferenceObject $processes_after

    Description
    ———–
    These commands compare two sets of process objects.

The first command uses the Get-Process cmdlet to get the processes on the computer. It stores them in the $processes_before Variable.

The second command starts Notepad.

The third command uses the Get-Process cmdlet again and stores the resulting processes in the $processes_after Variable.

The fourth command uses the Compare-Object cmdlet to compare the two sets of process objects. It displaysthe differences between them, which include the new instance of Notepad.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113286
    Group-Object
    Measure-Object
    Sort-Object
    ForEach-Object
    New-Object
    Select-Object
    Tee-Object
    Where-Object