about_Calculated_Properties

Descripción breve

PowerShell proporciona la capacidad de agregar dinámicamente nuevas propiedades y modificar el formato de los objetos de salida a la canalización.

Descripción larga

Varios cmdlets de PowerShell transforman, agrupan o procesan objetos de entrada en objetos de salida mediante parámetros que permiten agregar nuevas propiedades a esos objetos de salida. Puede usar estos parámetros para generar propiedades nuevas y calculadas en objetos de salida en función de los valores de los objetos de entrada. La propiedad calculada se define mediante una tabla hash que contiene pares clave-valor que especifican el nombre de la nueva propiedad, una expresión para calcular el valor y la información de formato opcional.

Cmdlets compatibles

Los siguientes cmdlets admiten valores de propiedad calculados para el parámetro Property . Los Format-* cmdlets también admiten valores calculados para el parámetro GroupBy .

En la lista siguiente se incluyen los cmdlets que admiten propiedades calculadas y los pares clave-valor que admite cada cmdlet.

• Compare-Object

  • expression

• ConvertTo-Html

  • name/label : opcional (agregado en PowerShell 6.x)
  • expression
  • width -Opcional
  • alignment -Opcional

• Format-Custom

  • expression
  • depth -Opcional

• Format-List

  • name/label -Opcional
  • expression
  • formatstring -Opcional

  Este mismo conjunto de pares clave-valor también se aplica a los valores de propiedad calculados pasados al parámetro GroupBy para todos los Format-* cmdlets.

• Format-Table

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

• Format-Wide

  • expression
  • formatstring -Opcional

• Group-Object

  • expression

• Measure-Object

  • Solo admite un bloque de script para la expresión, no una tabla hash.
  • No se admite en PowerShell 5.1 y versiones anteriores.

• Select-Object

  • name/label -Opcional
  • expression

• Sort-Object

  • expression
  • ascending/descending -Opcional

Nota:

El valor de expression puede ser un bloque de script en lugar de una tabla hash. Para más información, vea la sección Notas.

Definiciones de clave hashtable

• name/label : especifica el nombre de la propiedad que se va a crear. Puede usar name o su alias, label, indistintamente.
• expression : cadena o bloque de script usado para calcular el valor de la nueva propiedad. Si es expression una cadena, el valor se interpreta como un nombre de propiedad en el objeto de entrada. Esta es una opción más corta que expression = { $_.<PropertyName> }.
• alignment : se usa en cmdlets que generan resultados tabulares para definir cómo se muestran los valores en una columna. El valor debe ser 'left', 'center' o 'right'.
• formatstring : especifica una cadena de formato que define cómo se da formato al valor para la salida. Para obtener más información sobre las cadenas de formato, vea Tipos de formato en .NET.
• width : especifica la columna de ancho máximo de una tabla cuando se muestra el valor. El valor debe ser mayor que 0.
• depth : el parámetro Depth de Format-Custom especifica la profundidad de expansión de todas las propiedades. La depth clave permite especificar la profundidad de expansión por propiedad.
• ascending / descending : permite especificar el orden de ordenación de una o varias propiedades. Estos son valores booleanos.

No es necesario escribir las claves hashtable siempre que el prefijo de nombre especificado sea inequívoca. Por ejemplo, puede usar n en lugar de Name y e en lugar de Expression.

Ejemplos

Compare-Object

Con las propiedades calculadas, puede controlar cómo se comparan las propiedades de los objetos de entrada. En este ejemplo, en lugar de comparar los valores directamente, los valores se comparan con el resultado de la operación 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 puede convertir una colección de objetos en una tabla HTML. Las propiedades calculadas permiten controlar cómo se presenta la tabla.

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

En este ejemplo se crea una tabla HTML que contiene una lista de alias de PowerShell y los parámetros numéricos de cada comando con alias. Los valores de la columna ParameterCount se centran.

Format-Custom

Format-Custom proporciona una vista personalizada de un objeto en un formato similar a una definición de clase. Los objetos más complejos pueden contener miembros que están profundamente anidados con tipos complejos. El parámetro Depth de Format-Custom especifica la profundidad de expansión de todas las propiedades. La depth clave permite especificar la profundidad de expansión por propiedad.

En este ejemplo, la depth clave simplifica la salida personalizada para el Get-Date cmdlet . Get-Date devuelve un objeto DateTime . La propiedad Date de este objeto también es un objeto DateTime , por lo que el objeto está anidado.

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

En este ejemplo, se usan propiedades calculadas para cambiar el nombre y el formato de la salida 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

En este ejemplo, la propiedad calculada agrega una propiedad Type utilizada para clasificar los archivos por el tipo de contenido.

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

El Format-Wide cmdlet permite mostrar el valor de una propiedad para los objetos de una colección como una lista de varias columnas.

En este ejemplo, queremos ver el nombre de archivo y el tamaño (en kilobytes) como una lista amplia. Puesto Format-Wide que no muestra más de una propiedad, usamos una propiedad calculada para combinar el valor de dos propiedades en un solo 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

El Group-Object cmdlet muestra objetos en grupos en función del valor de una propiedad especificada. En este ejemplo, la propiedad calculada cuenta el número de archivos de cada tipo de contenido.

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

El Measure-Object cmdlet calcula las propiedades numéricas de los objetos. En este ejemplo, usamos una propiedad calculada para obtener el recuento (Suma) de los números, entre 1 y 10, que son divisibles uniformemente en 3.

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

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

Nota:

A diferencia de los otros cmdlets, Measure-Object no acepta una tabla hash para las propiedades calculadas. Debe usar un bloque de script.

Select-Object

Puede usar propiedades calculadas para agregar miembros adicionales a la salida de objetos con el Select-Object cmdlet . En este ejemplo, enumeraremos los alias de PowerShell que comienzan por la letra C. Con Select-Object, se genera el alias, el cmdlet al que se asigna y un recuento del número de parámetros definidos para el cmdlet. Con una propiedad calculada, podemos crear la propiedad 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

Con las propiedades calculadas, puede ordenar los datos en diferentes pedidos por propiedad. En este ejemplo se ordenan los datos de un archivo CSV en orden ascendente por Fecha. Pero dentro de cada fecha, ordena las filas en orden descendente 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

• Puede especificar el bloque de script de expresión directamente, como argumento, en lugar de especificarlo como entrada Expression en una tabla hash. Por ejemplo:

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

  Este ejemplo es cómodo para los cmdlets que no requieren (o admiten) asignar nombres a una propiedad a través de la Name clave, como Sort-Object, Group-Objecty Measure-Object.

  En el caso de los cmdlets que admiten la nomenclatura de la propiedad, el bloque de script se convierte en una cadena y se usa como nombre de la propiedad en la salida.

• ExpressionLos bloques de script se ejecutan en ámbitos secundarios, lo que significa que las variables del autor de la llamada no se pueden modificar directamente.

• La lógica de canalización se aplica a la salida de los bloques de Expression script. Esto significa que la salida de una matriz de un solo elemento hace que la matriz se desencapsula.

• Para la mayoría de los cmdlets, los errores dentro de los bloques de script de expresión se omiten silenciosamente. En el caso Sort-Objectde , los errores de terminación de instrucciones y de terminación de script son los resultados , pero no finalizan la instrucción .

Consulte también

• about_Hash_Tables
• ConvertTo-Html
• Format-Custom
• Format-List
• Format-Table
• Format-Wide
• Compare-Object
• Group-Object
• Measure-Object
• Select-Object
• Sort-Object
• Tipos de formato en .NET