about_Calculated_Properties

  • Artigo

Breve descrição

O PowerShell fornece a capacidade de adicionar dinamicamente novas propriedades e alterar a formatação da saída de objetos para o pipeline.

Descrição longa

Vários cmdlets do PowerShell transformam, agrupam ou processam objetos de entrada em objetos de saída usando parâmetros que permitem a adição de novas propriedades a esses objetos de saída. Você pode usar esses parâmetros para gerar novas propriedades calculadas em objetos de saída com base nos valores de objetos de entrada. A propriedade calculada é definida por uma hashtable contendo pares chave-valor que especificam o nome da nova propriedade, uma expressão para calcular o valor e informações de formatação opcionais.

Cmdlets suportados

Os cmdlets a seguir oferecem suporte a valores de propriedade calculados para o parâmetro Property . Os Format-* cmdlets também oferecem suporte a valores calculados para o parâmetro GroupBy .

A lista a seguir discrimina os cmdlets que oferecem suporte a propriedades calculadas e os pares chave-valor suportados por cada cmdlet.

  • Compare-Object

    • expression

  • ConvertTo-Html

    • name/label - opcional (adicionado no PowerShell 6.x)
    • expression
    • width - opcional
    • alignment - opcional

  • Format-Custom

    • expression
    • depth - opcional

  • Format-List

    • name/label - opcional
    • expression
    • formatstring - opcional

    Esse mesmo conjunto de pares chave-valor também se aplica aos valores de propriedade calculados passados para o parâmetro GroupBy para todos os Format-* cmdlets.

  • Format-Table

    • name/label - opcional
    • expression
    • formatstring - opcional
    • width - opcional
    • alignment - opcional

  • Format-Wide

    • expression
    • formatstring - opcional

  • Group-Object

    • expression

  • Measure-Object

    • Só suporta um bloco de script para a expressão, não uma tabela hash.
    • Não há suporte no PowerShell 5.1 e versões anteriores.

  • Select-Object

    • name/label - opcional
    • expression

  • Sort-Object

    • expression
    • ascending/descending - opcional

Nota

O valor do expression pode ser um bloco de scripts em vez de uma tabela hash. Para obter mais informações, consulte a seção Notas .

Definições de chave de hashtable

  • name/label - Especifica o nome da propriedade que está sendo criada. Você pode usar name seu alias, label, de forma intercambiável.
  • expression - Uma cadeia de caracteres ou bloco de script usado para calcular o valor da nova propriedade. Se for expression uma cadeia de caracteres, o valor será interpretado como um nome de propriedade no objeto de entrada. Esta é uma opção mais curta do que expression = { $_.<PropertyName> }.
  • alignment - Usado por cmdlets que produzem saída tabular para definir como os valores são exibidos em uma coluna. O valor deve ser 'left', 'center', ou 'right'.
  • formatstring - Especifica uma cadeia de caracteres de formato que define como o valor é formatado para saída. Para obter mais informações sobre cadeias de caracteres de formato, consulte Tipos de formato no .NET.
  • width - Especifica a coluna de largura máxima em uma tabela quando o valor é exibido. O valor deve ser maior que 0.
  • depth - O parâmetro Depth de especifica a profundidade de Format-Custom expansão para todas as propriedades. A depth chave permite especificar a profundidade de expansão por propriedade.
  • ascending / descending - Permite especificar a ordem de classificação de uma ou mais propriedades. Estes são valores booleanos.

Você não precisa soletrar as chaves hashtable, desde que o prefixo do nome especificado seja inequívoco. Por exemplo, você pode usar n em vez de Name e e em vez de Expression.

Exemplos

Compare-Object

Com propriedades calculadas, você pode controlar como as propriedades dos objetos de entrada são comparadas. Neste exemplo, em vez de comparar os valores diretamente, os valores são comparados com o resultado da operação aritmética (módulo de 2).

Compare-Object @{p=1} @{p=2} -property @{ Expression = { $_.p % 2 } }

 $_.p % 2  SideIndicator
---------- -------------
         0 =>
         1 <=

ConvertTo-Html

ConvertTo-Html pode converter uma coleção de objetos em uma tabela HTML. As propriedades calculadas permitem controlar como a tabela é apresentada.

Get-Alias |
  ConvertTo-Html Name,
                 Definition,
                 @{
                    name='ParameterCount'
                    expr={$_.Parameters.Keys.Count}
                    align='center'
                 } |
    Out-File .\aliases.htm -Force

Este exemplo cria uma tabela HTML contendo uma lista de aliases do PowerShell e os parâmetros de número para cada comando com alias. Os valores da coluna ParameterCount são centralizados.

Format-Custom

Format-Custom Fornece uma exibição personalizada de um objeto em um formato semelhante a uma definição de classe. Objetos mais complexos podem conter membros profundamente aninhados com tipos complexos. O parâmetro Depth de especifica a profundidade de Format-Custom expansão para todas as propriedades. A depth chave permite especificar a profundidade de expansão por propriedade.

Neste exemplo, a depth chave simplifica a saída personalizada para o Get-Date cmdlet. Get-Date retorna um objeto DateTime . A propriedade Date deste objeto também é um objeto DateTime , portanto, o objeto é aninhado.

Get-Date | Format-Custom @{expr={$_.Date};depth=1},TimeOfDay

class DateTime
{
  $_.Date =
    class DateTime
    {
      Date = 8/7/2020 12:00:00 AM
      Day = 7
      DayOfWeek = Friday
      DayOfYear = 220
      Hour = 0
      Kind = Local
      Millisecond = 0
      Minute = 0
      Month = 8
      Second = 0
      Ticks = 637323552000000000
      TimeOfDay = 00:00:00
      Year = 2020
      DateTime = Friday, August 07, 2020 12:00:00 AM
    }
  TimeOfDay =
    class TimeSpan
    {
      Ticks = 435031592302
      Days = 0
      Hours = 12
      Milliseconds = 159
      Minutes = 5
      Seconds = 3
      TotalDays = 0.503508787386574
      TotalHours = 12.0842108972778
      TotalMilliseconds = 43503159.2302
      TotalMinutes = 725.052653836667
      TotalSeconds = 43503.1592302
    }
}

Format-List

Neste exemplo, usamos propriedades calculadas para alterar o nome e o formato da saída de Get-ChildItem.

Get-ChildItem *.json -File |
  Format-List Fullname,
              @{
                 name='Modified'
                 expression={$_.LastWriteTime}
                 formatstring='O'
              },
              @{
                 name='Size'
                 expression={$_.Length/1KB}
                 formatstring='N2'
              }

FullName : C:\Git\PS-Docs\PowerShell-Docs\.markdownlint.json
Modified : 2020-07-23T10:26:28.4092457-07:00
Size     : 2.40

FullName : C:\Git\PS-Docs\PowerShell-Docs\.openpublishing.publish.config.json
Modified : 2020-07-23T10:26:28.4092457-07:00
Size     : 2.25

FullName : C:\Git\PS-Docs\PowerShell-Docs\.openpublishing.redirection.json
Modified : 2020-07-27T13:05:24.3887629-07:00
Size     : 324.60

Format-Table

Neste exemplo, a propriedade calculada adiciona uma propriedade Type usada para classificar os arquivos pelo tipo de conteúdo.

Get-ChildItem -File |
  Sort-Object extension |
    Format-Table Name, Length -GroupBy @{
      name='Type'
      expression={
        switch ($_.extension) {
          '.md'   {'Content'}
          ''      {'Metacontent'}
          '.ps1'  {'Automation'}
          '.yml'  {'Automation'}
          default {'Configuration'}
        }
      }
    }

   Type: Metacontent

Name              Length
----              ------
ThirdPartyNotices   1229
LICENSE-CODE        1106
LICENSE            19047

   Type: Configuration

Name                                Length
----                                ------
.editorconfig                          183
.gitattributes                         419
.gitignore                             228
.markdownlint.json                    2456
.openpublishing.publish.config.json   2306
.openpublishing.redirection.json    332394
.localization-config                   232

   Type: Content

Name            Length
----            ------
README.md         3355
CONTRIBUTING.md    247

   Type: Automation

Name                      Length
----                      ------
.openpublishing.build.ps1    796
build.ps1                   7495
ci.yml                       645
ci-steps.yml                2035
daily.yml                   1271

Format-Wide

O Format-Wide cmdlet permite que você exiba o valor de uma propriedade para objetos em uma coleção como uma lista de várias colunas.

Para este exemplo, queremos ver o nome do arquivo e o tamanho (em kilobytes) como uma lista ampla. Como Format-Wide não exibe mais de uma propriedade, usamos uma propriedade calculada para combinar o valor de duas propriedades em um único valor.

Get-ChildItem -File |
  Format-Wide -Property @{e={'{0} ({1:N2}kb)' -f $_.name,($_.length/1kb)}}

.editorconfig (0.18kb)                          .gitattributes (0.41kb)
.gitignore (0.22kb)                             .localization-config (0.23kb)
.markdownlint.json (2.40kb)                     .openpublishing.build.ps1 (0.78kb)
.openpublishing.publish.config.json (2.25kb)    .openpublishing.redirection.json (324.60kb)
build.ps1 (7.32kb)                              ci.yml (0.63kb)
ci-steps.yml (1.99kb)                           CONTRIBUTING.md (0.24kb)
daily.yml (1.24kb)                              LICENSE (18.60kb)
LICENSE-CODE (1.08kb)                           README.md (3.28kb)
ThirdPartyNotices (1.20kb)

Group-Object

O Group-Object cmdlet exibe objetos em grupos com base no valor de uma propriedade especificada. Neste exemplo, a propriedade calculada conta o número de arquivos de cada tipo de conteúdo.

Get-ChildItem -File |
  Sort-Object extension |
    Group-Object -NoElement -Property @{
      expression={
        switch ($_.extension) {
          '.md'   {'Content'}
          ''      {'Metacontent'}
          '.ps1'  {'Automation'}
          '.yml'  {'Automation'}
          default {'Configuration'}
        }
      }
    }

Count Name
----- ----
    5 Automation
    7 Configuration
    2 Content
    3 Metacontent

Measure-Object

O Measure-Object cmdlet calcula as propriedades numéricas dos objetos. Neste exemplo, usamos uma propriedade calculada para obter a contagem (Soma) dos números, entre 1 e 10, que são uniformemente divisíveis por 3.

1..10 | Measure-Object -Property {($_ % 3) -eq 0} -Sum

Count             : 10
Average           :
Sum               : 3
Maximum           :
Minimum           :
StandardDeviation :
Property          : ($_ % 3) -eq 0

Nota

Ao contrário dos outros cmdlets, Measure-Object não aceita uma hashtable para propriedades calculadas. Você deve usar um bloco de script.

Select-Object

Você pode usar propriedades calculadas para adicionar membros adicionais à saída de objetos com o Select-Object cmdlet. Neste exemplo, estamos listando os aliases do PowerShell que começam com a letra C. Usando Select-Objecto , produzimos o alias, o cmdlet para o qual ele é mapeado e uma contagem para o número de parâmetros definidos para o cmdlet. Usando uma propriedade calculada, podemos criar a propriedade ParameterCount .

$aliases = Get-Alias c* |
  Select-Object Name,
                Definition,
                @{
                    name='ParameterCount'
                    expr={$_.Parameters.Keys.Count}
                }
$aliases | Get-Member
$aliases

   TypeName: Selected.System.Management.Automation.AliasInfo

Name           MemberType   Definition
----           ----------   ----------
Equals         Method       bool Equals(System.Object obj)
GetHashCode    Method       int GetHashCode()
GetType        Method       type GetType()
ToString       Method       string ToString()
Definition     NoteProperty string Definition=Get-Content
Name           NoteProperty string Name=cat
ParameterCount NoteProperty System.Int32 ParameterCount=21

Name    Definition         ParameterCount
----    ----------         --------------
cat     Get-Content                    21
cd      Set-Location                   15
cdd     Push-MyLocation                 1
chdir   Set-Location                   15
clc     Clear-Content                  20
clear   Clear-Host                      0
clhy    Clear-History                  17
cli     Clear-Item                     20
clp     Clear-ItemProperty             22
cls     Clear-Host                      0
clv     Clear-Variable                 19
cnsn    Connect-PSSession              29
compare Compare-Object                 20
copy    Copy-Item                      24
cp      Copy-Item                      24
cpi     Copy-Item                      24
cpp     Copy-ItemProperty              23
cvpa    Convert-Path                   13

Sort-Object

Usando as propriedades calculadas, você pode classificar os dados em diferentes ordens por propriedade. Este exemplo classifica os dados de um arquivo CSV em ordem crescente por Data. Mas dentro de cada data, ele classifica as linhas em ordem decrescente por UnitsSold.

Import-Csv C:\temp\sales-data.csv |
  Sort-Object Date, @{expr={$_.UnitsSold}; desc=$true}, Salesperson  |
    Select-Object Date, Salesperson, UnitsSold

Date       Salesperson UnitsSold
----       ----------- ---------
2020-08-01 Sally       3
2020-08-01 Anne        2
2020-08-01 Fred        1
2020-08-02 Anne        6
2020-08-02 Fred        2
2020-08-02 Sally       0
2020-08-03 Anne        5
2020-08-03 Sally       3
2020-08-03 Fred        1
2020-08-04 Anne        2
2020-08-04 Fred        2
2020-08-04 Sally       2

Notas

  • Pode especificar o bloco de scripts de expressão diretamente, como um argumento, em vez de especitá-lo como a entrada Expression numa tabela hash. Por exemplo:

    '1', '10', '2' | Sort-Object { [int] $_ }

    Este exemplo é conveniente para cmdlets que não exigem (ou suportam) nomear uma propriedade por meio da Name chave, como Sort-Object, Group-Objecte Measure-Object.

    Para cmdlets que dão suporte à nomeação da propriedade, o bloco de script é convertido em uma cadeia de caracteres e usado como o nome da propriedade na saída.

  • Expression Os blocos de script são executados em escopos filho , o que significa que as variáveis do chamador não podem ser modificadas diretamente.

  • A lógica de pipeline é aplicada à saída de blocos de Expression script. Isso significa que a saída de uma matriz de elemento único faz com que essa matriz seja desempacotada.

  • Para a maioria dos cmdlets, os erros dentro dos blocos de script de expressão são ignorados silenciosamente. Para Sort-Object, erros de terminação de instrução e terminação de script são saída , mas não encerram a instrução.

Consulte também