about_Calculated_Properties

简短说明

PowerShell 提供动态添加新属性和更改向管道输出的对象格式的功能。

详细说明

多个 PowerShell cmdlet 使用允许向输出对象添加新属性的参数来转换输入对象、将输入对象分组以及将输入对象处理成输出对象。 可以使用这些参数来基于输入对象的值生成输出对象的新计算属性。 计算属性由哈希表定义，该哈希表中包含指定新属性的名称的键值对、一个用于计算值的表达式，以及可选的格式设置信息。

支持的 cmdlet

以下 cmdlet 支持 Property 参数的计算属性值。 Format-* cmdlet 还支持 GroupBy 参数的计算值。

以下列表逐项列出支持计算属性的 cmdlet 以及每个 cmdlet 支持的键值对。

• Compare-Object

  • Expression

• ConvertTo-Html

  • Name / Label - 可选（已在 PowerShell 6.x 中添加）
  • Expression
  • Width - 可选
  • Alignment - 可选

• Format-Custom

  • Expression
  • Depth - 可选

• Format-List

  • Name / Label - 可选
  • Expression
  • FormatString - 可选

  同一组键值对还适用于传递给所有 cmdlet 的 GroupByFormat-* 参数的计算属性值。

• Format-Table

  • Name / Label - 可选
  • Expression
  • FormatString - 可选
  • Width - 可选
  • Alignment - 可选

• Format-Wide

  • Expression
  • FormatString - 可选

• Group-Object

  • Expression

• Measure-Object

  • 仅支持表达式的脚本块，不支持哈希表。
  • 在 PowerShell 5.1 及更低版本中不受支持。

• Select-Object

  • Name / Label - 可选
  • Expression

• Sort-Object

  • Expression
  • Ascending / Descending - 可选

哈希表密钥定义

• Name / Label - 指定要创建的属性的名称。 Name 或其别名 Label 可以互换使用。
• Expression - 用于计算新属性的值的字符串或脚本块。 如果 Expression 是字符串，该值将解释为输入对象的属性名称。 此选项比 Expression = { $_.<PropertyName> } 更短。
• Alignment - 由生成表格输出的 cmdlet 用来定义值在列中的显示方式。 值必须为 'Left'、'Center' 或 'Right'。
• FormatString - 指定一个格式字符串，用于定义如何为输出设置值的格式。 有关格式字符串的详细信息，请参阅在 .NET 中设置类型的格式。
• Width - 指定在显示值时表中的最大宽度列。 该值必须大于 0。
• Depth - 的 DepthFormat-Custom 参数指定所有属性的扩展深度。 使用 Depth 键可以指定每个属性的扩展深度。
• Ascending / Descending - 允许指定一个或多个属性的排序顺序。 这些是布尔值。

只要指定的名称前缀明确，就不需要非常详尽地拼写出哈希表键。 例如，可以使用 n 而非 Name，使用 e 而非 Expression。

例子

Compare-Object

可以使用计算属性控制输入对象的属性的比较方式。 此示例中并没有直接比较值，而是将值与算术运算（以 2 为模进行取模）的结果进行比较。

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

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

ConvertTo-Html

ConvertTo-Html 可将对象集合转换为 HTML 表。 使用计算属性可以控制表的显示方式。

Get-Alias |
  ConvertTo-Html Name,
                 Definition,
                 @{
                    Name='ParameterCount'
                    Expr={$_.Parameters.Keys.Count}
                    Align='Center'
                 } |
    Out-File .\aliases.htm -Force

此示例创建一个 HTML 表，其中包含 PowerShell 别名的列表以及每个别名命令的数字参数。 ParameterCount 列的值居中。

Format-Custom

Format-Custom 以类似于类定义的格式提供对象的自定义视图。 更复杂的对象可以包含与复杂类型深度嵌套的成员。 的 DepthFormat-Custom 参数指定所有属性的扩展深度。 使用 Depth 键可以指定每个属性的扩展深度。

在此示例中，Depth 键简化了 Get-Date cmdlet 的自定义输出。 Get-Date 返回一个 DateTime 对象。 此对象的 Date 属性也是 DateTime 对象，因此该对象是嵌套的。

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

在此示例中，我们使用计算属性更改 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

在此示例中，计算属性添加了 Type 属性，后者用于按内容类型对文件进行分类。

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

使用 Format-Wide cmdlet 可以将集合中对象的一个属性的值显示为多列列表。

对于此示例，我们希望以宽列表形式显示文件名和大小（以 KB 为单位）。 由于 Format-Wide 不显示多个属性，因此我们使用计算属性将两个属性的值合并为单个值。

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

Group-Object cmdlet 可根据指定属性的值按组显示对象。 在此示例中，计算属性会计算每个内容类型的文件数。

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

Measure-Object cmdlet 会计算对象的数值属性。 在此示例中，我们使用计算属性获取 1 到 10 之间的数字计数，这些数字被 3 均匀地分割。

如果数字被 3 $true 和所有其他数字分割，则脚本块将返回$false。 Sum 运算将$true值视为1值和$false值。0

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

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

Select-Object

可以使用计算属性通过 Select-Object cmdlet 将其他成员添加到对象输出中。 在此示例中，我们将列出以字母 C 开头的 PowerShell 别名。 使用 Select-Object，我们输出了别名、它映射到的 cmdlet 以及为该 cmdlet 定义的参数的计数。 使用计算属性，我们可以创建 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

使用计算属性，可以按属性采用不同的顺序对数据进行排序。 本示例按 Date 采用升序对 CSV 文件中的数据进行排序。 但在每个日期内，都会按 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

注释

• 可以将表达式脚本块直接指定为参数，而不是将其指定为哈希表中的 Expression 项。 例如：

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

  此示例适用于不需要（或不支持）通过 Name 键对属性命名的 cmdlet，例如 Sort-Object、Group-Object 和 Measure-Object。

  对于支持对属性命名的 cmdlet，脚本块将转换为字符串，用作输出中的属性的名称。

• Expression 脚本块在子作用域中运行，这意味着无法直接修改调用方的变量。

• 管道逻辑应用于 Expression 脚本块的输出。 这意味着输出单元素数组会导致该数组被展开。

• 对于大多数 cmdlet，表达式脚本块中的错误会被悄悄忽略。 对于 Sort-Object，语句终止性错误和脚本终止性错误会被输出，但它们不会终止语句。

另请参阅

• about_Hash_Tables
• ConvertTo-Html
• Format-Custom
• Format-List
• Format-Table
• Format-Wide
• Compare-Object
• Group-Object
• Measure-Object
• Select-Object
• Sort-Object
• 在 .NET 中设置类型的格式