about_Calculated_Properties

簡短描述

PowerShell 可讓您動態新增屬性，並改變對象輸出至管線的格式。

完整描述

數個 PowerShell Cmdlet 會使用參數將輸入物件轉換成輸出物件，以允許將這些輸出物件新增屬性。 您可以使用這些參數，根據輸入物件的值，在輸出對象上產生新的導出屬性。 匯出屬性是由 哈希表 所定義，其中包含索引鍵/值組，指定新屬性的名稱、用來計算值的表達式，以及選擇性的格式資訊。

支援的 Cmdlet

下列 Cmdlet 支援 Property 參數的匯出屬性值。 Cmdlet Format-* 也支援 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 傳遞至 GroupBy 參數 Format-* 的導出屬性值。

• 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- 的 參數會指定所有屬性的展開深度。 索引 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,
                 @{
                    Expr={$_.Parameters.Keys.Count}
                    Align='Center'
                 } |
    Out-File .\aliases.htm -Force

此範例會建立 HTML 數據表，其中包含 PowerShell 別名清單，以及每個別名命令的數字參數。 ParameterCount 資料行的值會置中。

Format-Custom

Format-Custom 以類似類別定義的格式提供 物件的自定義檢視。 更複雜的物件可以包含與複雜類型深度巢狀的成員。 的 參數會指定所有屬性的展開深度。 索引 Depth 鍵可讓您指定每個屬性的擴充深度。

在此範例中，金鑰 Depth 可簡化 Cmdlet 的 Get-Date 自訂輸出。 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

Cmdlet Format-Wide 可讓您將集合中物件的一個屬性值顯示為多欄清單。

在此範例中，我們想要將檔名和大小（以 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

Cmdlet 會 Group-Object 根據指定屬性的值，在群組中顯示物件。 在此範例中，匯出屬性會計算每個內容類型的檔案數目。

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

Select-Object

您可以使用匯出屬性，將其他成員新增至 Cmdlet Select-Object 輸出的物件。 在此範例中，我們會列出以字母 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

使用匯出屬性，您可以依每個屬性的不同順序來排序數據。 此範例會依 日期以遞增順序排序 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 中的格式類型