通过

关于 Format.ps1xml

  • 项目

简短说明

从 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 设置文件可以定义每个对象的四个不同视图：

  • 表
  • 列出
  • Wide
  • 自定义

例如，当命令的 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 属性的值可以很长，因此请指定一个 45 个字符的值作为 <Width>。

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

使用 <TableColumnItem> 和 <PropertyName 标记在表行中添加“日历”的新列项：

<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> 标记。

跟踪 Format.ps1xml 文件使用

若要检测加载或应用 Format.ps1xml 文件时的错误，请将 Trace-Command cmdlet 与以下任一格式组件一起使用作为 Name 参数的值：

  • FormatFileLoading
  • FormatViewBinding

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

对 Format.ps1xml 文件进行签名

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

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

以下 XML 示例为 创建的 Get-ChildItemSystem.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 会话中可用的视图，请将 update 命令添加到 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>

另请参阅

Export-FormatData

Get-FormatData

Get-TraceSource

格式架构 XML 参考

Trace-Command

Update-FormatData

编写 PowerShell 格式设置文件