about_Format.ps1xml

發行項
03/19/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格式化檔案可以定義每個物件的四個不同的檢視：

Table
清單
寬
自訂

例如，當命令的 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 屬性的值可以是 long，因此請將 45 個字元的值指定為 <Width>。

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

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

<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 失敗。

搭配 View 參數使用 Format-Table 來指定自定義檢視的名稱 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>