about_Format.ps1xml

项目
10/07/2023

简短说明

从 PowerShell 6 开始，对象的默认视图在 PowerShell 源代码中定义。

你可以创建自己的 Format.ps1xml 文件来更改对象的显示，或为在 PowerShell 中创建的新对象类型定义默认显示。

长说明

从 PowerShell 6 开始，默认视图在 PowerShell 源代码中定义。 PowerShell 5.1 及更低版本中的 Format.ps1xml 文件在 PowerShell 6 及更高版本中不存在。

PowerShell 源代码定义 PowerShell 控制台中对象的默认显示。你可以创建自己的 Format.ps1xml 文件来更改对象的显示，或为在 PowerShell 中创建的新对象类型定义默认显示。

当 PowerShell 显示对象时，它会使用结构化格式文件中的数据来确定对象的默认显示。格式设置文件中的数据决定对象是以表还是列表形式呈现，并决定默认情况下显示哪些属性。

格式设置仅影响显示。它不会影响哪些对象属性在管道中传递或传递方式。 Format.ps1xml 文件不能用于自定义哈希表的输出格式。

.ps1xml 格式设置文件可以定义每个对象的四个不同视图：

表
列表
宽
自定义

例如，当 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 配置文件。

示例：将日历数据添加到区域性对象

此示例演示如何更改由 Get-Culture cmdlet 在当前 PowerShell 会话中生成的区域性对象 System.Globalization.CultureInfo 的格式。示例中的命令将 Calendar 属性添加到区域性对象的默认表视图显示中。

首先，从源代码文件获取格式数据，并创建一个包含区域性对象的当前视图的 Format.ps1xml 文件。

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

在任何 XML 或文本编辑器（如 Visual Studio Code）中打开 CultureInfo.Format.ps1xml 文件。以下 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> 标记（其指定要用作每个组的标签的字符串）或者一个 <Control> 标记，其引用使用 <CustomControlName> 标记在其他位置定义的自定义控件。 <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 文件时发生的错误，请结合以下任何格式组成部分（用作 Name 参数的值）使用 Trace-Command cmdlet：

FormatFileLoading
FormatViewBinding

有关详细信息，请参阅 Trace-Command 和 Get-TraceSource。

为 Format.ps1xml 文件签名

若要保护 Format.ps1xml 文件的用户，请使用数字签名对文件进行签名。有关详细信息，请参阅 about_Signing。

Format-Table 自定义视图的示例 XML

以下 XML 示例为 Get-ChildItem 创建的 System.IO.DirectoryInfo 和 System.IO.FileInfo 对象创建 Format-Table 自定义视图。自定义视图命名为 mygciview，并将 CreationTime 列添加到表中。

若要创建自定义视图，请使用 Get-FormatData 和 Export-FormatData cmdlet 生成 .ps1xml 文件。然后，编辑 .ps1xml 文件，为自定义视图创建代码。 .ps1xml 文件可以存储在 PowerShell 可访问的任何目录中。例如，$HOME 的子目录。

创建 .ps1xml 文件后，使用 Update-FormatData cmdlet 将视图包含在当前 PowerShell 会话中。或者，如果需要所有 PowerShell 会话中可用的视图，请将更新命令添加到 PowerShell 配置文件。

对于此示例，自定义视图必须使用表格式，否则 Format-Table 会失败。

将 Format-Table 与 View 参数一起使用，以指定自定义视图的名称、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>