diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md b/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md index ea4a39226ecb..56b0e6da9afa 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 4/26/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,7 +10,6 @@ title: Group-Object # Group-Object ## SYNOPSIS - Groups objects that contain the same value for specified properties. ## SYNTAX @@ -23,67 +22,102 @@ Group-Object [[-Property] ] [-NoElement] [-AsHashTable] [-AsString] ## 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. +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. +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. ## EXAMPLES -### Example 1 +### Example 1: Group files by extension -```powershell -Get-ChildItem *.doc | Group-Object -Property length -``` +This example recursively gets the files under `$PSHOME` and groups them by file name extension. The +output is sent to the `Sort-Object` cmdlet which sorts them by the count files found for the given +extension. The empty **Name** represents directories. -This command gets the files in the current location that have a .doc extension and groups them by size. - -### Example 2 +This example uses the **NoElement** parameter to omit the members of the group. ```powershell -Get-ChildItem | Sort-Object -Property extension | Group-Object -Property extension +$files = Get-ChildItem -Path $PSHOME -Recurse +$files | Group-Object -Property extension -NoElement | Sort-Object -Property Count -Descending +``` + +```Output +Count Name +----- ---- + 365 .xml + 231 .cdxml + 197 + 169 .ps1xml + 142 .txt + 114 .psd1 + 63 .psm1 + 49 .xsd + 36 .dll + 15 .mfl + 15 .mof +... ``` -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 2: Group integers by odds and evens -### Example 3 +This example shows how to use script blocks as the value of the **Property** parameter. + +This command displays the integers from 1 to 20, grouped by odds and even. ```powershell -1..35 | Group-Object -Property {$_ % 2},{$_ % 3} +1..20 | Group-Object -Property {$_ % 2} +``` + +```Output +Count Name Group +----- ---- ----- + 10 1 {1, 3, 5, 7, 9, 11, 13, 15, 17, 19} + 10 0 {2, 4, 6, 8, 10, 12, 14, 16, 18, 20} ``` -This example shows how to use script blocks as the value of the Property parameter. +### Example 3: Group event log events by EntryType -This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3. +These commands display the 1,000 most recent entries in the System event log, grouped by **EntryType**. -### Example 4 +In the output, the **Count** column represents the number of entries in each group, the **Name** +column represents the **EventType** values that define a group, and the **Group** column represents +the objects in each group. +```powershell +Get-WinEvent -LogName System -MaxEvents 1000 | Group-Object -Property LevelDisplayName ``` -PS> $events = get-eventlog -logname system -newest 1000 -PS> $events | group-object -property eventID -Count Name Group ------ ---- ----- -44 Information {System.Diagnostics.EventLogEntry, -5 Error {System.Diagnostics.EventLogEntry, -1 Warning {System.Diagnostics.EventLogEntry} +```Output +Count Name Group +----- ---- ----- + 153 Error {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 722 Information {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 125 Warning {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… ``` -These commands display the 1,000 most recent entries in the System event log, grouped by Event ID. +### Example 4: Group processes by priority class -The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $events variable. +This example demonstrates the effect of the **NoElement** parameter. +These commands group the processes on the computer by priority class. -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. +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. -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. +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. -### Example 5 +The results are shown in the following sample output. ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass +Get-Process | Group-Object -Property PriorityClass +``` +```Output Count Name Group ----- ---- ----- 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... @@ -93,8 +127,10 @@ Count Name Group ``` ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement +Get-Process | Group-Object -Property PriorityClass -NoElement +``` +```Output Count Name ----- ---- 55 Normal @@ -103,110 +139,60 @@ Count Name 2 BelowNormal ``` -This example demonstrates the effect of the NoElement parameter. -These commands group the processes on the computer by priority class. +### Example 5: Group processes by name -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 +The following example uses `Group-Object` to multiple instances of processes running on the local +computer. ```powershell -Get-EventLog -LogName system -Newest 1000 | Group-Object -Property {$_.TimeWritten - $_.TimeGenerated} -``` - -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 - -``` -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 -``` - -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 - +Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} ``` -PS> "a", "b", "c", "c", "d" | get-unique -a -b -c -d - -PS> "a", "b", "c", "c", "d" | group-object -noelement | Where-Object {$_.Count -gt 1} - -Count Name ------ ---- -2 c - -PS> get-process | group-object -property Name -noelement | Where-Object {$_.count -gt 1} +```Output Count Name ----- ---- -2 csrss -5 svchost -2 winlogon -2 wmiprvse +2 csrss +5 svchost +2 winlogon +2 wmiprvse ``` -This example shows how to find the unique and non-unique (repeated) property values in a collection. +### Example 8: Group objects in a hash table -The first command gets the unique elements of an array by piping the array to the Get-Unique cmdlet. +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. -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. +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 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 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 results are shown in the following sample output. +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. -### Example 9 +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. +```powershell +$A = Get-Command get-*, set-* -CommandType cmdlet | Group-Object -Property verb -AsHashTable -AsString +$A ``` -PS> $a = get-command get-*, set-* -type cmdlet | group-object -property verb -ashashtable -asstring -PS> $a +```Output Name Value ---- ----- Get {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession...} Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} +``` -PS> $a.get +```powershell +$A.get +``` +```Output CommandType Name Definition ----------- ---- ---------- Cmdlet Get-PSCallStack Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction ] [-Scope ] [-NoElement] [-AsHashTable] [-AsString] ``` ## 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. +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. ## EXAMPLES -### Example 1 -``` -PS C:\> get-childitem *.doc | group-object -property length -``` +### Example 1: Group files by extension + +This example recursively gets the files under `$PSHOME` and groups them by file name extension. The +output is sent to the `Sort-Object` cmdlet which sorts them by the count files found for the given +extension. The empty **Name** represents directories. -This command gets the files in the current location that have a .doc extension and groups them by size. +This example uses the **NoElement** parameter to omit the members of the group. -### Example 2 +```powershell +$files = Get-ChildItem -Path $PSHOME -Recurse +$files | Group-Object -Property extension -NoElement | Sort-Object -Property Count -Descending ``` -PS C:\> get-childitem | sort-object -property extension | group-object -property extension + +```Output +Count Name +----- ---- + 365 .xml + 231 .cdxml + 197 + 169 .ps1xml + 142 .txt + 114 .psd1 + 63 .psm1 + 49 .xsd + 36 .dll + 15 .mfl + 15 .mof +... ``` -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 2: Group integers by odds and evens + +This example shows how to use script blocks as the value of the **Property** parameter. -### Example 3 +This command displays the integers from 1 to 20, grouped by odds and even. + +```powershell +1..20 | Group-Object -Property {$_ % 2} ``` -PS C:\> 1..35 | group-object -property {$_ % 2},{$_ % 3} + +```Output +Count Name Group +----- ---- ----- + 10 1 {1, 3, 5, 7, 9, 11, 13, 15, 17, 19} + 10 0 {2, 4, 6, 8, 10, 12, 14, 16, 18, 20} ``` -This example shows how to use script blocks as the value of the Property parameter. +### Example 3: Group event log events by EntryType -This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3. +These commands display the 1,000 most recent entries in the System event log, grouped by **EntryType**. -### Example 4 +In the output, the **Count** column represents the number of entries in each group, the **Name** +column represents the **EventType** values that define a group, and the **Group** column represents +the objects in each group. + +```powershell +Get-WinEvent -LogName System -MaxEvents 1000 | Group-Object -Property LevelDisplayName ``` -PS C:\> $events = get-eventlog -logname system -newest 1000 -PS C:\> $events | group-object -property eventID -Count Name Group ------ ---- ----- -44 Information {System.Diagnostics.EventLogEntry, -5 Error {System.Diagnostics.EventLogEntry, -1 Warning {System.Diagnostics.EventLogEntry} +```Output +Count Name Group +----- ---- ----- + 153 Error {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 722 Information {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 125 Warning {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… ``` -These commands display the 1,000 most recent entries in the System event log, grouped by Event ID. +### Example 4: Group processes by priority class -The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $events variable. +This example demonstrates the effect of the **NoElement** parameter. +These commands group the processes on the computer by priority class. -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. +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. -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. +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 5 ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass +Get-Process | Group-Object -Property PriorityClass +``` +```Output Count Name Group ----- ---- ----- 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... @@ -87,8 +127,10 @@ Count Name Group ``` ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement +Get-Process | Group-Object -Property PriorityClass -NoElement +``` +```Output Count Name ----- ---- 55 Normal @@ -97,106 +139,60 @@ Count Name 2 BelowNormal ``` -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 -``` -PS C:\> get-eventlog -logname system -newest 1000 | group-object -property {$_.TimeWritten - $_.TimeGenerated} -``` - -This command demonstrates how to provide the value of the Property parameter as a script block. +### Example 5: Group processes by name -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 following example uses `Group-Object` to multiple instances of processes running on the local +computer. -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 +```powershell +Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} ``` -PS C:\> get-childitem | group-object extension -noelement +```Output 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 +2 csrss +5 svchost +2 winlogon +2 wmiprvse ``` -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. +### Example 8: Group objects in a hash table -The results are shown in the following sample output. - -### Example 8 -``` -PS C:\> "a", "b", "c", "c", "d" | get-unique -a -b -c -d +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. -PS C:\> "a", "b", "c", "c", "d" | group-object -noelement | where {$_.Count -gt 1} - -Count Name ------ ---- -2 c - -PS C:\> get-process | group-object -property Name -noelement | where {$_.count -gt 1} - -Count Name ------ ---- -2 csrss -5 svchost -2 winlogon -2 wmiprvse -``` - -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. +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 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 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 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 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 results are shown in the following sample output. +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. -### Example 9 +```powershell +$A = Get-Command get-*, set-* -CommandType cmdlet | Group-Object -Property verb -AsHashTable -AsString +$A ``` -PS C:\> $a = get-command get-*, set-* -type cmdlet | group-object -property verb -ashashtable -asstring -PS C:\> $a +```Output Name Value ---- ----- Get {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession...} Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} +``` -PS C:\> $a.get +```powershell +$A.get +``` +```Output CommandType Name Definition ----------- ---- ---------- Cmdlet Get-PSCallStack Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction ] [-Scope ] [-NoElement] [-AsHashTable] [-AsString] ## 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. +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. +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. ## EXAMPLES -### Example 1: Group files by size +### Example 1: Group files by extension -``` -PS C:\> Get-ChildItem *.doc | Group-Object -Property length -``` +This example recursively gets the files under `$PSHOME` and groups them by file name extension. The +output is sent to the `Sort-Object` cmdlet which sorts them by the count files found for the given +extension. The empty **Name** represents directories. -This command gets the files in the current location that have a .doc extension and groups them by size. - -### Example 2: Group files by extension +This example uses the **NoElement** parameter to omit the members of the group. +```powershell +$files = Get-ChildItem -Path $PSHOME -Recurse +$files | Group-Object -Property extension -NoElement | Sort-Object -Property Count -Descending ``` -PS C:\> Get-ChildItem | Sort-Object -Property extension | Group-Object -Property extension + +```Output +Count Name +----- ---- + 365 .xml + 231 .cdxml + 197 + 169 .ps1xml + 142 .txt + 114 .psd1 + 63 .psm1 + 49 .xsd + 36 .dll + 15 .mfl + 15 .mof +... ``` -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 2: Group integers by odds and evens -### Example 3: Group integers by remainder +This example shows how to use script blocks as the value of the **Property** parameter. +This command displays the integers from 1 to 20, grouped by odds and even. + +```powershell +1..20 | Group-Object -Property {$_ % 2} ``` -PS C:\> 1..35 | Group-Object -Property {$_ % 2},{$_ % 3} + +```Output +Count Name Group +----- ---- ----- + 10 1 {1, 3, 5, 7, 9, 11, 13, 15, 17, 19} + 10 0 {2, 4, 6, 8, 10, 12, 14, 16, 18, 20} ``` -This example shows how to use script blocks as the value of the *Property* parameter. +### Example 3: Group event log events by EntryType -This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3. +These commands display the 1,000 most recent entries in the System event log, grouped by **EntryType**. -### Example 4: Group event log events by ID +In the output, the **Count** column represents the number of entries in each group, the **Name** +column represents the **EventType** values that define a group, and the **Group** column represents +the objects in each group. +```powershell +Get-WinEvent -LogName System -MaxEvents 1000 | Group-Object -Property LevelDisplayName ``` -PS C:\> $Events = Get-EventLog -LogName "system" -Newest 1000 -PS C:\> $Events | Group-Object -Property eventID -Count Name Group ------ ---- ----- -44 Information {System.Diagnostics.EventLogEntry, -5 Error {System.Diagnostics.EventLogEntry, -1 Warning {System.Diagnostics.EventLogEntry} + +```Output +Count Name Group +----- ---- ----- + 153 Error {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 722 Information {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 125 Warning {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… ``` -These commands display the 1,000 most recent entries in the System event log, grouped by Event ID. +### Example 4: Group processes by priority class -The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $Events variable. +This example demonstrates the effect of the **NoElement** parameter. +These commands group the processes on the computer by priority class. -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. +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. -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. +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. -### Example 5: Group processes by priority class +The results are shown in the following sample output. ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass +Get-Process | Group-Object -Property PriorityClass +``` +```Output Count Name Group ----- ---- ----- 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... @@ -91,8 +127,10 @@ Count Name Group ``` ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement +Get-Process | Group-Object -Property PriorityClass -NoElement +``` +```Output Count Name ----- ---- 55 Normal @@ -101,69 +139,16 @@ Count Name 2 BelowNormal ``` -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: Group events by time - -``` -PS C:\> Get-EventLog -LogName system -Newest 1000 | Group-Object -Property {$_.TimeWritten - $_.TimeGenerated} -``` - -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 5: Group processes by name -### Example 7: Group items by file name extension +The following example uses `Group-Object` to multiple instances of processes running on the local +computer. -``` -PS C:\> 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 +```powershell +Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} ``` -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: Group objects by value - -``` -PS C:\> "a", "b", "c", "c", "d" | Get-Unique -a -b -c -d PS C:\> "a", "b", "c", "c", "d" | Group-Object -NoElement | Where {$_.Count -gt 1} -Count Name ------ ---- -2 c PS C:\> Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} +```Output Count Name ----- ---- 2 csrss @@ -172,28 +157,42 @@ Count Name 2 wmiprvse ``` -This example shows how to find the unique and non-unique (repeated) property values in a collection. +### Example 8: Group objects in a hash table -The first command gets the unique elements of an array by piping the array to the Get-Unique cmdlet. +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. -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. +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 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 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 results are shown in the following sample output. +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. -### Example 9: Group objects in a hash table +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. +```powershell +$A = Get-Command get-*, set-* -CommandType cmdlet | Group-Object -Property verb -AsHashTable -AsString +$A ``` -PS C:\> $A = Get-Command get-*, set-* -Type cmdlet | Group-Object -Property verb -AsHashTable -AsString -PS C:\> $A + +```Output Name Value ---- ----- Get {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession...} -Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} PS C:\> $A.get +Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} +``` + +```powershell +$A.get +``` + +```Output CommandType Name Definition ----------- ---- ---------- Cmdlet Get-PSCallStack Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction ] [-Scope ] [ ``` ## 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. +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. ## EXAMPLES -### Example 1: Group files by size -``` -PS C:\> Get-ChildItem *.doc | Group-Object -Property length -``` +### Example 1: Group files by extension + +This example recursively gets the files under `$PSHOME` and groups them by file name extension. The +output is sent to the `Sort-Object` cmdlet which sorts them by the count files found for the given +extension. The empty **Name** represents directories. -This command gets the files in the current location that have a .doc extension and groups them by size. +This example uses the **NoElement** parameter to omit the members of the group. -### Example 2: Group files by extension +```powershell +$files = Get-ChildItem -Path $PSHOME -Recurse +$files | Group-Object -Property extension -NoElement | Sort-Object -Property Count -Descending ``` -PS C:\> Get-ChildItem | Sort-Object -Property extension | Group-Object -Property extension + +```Output +Count Name +----- ---- + 365 .xml + 231 .cdxml + 197 + 169 .ps1xml + 142 .txt + 114 .psd1 + 63 .psm1 + 49 .xsd + 36 .dll + 15 .mfl + 15 .mof +... ``` -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 2: Group integers by odds and evens -### Example 3: Group integers by remainder +This example shows how to use script blocks as the value of the **Property** parameter. + +This command displays the integers from 1 to 20, grouped by odds and even. + +```powershell +1..20 | Group-Object -Property {$_ % 2} ``` -PS C:\> 1..35 | Group-Object -Property {$_ % 2},{$_ % 3} + +```Output +Count Name Group +----- ---- ----- + 10 1 {1, 3, 5, 7, 9, 11, 13, 15, 17, 19} + 10 0 {2, 4, 6, 8, 10, 12, 14, 16, 18, 20} ``` -This example shows how to use script blocks as the value of the *Property* parameter. +### Example 3: Group event log events by EntryType + +These commands display the 1,000 most recent entries in the System event log, grouped by **EntryType**. -This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3. +In the output, the **Count** column represents the number of entries in each group, the **Name** +column represents the **EventType** values that define a group, and the **Group** column represents +the objects in each group. -### Example 4: Group event log events by ID +```powershell +Get-WinEvent -LogName System -MaxEvents 1000 | Group-Object -Property LevelDisplayName ``` -PS C:\> $Events = Get-EventLog -LogName "system" -Newest 1000 -PS C:\> $Events | Group-Object -Property eventID -Count Name Group ------ ---- ----- -44 Information {System.Diagnostics.EventLogEntry, -5 Error {System.Diagnostics.EventLogEntry, -1 Warning {System.Diagnostics.EventLogEntry} + +```Output +Count Name Group +----- ---- ----- + 153 Error {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 722 Information {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 125 Warning {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… ``` -These commands display the 1,000 most recent entries in the System event log, grouped by Event ID. +### Example 4: Group processes by priority class -The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $Events variable. +This example demonstrates the effect of the **NoElement** parameter. +These commands group the processes on the computer by priority class. -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. +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. -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. +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 5: Group processes by priority class ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass +Get-Process | Group-Object -Property PriorityClass +``` +```Output Count Name Group ----- ---- ----- 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... @@ -86,8 +127,10 @@ Count Name Group ``` ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement +Get-Process | Group-Object -Property PriorityClass -NoElement +``` +```Output Count Name ----- ---- 55 Normal @@ -96,66 +139,16 @@ Count Name 2 BelowNormal ``` -This example demonstrates the effect of the *NoElement* parameter. -These commands group the processes on the computer by priority class. +### Example 5: Group processes by name -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 following example uses `Group-Object` to multiple instances of processes running on the local +computer. -The results are shown in the following sample output. - -### Example 6: Group events by time -``` -PS C:\> Get-EventLog -LogName system -Newest 1000 | Group-Object -Property {$_.TimeWritten - $_.TimeGenerated} -``` - -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: Group items by file name extension -``` -PS C:\> 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 +```powershell +Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} ``` -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: Group objects by value -``` -PS C:\> "a", "b", "c", "c", "d" | Get-Unique -a -b -c -d PS C:\> "a", "b", "c", "c", "d" | Group-Object -NoElement | Where {$_.Count -gt 1} -Count Name ------ ---- -2 c PS C:\> Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} +```Output Count Name ----- ---- 2 csrss @@ -164,27 +157,42 @@ Count Name 2 wmiprvse ``` -This example shows how to find the unique and non-unique (repeated) property values in a collection. +### Example 8: Group objects in a hash table + +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. -The first command gets the unique elements of an array by piping the array to the Get-Unique cmdlet. +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 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 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 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 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 results are shown in the following sample output. +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. -### Example 9: Group objects in a hash table +```powershell +$A = Get-Command get-*, set-* -CommandType cmdlet | Group-Object -Property verb -AsHashTable -AsString +$A ``` -PS C:\> $A = Get-Command get-*, set-* -Type cmdlet | Group-Object -Property verb -AsHashTable -AsString -PS C:\> $A + +```Output Name Value ---- ----- Get {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession...} -Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} PS C:\> $A.get +Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} +``` + +```powershell +$A.get +``` + +```Output CommandType Name Definition ----------- ---- ---------- Cmdlet Get-PSCallStack Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction ] [-Scope ] [ ## 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. +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. +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. ## EXAMPLES -### Example 1: Group files by size +### Example 1: Group files by extension -``` -PS C:\> Get-ChildItem *.doc | Group-Object -Property length -``` +This example recursively gets the files under `$PSHOME` and groups them by file name extension. The +output is sent to the `Sort-Object` cmdlet which sorts them by the count files found for the given +extension. The empty **Name** represents directories. -This command gets the files in the current location that have a .doc extension and groups them by size. - -### Example 2: Group files by extension +This example uses the **NoElement** parameter to omit the members of the group. +```powershell +$files = Get-ChildItem -Path $PSHOME -Recurse +$files | Group-Object -Property extension -NoElement | Sort-Object -Property Count -Descending ``` -PS C:\> Get-ChildItem | Sort-Object -Property extension | Group-Object -Property extension + +```Output +Count Name +----- ---- + 365 .xml + 231 .cdxml + 197 + 169 .ps1xml + 142 .txt + 114 .psd1 + 63 .psm1 + 49 .xsd + 36 .dll + 15 .mfl + 15 .mof +... ``` -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 2: Group integers by odds and evens -### Example 3: Group integers by remainder +This example shows how to use script blocks as the value of the **Property** parameter. +This command displays the integers from 1 to 20, grouped by odds and even. + +```powershell +1..20 | Group-Object -Property {$_ % 2} ``` -PS C:\> 1..35 | Group-Object -Property {$_ % 2},{$_ % 3} + +```Output +Count Name Group +----- ---- ----- + 10 1 {1, 3, 5, 7, 9, 11, 13, 15, 17, 19} + 10 0 {2, 4, 6, 8, 10, 12, 14, 16, 18, 20} ``` -This example shows how to use script blocks as the value of the *Property* parameter. +### Example 3: Group event log events by EntryType -This command displays the integers from 1 to 35, grouped by the remainder left when they are divided by 2 or 3. +These commands display the 1,000 most recent entries in the System event log, grouped by **EntryType**. -### Example 4: Group event log events by ID +In the output, the **Count** column represents the number of entries in each group, the **Name** +column represents the **EventType** values that define a group, and the **Group** column represents +the objects in each group. +```powershell +Get-WinEvent -LogName System -MaxEvents 1000 | Group-Object -Property LevelDisplayName ``` -PS C:\> $Events = Get-EventLog -LogName "system" -Newest 1000 -PS C:\> $Events | Group-Object -Property eventID -Count Name Group ------ ---- ----- -44 Information {System.Diagnostics.EventLogEntry, -5 Error {System.Diagnostics.EventLogEntry, -1 Warning {System.Diagnostics.EventLogEntry} + +```Output +Count Name Group +----- ---- ----- + 153 Error {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 722 Information {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… + 125 Warning {System.Diagnostics.Eventing.Reader.EventLogRecord, System.Diagnostics.… ``` -These commands display the 1,000 most recent entries in the System event log, grouped by Event ID. +### Example 4: Group processes by priority class -The first command uses the Get-EventLog cmdlet to retrieve the events and the assignment operator (=) to save them in the $Events variable. +This example demonstrates the effect of the **NoElement** parameter. +These commands group the processes on the computer by priority class. -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. +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. -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. +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. -### Example 5: Group processes by priority class +The results are shown in the following sample output. ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass +Get-Process | Group-Object -Property PriorityClass +``` +```Output Count Name Group ----- ---- ----- 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... @@ -91,8 +127,10 @@ Count Name Group ``` ```powershell -PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement +Get-Process | Group-Object -Property PriorityClass -NoElement +``` +```Output Count Name ----- ---- 55 Normal @@ -101,69 +139,16 @@ Count Name 2 BelowNormal ``` -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: Group events by time - -``` -PS C:\> Get-EventLog -LogName system -Newest 1000 | Group-Object -Property {$_.TimeWritten - $_.TimeGenerated} -``` - -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. +### Example 5: Group processes by name -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. +The following example uses `Group-Object` to multiple instances of processes running on the local +computer. -### Example 7: Group items by file name extension - -``` -PS C:\> 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 +```powershell +Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} ``` -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: Group objects by value - -``` -PS C:\> "a", "b", "c", "c", "d" | Get-Unique -a -b -c -d PS C:\> "a", "b", "c", "c", "d" | Group-Object -NoElement | Where {$_.Count -gt 1} -Count Name ------ ---- -2 c PS C:\> Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1} +```Output Count Name ----- ---- 2 csrss @@ -172,28 +157,42 @@ Count Name 2 wmiprvse ``` -This example shows how to find the unique and non-unique (repeated) property values in a collection. +### Example 8: Group objects in a hash table -The first command gets the unique elements of an array by piping the array to the Get-Unique cmdlet. +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. -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. +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 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 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 results are shown in the following sample output. +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. -### Example 9: Group objects in a hash table +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. +```powershell +$A = Get-Command get-*, set-* -CommandType cmdlet | Group-Object -Property verb -AsHashTable -AsString +$A ``` -PS C:\> $A = Get-Command get-*, set-* -Type cmdlet | Group-Object -Property verb -AsHashTable -AsString -PS C:\> $A + +```Output Name Value ---- ----- Get {Get-PSCallStack, Get-PSBreakpoint, Get-PSDrive, Get-PSSession...} -Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} PS C:\> $A.get +Set {Set-Service, Set-StrictMode, Set-PSDebug, Set-PSSessionConfiguration...} +``` + +```powershell +$A.get +``` + +```Output CommandType Name Definition ----------- ---- ---------- Cmdlet Get-PSCallStack Get-PSCallStack [-Verbose] [-Debug] [-ErrorAction ] [-Scope