about_Format.ps1xml

發行項
01/11/2023

簡短描述

從 PowerShell 6 開始，物件的預設檢視定義于 PowerShell 原始程式碼中。

您可以建立自己的 Format.ps1xml 檔案來變更物件的顯示，或為您在 PowerShell 中建立的新物件類型定義預設顯示。

完整描述

從 PowerShell 6 開始，預設檢視會在 PowerShell 原始程式碼中定義。 Format.ps1xmlPowerShell 5.1 和舊版的檔案不存在於 PowerShell 6 和更新版本中。

PowerShell 原始程式碼會在 PowerShell 主控台中定義物件的預設顯示。您可以建立自己的 Format.ps1xml 檔案來變更物件的顯示，或為您在 PowerShell 中建立的新物件類型定義預設顯示。

當 PowerShell 顯示物件時，它會使用結構化格式檔案中的資料來判斷物件的預設顯示。格式化檔案中的資料會決定物件是在資料表或清單中轉譯，並且決定預設會顯示哪些屬性。

格式只會影響顯示。這不會影響哪些物件屬性會傳遞至管線或傳遞方式。 Format.ps1xml 檔案無法用來自訂雜湊表的輸出格式。

.ps1xml格式化檔案可以定義每個物件的四個不同的檢視：

資料表
List
寬
Custom

例如，當命令的 Get-ChildItem 輸出傳送至 Format-List 命令時， Format-List 會使用原始程式碼中定義的清單檢視來決定如何將檔案和資料夾物件顯示為清單。

當格式化檔案包含一個以上的物件檢視時，PowerShell 會套用它找到的第一個檢視。

在自訂 Format.ps1xml 檔案中，檢視是由描述檢視名稱的一組 XML 標記所定義、可套用的物件類型、資料行標頭，以及顯示在檢視主體中的屬性。檔案中的 Format.ps1xml 格式會在資料呈現給使用者之前套用。

建立新的 Format.ps1xml 檔案

若要變更現有物件檢視的顯示格式，或新增新物件的檢視，請建立您自己的 Format.ps1xml 檔案，然後將其新增至 PowerShell 會話。

若要建立 Format.ps1xml 檔案以定義自訂檢視，請使用 Get-FormatData 和 Export-FormatData Cmdlet。使用文字編輯器來編輯檔案。檔案可以儲存至 PowerShell 可以存取的任何目錄，例如的 $HOME 子目錄。

若要變更目前檢視的格式，請在格式化檔案中找出檢視，然後使用標記來變更檢視。若要建立新物件類型的檢視，請建立新的檢視，或使用現有的檢視作為模型。下一節會說明標記。然後，您可以刪除檔案中的所有其他檢視，讓任何檢查檔案的任何人都能明顯看到變更。

儲存變更之後，請使用 Update-FormatData 將新檔案新增至 PowerShell 會話。如果您想要讓檢視優先于內建檔案中定義的檢視，請使用 PrependPath 參數。 Update-FormatData 只會影響目前的會話。若要變更所有未來的會話，請將命令新增 Update-FormatData 至您的 PowerShell 設定檔。

範例：將行事歷數據新增至文化特性物件

此範例示範如何變更目前 PowerShell 會話中 Cmdlet 所產生的 Get-Culture 文化特性物件System.Globalization.CultureInfo格式設定。範例中的命令會將 Calendar 屬性新增至文化特性物件的預設資料表檢視顯示。

若要開始，請從原始程式碼檔案取得格式資料，並建立 Format.ps1xml 包含文化特性物件目前檢視的檔案。

Get-FormatData -TypeName System.Globalization.CultureInfo |
  Export-FormatData -Path $HOME\Format\CultureInfo.Format.ps1xml

CultureInfo.Format.ps1xml在任何 XML 或文字編輯器中開啟檔案，例如Visual Studio Code。下列 XML 會定義 CultureInfo 物件的檢視。

檔案 CultureInfo.Format.ps1xml 看起來應該像下列範例：

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <ViewDefinitions>
    <View>
      <Name>System.Globalization.CultureInfo</Name>
      <ViewSelectedBy>
        <TypeName>System.Globalization.CultureInfo</TypeName>
      </ViewSelectedBy>
      <TableControl>
        <TableHeaders>
          <TableColumnHeader>
            <Width>16</Width>
          </TableColumnHeader>
          <TableColumnHeader>
            <Width>16</Width>
          </TableColumnHeader>
          <TableColumnHeader />
        </TableHeaders>
        <TableRowEntries>
          <TableRowEntry>
            <TableColumnItems>
              <TableColumnItem>
                <PropertyName>LCID</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Name</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>DisplayName</PropertyName>
              </TableColumnItem>
            </TableColumnItems>
          </TableRowEntry>
        </TableRowEntries>
      </TableControl>
    </View>
  </ViewDefinitions>
</Configuration>

藉由新增一組 <TableColumnHeader> 新的標記，為Calendar屬性建立新的資料行。 Calendar屬性的值可以很長，因此請將 45 個字元的值指定為 <Width> 。

<TableHeaders>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>45</Width>
  </TableColumnHeader>
  <TableColumnHeader/>
</TableHeaders>

使用 <TableColumnItem> 和 <PropertyName 標記，在資料表資料列中新增Calendar的資料行專案：

<TableRowEntries>
  <TableRowEntry>
    <TableColumnItems>
      <TableColumnItem>
        <PropertyName>LCID</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>Name</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>Calendar</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>DisplayName</PropertyName>
      </TableColumnItem>
    </TableColumnItems>
  </TableRowEntry>
</TableRowEntries>

儲存並關閉檔案。使用 Update-FormatData 將新的格式檔案新增至目前的 PowerShell 會話。

此範例會使用 PrependPath 參數，將新檔案置於比原始檔案更高的優先順序。如需詳細資訊，請參閱 Update-FormatData。

Update-FormatData -PrependPath $HOME\Format\CultureInfo.Format.ps1xml

若要測試變更，請輸入 Get-Culture 並檢閱包含 Calendar 屬性的輸出。

Get-Culture

LCID  Name   Calendar                                DisplayName
----  ----   --------                                -----------
1033  en-US  System.Globalization.GregorianCalendar  English (United States)

Format.ps1xml 檔案中的 XML

您可以在 GitHub 上 PowerShell 原始程式碼存放庫中的 Format.xsd 中找到完整的架構定義。

每個 Format.ps1xml 檔案的ViewDefinitions區段包含 <View> 定義每個檢視的標記。一般 <View> 標籤包含下列標籤：

<Name> 會識別檢視的名稱。
<ViewSelectedBy> 會指定套用檢視的物件類型或型別。
<GroupBy> 會指定檢視中的專案如何在群組中合併。
<TableControl>、 <ListControl> 、 <WideControl> 和 <CustomControl> 包含標記，指定每個專案的顯示方式。

ViewSelectedBy 標記

標記 <ViewSelectedBy> 可以包含 <TypeName> 套用檢視之每個物件類型的標記。或者，它可以包含一個 <SelectionSetName> 標籤，參考使用 <SelectionSet> 標記在其他位置定義的選取集。

GroupBy 標記

標記 <GroupBy> 包含標記 <PropertyName> ，指定要分組專案的物件屬性。它也包含 <Label> 標記，指定要作為每個群組標籤的字串，或是 <CustomControlName> 參考使用 <Control> 標記在其他位置定義的自訂控制項的標籤。標記 <Control> 包含 <Name> 標籤和 <CustomControl> 標記。

TableControlTag

標記 <TableControl> 通常包含 <TableHeaders> 和 <TableRowEntries> 標記，可定義資料表的頭部和資料列的格式設定。標記 <TableHeaders> 通常包含 <TableColumnHeader> 包含 <Label> 、 <Width> 和標記的 <Alignment> 標記。標記 <TableRowEntries> 包含 <TableRowEntry> 資料表中每個資料列的標記。標記 <TableRowEntry> 包含標記 <TableColumnItems> ，其中包含 <TableColumnItem> 資料列中每個資料行的標記。一般而言，卷 <TableColumnItem> 標包含 <PropertyName> 可識別要顯示在定義位置之物件屬性的標記，或 <ScriptBlock> 包含腳本程式碼的標記，其會計算要顯示在位置的結果。

注意

腳本區塊也可以用於計算結果可能很有用的位置。

標記 <TableColumnItem> 也可以包含標記 <FormatString> ，指定屬性或計算結果的顯示方式。

ListControl 標籤

標記 <ListControl> 通常包含 <ListEntries> 標記。卷 <ListEntries> 標包含卷 <ListEntry> 標。卷 <ListEntry> 標包含卷 <ListItems> 標。標記 <ListItems> 包含 <ListItem> 標籤，其中包含 <PropertyName> 標記。標記 <PropertyName> 會指定要顯示在清單中指定位置的物件屬性。如果使用選取集定義檢視選取範圍， <ListControl> 和 <ListEntry> 標籤也可以包含 <EntrySelectedBy> 包含一或多個 <TypeName> 標籤的標籤。這些 <TypeName> 標記會指定標記要顯示的物件類型 <ListControl> 。

WideControl 標籤

標記 <WideControl> 通常包含 <WideEntries> 標記。卷 <WideEntries> 標包含一或多個 <WideEntry> 標記。卷 <WideEntry> 標包含一個 <WideItem> 標記。

卷 <WideItem> 標必須包含 <PropertyName> 標籤或 <ScriptBlock> 標記。標記 <PropertyName> 會指定要顯示在檢視中指定位置的屬性。標記 <ScriptBlock> 會指定要在檢視中指定位置評估及顯示的腳本。

標記 <WideItem> 可以包含 <FormatString> 指定如何顯示內容的標記。

CustomControl 標籤

標記 <CustomControl> 可讓您使用腳本區塊來定義格式。標記 <CustomControl> 通常包含 <CustomEntries> 包含多個 <CustomEntry> 標記的標籤。每個 <CustomEntry> 標記都包含一個 <CustomItem> 標籤，可以包含各種標記，指定檢視中指定位置的內容和格式，包括 <Text> 、 <Indentation><ExpressionBinding> 和 <NewLine> 標記。

追蹤 Format.ps1xml 檔案使用

若要偵測載入或套用 Format.ps1xml 檔案時發生錯誤，請使用 Trace-Command Cmdlet 搭配下列任何格式元件作為 Name 參數的值：

FormatFileLoading
FormatViewBinding

如需詳細資訊，請參閱 Trace-Command 和 Get-TraceSource。

簽署 Format.ps1xml 檔案

若要保護檔案 Format.ps1xml 的使用者，請使用數位簽章簽署檔案。如需詳細資訊，請參閱 about_Signing。

Format-Table自訂檢視的 XML 範例

下列 XML 範例會 Format-Table 為所 Get-ChildItem 建立的 System.IO.DirectoryInfo和System.IO.FileInfo物件建立自訂檢視。自訂檢視名為 mygciview ，並將 CreationTime 資料行新增至資料表。

若要建立自訂檢視，請使用 Get-FormatData 和 Export-FormatData Cmdlet 來產生 .ps1xml 檔案。然後，編輯檔案 .ps1xml 以建立自訂檢視的程式碼。檔案 .ps1xml 可以儲存在任何 PowerShell 可以存取的目錄中。例如，的 $HOME 子目錄。

.ps1xml建立檔案之後，請使用 Update-FormatData Cmdlet 在目前的 PowerShell 會話中包含檢視。或者，如果您需要所有 PowerShell 會話中可用的檢視，請將更新命令新增至 PowerShell 設定檔。

在此範例中，自訂檢視必須使用資料表格式，否則會 Format-Table 失敗。

搭配 Format-TableView 參數使用來指定自訂檢視的名稱 mygciview，並使用 CreationTime 資料行格式化資料表的輸出。如需如何執行命令的範例，請參閱 Format-Table。

注意

雖然您可以從原始程式碼取得格式化 XML 來建立自訂檢視，但可能需要更多開發才能取得所需的結果。

在下列 Get-FormatData 命令中， PowerShellVersion 參數有替代方法，以確保會傳回所有本機格式資訊。使用 -PowerShellVersion $PSVersionTable.PSVersion 而非特定的 PowerShell 版本。

Get-FormatData -PowerShellVersion 5.1 -TypeName System.IO.DirectoryInfo |
   Export-FormatData -Path ./Mygciview.Format.ps1xml
Update-FormatData -AppendPath ./Mygciview.Format.ps1xml

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <ViewDefinitions>
    <View>
      <Name>mygciview</Name>
      <ViewSelectedBy>
        <TypeName>System.IO.DirectoryInfo</TypeName>
        <TypeName>System.IO.FileInfo</TypeName>
      </ViewSelectedBy>
      <GroupBy>
        <PropertyName>PSParentPath</PropertyName>
      </GroupBy>
      <TableControl>
        <TableHeaders>
          <TableColumnHeader>
            <Label>Mode</Label>
            <Width>7</Width>
            <Alignment>Left</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>LastWriteTime</Label>
            <Width>26</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>CreationTime</Label>
            <Width>26</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>Length</Label>
            <Width>14</Width>
            <Alignment>Right</Alignment>
          </TableColumnHeader>
          <TableColumnHeader>
            <Label>Name</Label>
            <Alignment>Left</Alignment>
          </TableColumnHeader>
        </TableHeaders>
        <TableRowEntries>
          <TableRowEntry>
            <Wrap />
            <TableColumnItems>
              <TableColumnItem>
                <PropertyName>ModeWithoutHardLink</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>LastWriteTime</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>CreationTime</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Length</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Name</PropertyName>
              </TableColumnItem>
            </TableColumnItems>
          </TableRowEntry>
        </TableRowEntries>
      </TableControl>
    </View>
  </ViewDefinitions>
</Configuration>