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

Sintaxe

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

Descrição

O cmdlet Group-Object exibe objetos em grupos baseado 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 aquele valor.

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

Parâmetros

-AsHashTable

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 o objeto que possuem 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 da tabela de hash são cadeias de caracteres.

Necessário?

false

Posição?

named

Valor padrão

GroupInfo object

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-AsString

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

Necessário?

false

Posição?

named

Valor padrão

GroupInfo objects

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-CaseSensitive

Faz o agrupamento diferenciar maiúsculas e minúsculas. Sem este parâmetro, os valores de propriedade de objetos de um grupo poderiam ter maiúsculas e minúsculas.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Culture <string>

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

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-InputObject <psobject>

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

Ao usar 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, cria um único grupo com aquele objeto como seu membro.

Para agrupar os objetos de uma coleção, envie-os para Group-Object.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

true (ByValue)

Aceitar caracteres curinga?

false

-NoElement

Omite os membros de um grupo dos resultados.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Property <Object[]>

Especifica as propriedades a serem agrupadas. 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 especifica um valor de cadeia de caracteres ou bloco de script.

Necessário?

false

Posição?

1

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas

System.Management.Automation.PSObject

Você pode canalizar qualquer objeto para Group-Object

Saídas

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

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

Observações

Você também pode usar o parâmetro GroupBy dos cmdlets de formatação (como Format-Table [m2] e Format-List [m2]) para agrupar objetos. Diferentemente de Group-Object, que cria uma única tabela com uma linha para 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 de propriedade.

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

-- Nomes e tipos de propriedade iguais: 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 com base nas mesmas regras que seriam usadas para objetos do mesmo tipo.

-- Nomes de propriedade iguais, tipos diferentes: se os objetos tiverem uma propriedade com o nome especificado, mas os valores de propriedade tiverem um tipo .NET Framework diferente em objetos diferentes, Group-Object usará o tipo .NET Framework da primeira ocorrência da propriedade como o tipo .NET Framework referente àquele grupo de propriedades. Quando um objeto tiver uma propriedade de tipo diferente, o valor da propriedade será convertido para o tipo do grupo. Se a conversão de tipos falhar, o objeto não será incluído no grupo.

-- Missing Properties: os objetos que não têm uma propriedade especificada são considerados não agrupáveis. Os objetos não agrupáveis aparecem na saída do objeto GroupInfo em um grupo nomeado AutomationNull.Value.

Exemplo 1

C:\PS>get-childitem *.doc | group-object -property length

Descrição
-----------
Este comando obtém os arquivos do local atual que tenham a extensão .doc e os agrupa por tamanho.

Exemplo 2

C:\PS>get-childitem | sort-object -property extension | group-object -property extension

Descrição
-----------
Esse comando obtém os arquivos do local atual, classifica-os por extensão de nome de arquivo e, depois, agrupa-os por extensão de nome de arquivo. Observe que os arquivos são classificados antes de serem agrupados.

Exemplo 3

C:\PS>1..35 | group-object -property {$_ % 2},{$_ % 3}

Descrição
-----------
Este exemplo mostra como usar blocos de scripts como valor do parâmetro Property. 

Este comando exibe os inteiros de 1 a 35, agrupados pelos restantes da esquerda quando divididos por 2 ou 3.

Exemplo 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}

Descrição
-----------
Esses comandos exibem as 1.000 entradas mais recentes do log de eventos System, agrupados por Event ID. 

O primeiro comando usa o cmdlet Get-EventLog para recuperar os eventos e o operador de atribuição (=) para salvá-los na variável $events. 

O segundo comando usa um operador de pipeline (|) para enviar os eventos da variável $events para o cmdlet Group-Object. O comando usa o parâmetro Property para especificar que os eventos deveriam ser agrupados de acordo com o valor de sua propriedade EventID. 

Na saída, a coluna Count representa o número de entradas em cada grupo, a coluna Name representa os valores EventID que definem um grupo e a coluna Group representa a os objetos de cada grupo.

Exemplo 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

Descrição
-----------
Esse 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. 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, mas ele usa o parâmetro NoElement para eliminar os membros do grupo da saída. O resultado é uma tabela com apenas a contagem e nome de valor de propriedade.

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

Exemplo 6

C:\PS>get-eventlog -logname system -newest 1000 | group-object -property {$_.TimeWritten - $_.TimeGenerated}

Descrição
-----------
Este comando demonstra como você pode fornecer o valor do parâmetro Property como um bloco de script.

Esse comando exibe as 1.000 entradas mais recentes do log de eventos do sistema, agrupadas de acordo com a hora entre sua geração e sua gravação no log. 

O comando usa o cmdlet Get-EventLog para as entradas de logs de eventos. Ele usa o operador de pipeline (|) para enviar as entradas para o cmdlet Group-Object. O valor do parâmetro Property é especificado como um bloco de script (uma expressão entre chaves). O resultado da avaliação do bloco de script será a hora entre a geração da entrada do log e sua gravação no log. Tal valor será usado para agrupar os 1.000 eventos mais recentes.

Exemplo 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

Descrição
-----------
Esse comando agrupa os itens do diretório atual por extensão de nome de arquivo. Usa o parâmetro NoElement para omitir os membros do grupo.

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

Exemplo 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

Descrição
-----------
Este exemplo mostra como localizar os valores de propriedade exclusivos e não exclusivos (repetidos) em uma coleção. 

O primeiro comando obtém os elementos exclusivos de uma matriz enviando a matriz para o cmdlet Get-Unique.

O segundo comando obtém os elementos não exclusivos de uma matriz. Envia a matriz ao cmdlet Group-Object, o que agrupa os objetos por valor. Os grupos resultantes são enviados ao cmdlet Where-Object, o qual seleciona objetos com grupos com mais de um membro.

O terceiro comando mostra um uso prático para esta técnica. Usa o mesmo método para localizar processos no computador que possuam o mesmo nome de processo.

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

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

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

Na tabela de hash resultante, cada valor de propriedade é uma chave e os elementos de 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 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 de valores-chave, um para os cmdlets Get e outro para os cmdlets Set.

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



Sumário