about_Format.ps1xml

簡短描述

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

詳細描述

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

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

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

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

1. Certificate.Format.ps1xml

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

2. DotNetTypes.Format.ps1xml

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

3. FileSystem.Format.ps1xml

   檔案系統物件，例如檔案和目錄。

4. Help.Format.ps1xml

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

5. PowerShellCore.Format.ps1xml

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

6. PowerShellTrace.Format.ps1xml

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

7. 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>

另請參閱

• Trace-Command
• Export-FormatData
• Get-FormatData
• Update-FormatData
• Get-TraceSource
• 格式架構 XML 參考
• 撰寫 PowerShell 格式檔案