關於 Format.ps1xml

發行項
05/09/2024

簡短描述

從 PowerShell 6 開始，對象的預設檢視定義於 PowerShell 原始程式碼中。

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

完整描述

從 PowerShell 6 開始，預設檢視會在 PowerShell 原始碼中定義。 Format.ps1xml PowerShell 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>新的標記，Create Calendar 屬性的新數據行。 Calendar 屬性的值可以是 long，因此請將 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> 通常包含 <PropertyName> 標記，指定要顯示在檢視中指定位置的屬性。標籤 <PropertyName> 可以包含 <FormatString> 標記，指定屬性的顯示方式。

CustomControl 標籤

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

追蹤格式.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>