Compartilhar via

about_Calculated_Properties

Descrição curta

O PowerShell fornece a capacidade de adicionar dinamicamente novas propriedades e alterar a formatação da saída de objetos ao 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 criar novas propriedades nesses objetos de saída. Você pode usar esses parâmetros para gerar novas propriedades calculadas em objetos de saída com base nos valores dos objetos de entrada. O objeto de entrada pode ser acessado usando a $_ variável ou $PSItem automática dentro do Expression membro de uma propriedade calculada.

A propriedade calculada é definida como um hashable que contém pares chave-valor que especificam o valor da propriedade calculada recentemente. Alguns comandos dão suporte a outros pares chave-valor que controlam como a propriedade é exibida na saída.

Cmdlets com suporte

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

A lista a seguir itemiza os cmdlets que dão suporte a propriedades calculadas e aos pares chave-valor que cada cmdlet dá suporte.

  • Compare-Object

    • Expression

  • ConvertTo-Html

    • Name / Label - opcional (adicionado ao 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 a valores de propriedade calculados passados para o parâmetro GroupBy para todos os cmdlets Format-*.

  • Format-Table

    • Name / Label - opcional
    • Expression
    • FormatString - opcional
    • Width - opcional
    • Alignment - opcional

  • Format-Wide

    • Expression
    • FormatString - opcional

  • Group-Object

    • Expression

  • Measure-Object

    • Só dá suporte a um scriptblock para a expressão, não a um hashtable.
    • Não há suporte no PowerShell 5.1 e mais antigo.

  • Select-Object

    • Name / Label - opcional
    • Expression

  • Sort-Object

    • Expression
    • Ascending / Descending - opcional

Nota

O valor do Expression pode ser um scriptblock em vez de um hashtable. Para obter mais informações, consulte a seção Anotações.

Definições de chave hashable

  • Name / Label - Especifica o nome da propriedade que está sendo criada. Você pode usar Name ou seu alias, Label, intercambiável.
  • Expression - Uma cadeia de caracteres ou um scriptblock usado para calcular o valor da nova propriedade. Se o Expression for uma cadeia de caracteres, o valor será interpretado como um nome de propriedade no objeto de entrada. Essa é 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 de Profundidade de Format-Custom especifica a profundidade da expansão para todas as propriedades. A chave Depth permite que você especifique a profundidade da expansão por propriedade.
  • Ascending / Descending - Permite que você especifique a ordem de classificação para uma ou mais propriedades. Estes são valores boolianos.

Você não precisa soletrar as chaves de hash, desde que o prefixo de nome especificado seja inequívoca. 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 que contém uma lista de aliases do PowerShell e os parâmetros numéricos para cada comando aliased. 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 Format-Custom especifica a profundidade da expansão para todas as propriedades. A chave Depth permite que você especifique a profundidade da expansão por propriedade.

Neste exemplo, a chave Depth simplifica a saída personalizada para o cmdlet Get-Date. Get-Date retorna um objeto DateTime. A propriedade Date desse objeto também é um objeto DateTime, portanto, o objeto está 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 cmdlet Format-Wide permite exibir 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 quilobytes) como uma listagem 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 cmdlet Group-Object 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 cmdlet Measure-Object calcula as propriedades numéricas dos objetos. Neste exemplo, usamos uma propriedade calculada para obter a contagem dos números entre 1 e 10 que são uniformemente divisível por 3.

O scriptblock retornará $true se o número for divisível por 3 e $false para todos os outros números. A operação Sum trata valores $true como valores 1 e $false como 0.

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 um hashtable para propriedades calculadas. Você deve usar um scriptblock.

Select-Object

Você pode usar propriedades calculadas para adicionar membros adicionais à saída de objetos com o cmdlet Select-Object. Neste exemplo, estamos listando os aliases do PowerShell que começam com a letra C. Usando Select-Object, geramos o alias, o cmdlet para o qual ele está 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 dados em diferentes pedidos por propriedade. Este exemplo classifica dados de um arquivo CSV em ordem crescente Data. No entanto, dentro de cada data, ele classifica as linhas em ordem decrescente 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

Anotações

  • Você pode especificar o scriptblock de expressão diretamente, como um argumento, em vez de especificá-lo como a Expression entrada em um hashtable. Por exemplo:

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

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

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

  • Expression os scriptblocks 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 Expression scriptblocks. Isso significa que a saída de uma matriz de elemento único faz com que essa matriz seja desembrulhada.

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

Consulte também

  • about_Hash_Tables
  • ConvertTo-Html
  • personalizado de formato
  • de Lista de Formatos
  • format-table
  • em todo o formato
  • de objeto de comparação
  • de objeto de grupo
  • de objeto de medida
  • select-object
  • de objeto de classificação
  • tipos de formato no .NET
  • Last updated on