Partilhar via

Group-Object

Módulo:
Microsoft.PowerShell.Utility Module

Agrupa objetos que contêm o mesmo valor para propriedades especificadas.

Sintaxe

Default (Predefinição) 

Group-Object
    [[-Property] <Object[]>]
    [-NoElement]
    [-AsHashTable]
    [-AsString]
    [-InputObject <PSObject>]
    [-Culture <String>]
    [-CaseSensitive]
    [<CommonParameters>]

Description

O cmdlet Group-Object exibe objetos em grupos com base no valor de uma propriedade especificada. Group-Object retorna uma tabela com uma linha para cada valor de propriedade e uma coluna que exibe o número de itens com esse valor.

Se você especificar mais de uma propriedade, Group-Object primeiro as agrupará pelos valores da primeira propriedade e, em seguida, dentro de cada grupo de propriedades, agrupará pelo valor da próxima propriedade.

Exemplos

Exemplo 1: Agrupar arquivos por extensão

Este exemplo obtém recursivamente os arquivos em $PSHOME e os agrupa por extensão de nome de arquivo. A saída é enviada para o cmdlet Sort-Object, que as classifica pelos arquivos de contagem encontrados para determinada extensão. O Nome vazio representa diretórios.

Este exemplo usa o parâmetro NoElement para omitir os membros do grupo.

$files = Get-ChildItem -Path $PSHOME -Recurse
$files | Group-Object -Property extension -NoElement | Sort-Object -Property Count -Descending

Count Name
----- ----
  365 .xml
  231 .cdxml
  197
  169 .ps1xml
  142 .txt
  114 .psd1
   63 .psm1
   49 .xsd
   36 .dll
   15 .mfl
   15 .mof
...

Exemplo 2: Agrupar inteiros por odds e pares

Este exemplo mostra como usar blocos de script como o valor do parâmetro Property .

Este comando exibe os inteiros de 1 a 20, agrupados por ímpares e pares.

1..20 | Group-Object -Property {$_ % 2}

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}

Exemplo 3: Agrupar eventos de log de eventos por EntryType

Esses comandos exibem as 1.000 entradas mais recentes no log de eventos do sistema, agrupadas por EntryType.

Na saída, a coluna Contagem de representa o número de entradas em cada grupo, a coluna Nome representa os valores EventType que definem um grupo e a coluna Grupo representa os objetos em cada grupo.

Get-WinEvent -LogName System -MaxEvents 1000 | Group-Object -Property LevelDisplayName

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.�

Exemplo 4: Agrupar processos por classe de prioridade

Este exemplo demonstra o efeito do parâmetro NoElement. Esses comandos agrupam os processos no computador por classe de prioridade.

O primeiro comando usa o cmdlet Get-Process para obter os processos no computador. Ele usa um operador de pipeline | para enviar os resultados para Group-Object, que agrupa os objetos pelo valor da propriedade PriorityClass do processo.

O segundo comando é idêntico ao primeiro, exceto que ele usa o parâmetro NoElement para eliminar os membros do grupo da saída. O resultado é uma tabela com apenas a contagem e o nome do valor da propriedade.

Os resultados são mostrados na saída de exemplo a seguir.

Get-Process | Group-Object -Property PriorityClass

Count Name         Group
----- ----         -----
   55 Normal       {System.Diagnostics.Process (AdtAgent), System.Diagnosti...
    1              {System.Diagnostics.Process (Idle)}
    3 High         {System.Diagnostics.Process (Newproc), System.Diagnostic...
    2 BelowNormal  {System.Diagnostics.Process (winperf),

Get-Process | Group-Object -Property PriorityClass -NoElement

Count Name
----- ----
   55 Normal
    1
    3 High
    2 BelowNormal

Exemplo 5: Agrupar processos por nome

O exemplo a seguir usa Group-Object a várias instâncias de processos em execução no computador local.

Get-Process | Group-Object -Property Name -NoElement | Where {$_.count -gt 1}

Count Name
----- ----
2     csrss
5     svchost
2     winlogon
2     wmiprvse

Exemplo 8: Agrupar objetos em uma tabela de hash

Este exemplo usa os parâmetros AsHashTable e AsString para retornar os grupos em uma tabela de hash, ou seja, como uma coleção de pares chave-valor.

Na tabela de hash resultante, cada valor de propriedade é uma chave e os elementos do grupo são os valores. Como cada chave é uma propriedade do objeto de tabela de hash, você pode usar a notação de pontos para exibir os valores.

O primeiro comando obtém os cmdlets Get e Set na sessão, agrupa-os por verbo, retorna os grupos como uma tabela de hash e salva a tabela de hash na variável $A.

O segundo comando exibe a tabela de hash em $A. Há dois pares chave-valor, um para os cmdlets Get e outro para os cmdlets Set.

O terceiro comando usa notação de pontos para exibir os valores da chave Get no $A. Os valores são objeto CmdletInfo. O parâmetro AsString não converte os objetos nos grupos em cadeias de caracteres.

$A = Get-Command get-*, set-* -CommandType cmdlet | Group-Object -Property verb -AsHashTable -AsString
$A

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

$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...
...

Parâmetros

-AsHashTable

Indica que esse cmdlet retorna o grupo como uma tabela de hash. As chaves da tabela de hash são os valores de propriedade pelos quais os objetos são agrupados. Os valores da tabela de hash são os objetos que têm esse valor de propriedade.

Por si só, o parâmetro AsHashTable retorna cada tabela de hash na qual cada chave é uma instância do objeto agrupado. Quando usado com o parâmetro AsString, as chaves na tabela de hash são strings.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:AHT

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-AsString

Indica que esse cmdlet converte as chaves da tabela de hash em cadeias de caracteres. Por padrão, as chaves da tabela de hash são instâncias do objeto agrupado. Este parâmetro é válido somente quando usado com o parâmetro AsHashTable.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-CaseSensitive

Indica que esse cmdlet diferencia maiúsculas de minúsculas do agrupamento. Sem esse parâmetro, os valores de propriedade de objetos em um grupo podem ter casos diferentes.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Culture

Especifica a cultura a ser usada ao comparar cadeias de caracteres.

Propriedades dos parâmetros

Tipo:String
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-InputObject

Especifica os objetos a serem agrupados. Insira uma variável que contenha os objetos ou digite um comando ou expressão que obtenha os objetos.

Quando você usa o parâmetro InputObject para enviar uma coleção de objetos para Group-Object, Group-Object recebe um objeto que representa a coleção. Como resultado, ele cria um único grupo com esse objeto como seu membro.

Para agrupar os objetos em uma coleção, canalize os objetos para Group-Object.

Propriedades dos parâmetros

Tipo:PSObject
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-NoElement

Indica que esse cmdlet omite os membros de um grupo dos resultados.

Propriedades dos parâmetros

Tipo:SwitchParameter
Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Property

Especifica as propriedades para agrupamento. Os objetos são organizados em grupos com base no valor da propriedade especificada.

O valor do parâmetro Property pode ser uma nova propriedade calculada. Para criar uma propriedade calculada, crie uma tabela de hash com uma chave Expression que especifique um valor de cadeia de caracteres ou bloco de script.

Propriedades dos parâmetros

Tipo:

Object[]

Default value:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Position:0
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

PSObject

Você pode canalizar qualquer objeto para Group-Object.

Saídas

Microsoft.PowerShell.Commands.GroupInfo or System.Collections.Hashtable

Quando você usa o parâmetro AsHashTable, Group-Object retorna uma tabela de hash. Caso contrário, ele retorna um objeto GroupInfo.

Notas

  • Você também pode usar o parâmetro GroupBy dos cmdlets de formatação (como Format-Table e Format-List) para agrupar objetos. Ao contrário Group-Object, que cria uma única tabela com uma linha para cada valor de propriedade, os parâmetros GroupBy criam uma tabela para cada valor de propriedade com uma linha para cada item que tem o valor da propriedade.

    Group-Object não requer que os objetos que estão sendo agrupados sejam do mesmo tipo do Microsoft .NET Framework. Ao agrupar objetos de diferentes tipos do .NET Framework, Group-Object usa as seguintes regras:

    • Mesmos nomes e tipos de propriedade. Se os objetos tiverem uma propriedade com o nome especificado e os valores de propriedade tiverem o mesmo tipo .NET Framework, os valores de propriedade serão agrupados usando as mesmas regras que seriam usadas para objetos do mesmo tipo.

    • Mesmos nomes de propriedade, tipos diferentes. Se os objetos tiverem uma propriedade com o nome especificado, mas os valores de propriedade tiverem um tipo diferente do .NET Framework em objetos diferentes, Group-Object usará o tipo .NET Framework da primeira ocorrência da propriedade como o tipo .NET Framework para esse grupo de propriedades. Quando um objeto tem uma propriedade com um tipo diferente, o valor da propriedade é convertido para o tipo para esse grupo. Se a conversão de tipo falhar, o objeto não será incluído no grupo.

    • Propriedades ausentes. Os objetos que não têm uma propriedade especificada são considerados não agrupáveis. Os objetos não agrupáveis aparecem no final GroupInfo saída de objeto em um grupo chamado AutomationNull.Value.