about_Format.ps1xml

發行項
03/19/2024

簡短描述

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

詳細描述

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

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

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

PowerShell 包含七個格式化檔案。這些檔案位於安裝目錄（$PSHOME）。每個檔案都會定義一組Microsoft .NET Framework 物件的顯示：

Certificate.Format.ps1xml

證書存儲中的物件，例如 X.509 憑證和證書存儲。
DotNetTypes.Format.ps1xml

其他 .NET Framework 類型，例如 CultureInfo、FileVersionInfo 和 EventLogEntry 物件。
FileSystem.Format.ps1xml

檔案系統物件，例如檔案和目錄。
Help.Format.ps1xml

說明檢視，例如詳細和完整的檢視、參數和範例。
PowerShellCore.Format.ps1xml

PowerShell 核心 Cmdlet 所產生的物件，例如 Get-Member 和 Get-History。
PowerShellTrace.Format.ps1xml

追蹤物件，例如 Cmdlet 所產生的 Trace-Command 物件。
Registry.Format.ps1xml

登錄物件，例如機碼和專案。

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

Table
清單
寬
自訂

例如，當命令的 Get-ChildItem 輸出管道傳送至 Format-List 命令時， Format-List 會使用檔案中的 FileSystem.Format.ps1xml 檢視來判斷如何將檔案和資料夾物件顯示為清單。

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

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

建立新的 Format.ps1xml 檔案

.ps1xml隨 PowerShell 一起安裝的檔案會經過數字簽署，以防止竄改，因為格式可以包含腳本區塊。若要變更現有物件檢視的顯示格式，或新增新對象的檢視，請建立您自己的 Format.ps1xml 檔案，然後將它們新增至 PowerShell 會話。

若要建立新的檔案，請複製現有的 Format.ps1xml 檔案。新檔案可以有任何名稱，但必須有 .ps1xml 擴展名。您可以將新檔案放在 PowerShell 可存取的任何目錄中，但是將檔案放在 PowerShell 安裝目錄（$PSHOME）或安裝目錄的子目錄中很有用。

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

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

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

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

第一個步驟是尋找 Format.ps1xml 包含目前文化特性對象檢視的檔案。下列 Select-String 命令會尋找檔案：

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.Globalization.CultureInfo"
}

Select-String @Parms

C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:113:
     <Name>System.Globalization.CultureInfo</Name>
C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:115:
<TypeName>System.Globalization.CultureInfo</TypeName>

此命令會顯示定義位於檔案中 DotNetTypes.Format.ps1xml 。

下一個指令會將檔案內容複製到新的檔案 MyDotNetTypes.Format.ps1xml。

Copy-Item $PSHome\DotNetTypes.format.ps1xml MyDotNetTypes.Format.ps1xml

MyDotNetTypes.Format.ps1xml在任何 XML 或文本編輯器中開啟檔案，例如 Visual Studio Code。 尋找 System.Globalization.CultureInfo 物件區段。下列 XML 會定義 CultureInfo 物件的檢視。物件只有 TableControl 檢視。

<View>
  <Name>System.Globalization.CultureInfo</Name>
  <ViewSelectedBy>
    <TypeName>Deserialized.System.Globalization.CultureInfo</TypeName>
    <TypeName>System.Globalization.CultureInfo</TypeName>
  </ViewSelectedBy>
  <TableControl>
    <TableHeaders>
      <TableColumnHeader>
        <Width>16</Width>
      </TableColumnHeader>
      <TableColumnHeader>
        <Width>16</Width>
      </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>

刪除檔案的其餘部分，但開頭 <?xml>、 <Configuration>和 <ViewDefinitions> 標籤以及結尾 <ViewDefinitions> 和 <Configuration> 標記除外。如果有數位簽名，請從您的自定義 Format.ps1xml檔案中刪除它。

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

<?xml version="1.0" encoding="utf-8" ?>
<Configuration>
<ViewDefinitions>
<View>
  <Name>System.Globalization.CultureInfo</Name>
  <ViewSelectedBy>
    <TypeName>Deserialized.System.Globalization.CultureInfo</TypeName>
    <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 $PSHOME\MyDotNetTypes.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> 標記。

Types.ps1xml 中的默認顯示

目錄中的檔案$PSHOME中Types.ps1xml會定義某些基本物件類型的默認顯示。節點的名稱為 PsStandardMembers，而子節點會使用下列其中一個標記：

<DefaultDisplayProperty>
<DefaultDisplayPropertySet>
<DefaultKeyPropertySet>

如需詳細資訊，請參閱 about_Types.ps1xml。

追蹤 Format.ps1xml 檔案使用

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

FormatFileLoading
FormatViewBinding

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

簽署 Format.ps1xml 檔案

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

Format-Table 自定義檢視的範例 XML

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

自定義檢視是從儲存在 $PSHOME PowerShell 5.1上之檔案的FileSystem.Format.ps1xml編輯版本建立。

儲存自定義 .ps1xml 檔案之後，請使用 Update-FormatData 在 PowerShell 工作階段中包含檢視。在此範例中，自定義檢視必須使用數據表格式，否則會 Format-Table 失敗。

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

$Parms = @{
  Path = "$PSHOME\*Format.ps1xml"
  Pattern = "System.IO.DirectoryInfo"
}
Select-String @Parms
Copy-Item $PSHome\FileSystem.format.ps1xml .\MyFileSystem.Format.ps1xml
Update-FormatData -PrependPath $PSHOME\Format\MyFileSystem.Format.ps1xml

注意

若要符合行寬限制內的 XML 範例，必須壓縮部分縮排，並在程式代碼中使用換行符。

<?xml version="1.0" encoding="utf-8" ?>
<Configuration>
    <SelectionSets>
        <SelectionSet>
            <Name>FileSystemTypes</Name>
            <Types>
                <TypeName>System.IO.DirectoryInfo</TypeName>
                <TypeName>System.IO.FileInfo</TypeName>
            </Types>
        </SelectionSet>
    </SelectionSets>
<Controls>
<Control>
<Name>FileSystemTypes-GroupingFormat</Name>
<CustomControl>
 <CustomEntries>
  <CustomEntry>
    <CustomItem>
    <Frame>
    <LeftIndent>4</LeftIndent>
    <CustomItem>
    <Text AssemblyName="System.Management.Automation"
    BaseName="FileSystemProviderStrings"
    ResourceId="DirectoryDisplayGrouping"/>
    <ExpressionBinding>
     <ScriptBlock>
      $_.PSParentPath.Replace("Microsoft.PowerShell.Core\FileSystem::", "")
     </ScriptBlock>
    </ExpressionBinding>
    <NewLine/>
    </CustomItem>
    </Frame>
    </CustomItem>
    </CustomEntry>
 </CustomEntries>
</CustomControl>
</Control>
</Controls>
<ViewDefinitions>
    <View>
    <Name>mygciview</Name>
    <ViewSelectedBy>
        <SelectionSetName>FileSystemTypes</SelectionSetName>
    </ViewSelectedBy>
    <GroupBy>
      <PropertyName>PSParentPath</PropertyName>
      <CustomControlName>FileSystemTypes-GroupingFormat</CustomControlName>
    </GroupBy>
        <TableControl>
            <TableHeaders>
                <TableColumnHeader>
                    <Label>Mode</Label>
                    <Width>7</Width>
                    <Alignment>left</Alignment>
                </TableColumnHeader>
                <TableColumnHeader>
                    <Label>LastWriteTime</Label>
                    <Width>25</Width>
                    <Alignment>right</Alignment>
                </TableColumnHeader>
                <TableColumnHeader>
                    <Label>CreationTime</Label>
                    <Width>25</Width>
                    <Alignment>right</Alignment>
                </TableColumnHeader>
                <TableColumnHeader>
                    <Label>Length</Label>
                    <Width>14</Width>
                    <Alignment>right</Alignment>
                </TableColumnHeader>
                <TableColumnHeader/>
            </TableHeaders>
            <TableRowEntries>
                <TableRowEntry>
                    <Wrap/>
                    <TableColumnItems>
                        <TableColumnItem>
                            <PropertyName>Mode</PropertyName>
                        </TableColumnItem>
                        <TableColumnItem>
                            <ScriptBlock>
                                [String]::Format("{0,10}  {1,8}",
                                    $_.LastWriteTime.ToString("d"),
                                    $_.LastWriteTime.ToString("t"))
                            </ScriptBlock>
                        </TableColumnItem>
                        <TableColumnItem>
                            <ScriptBlock>
                                [String]::Format("{0,10}  {1,8}",
                                    $_.CreationTime.ToString("d"),
                                    $_.LastWriteTime.ToString("t"))
                            </ScriptBlock>
                        </TableColumnItem>
                        <TableColumnItem>
                        <PropertyName>Length</PropertyName>
                        </TableColumnItem>
                        <TableColumnItem>
                            <PropertyName>Name</PropertyName>
                        </TableColumnItem>
                    </TableColumnItems>
                </TableRowEntry>
            </TableRowEntries>
        </TableControl>
    </View>
  </ViewDefinitions>
</Configuration>

共用方式為