about_Format.ps1xml
简短说明
PowerShell 中的 Format.ps1xml
文件定义 PowerShell 控制台中对象的默认显示。 可以创建自己的 Format.ps1xml
文件来更改对象的显示,或为在 PowerShell 中创建的新对象类型定义默认显示。
长说明
PowerShell 中的 Format.ps1xml
文件定义 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
跟踪对象,例如由
Trace-Command
cmdlet 生成的对象。Registry.Format.ps1xml
注册表对象,例如键和条目。
格式设置文件可以定义每个对象的四个不同的视图:
- 表
- 列表
- 宽
- 自定义
例如,当 Get-ChildItem
命令的输出通过管道传递给 Format-List
命令时,Format-List
使用 FileSystem.Format.ps1xml
文件中的视图来确定如何将文件和文件夹对象显示为列表。
当格式设置文件包含对象的多个视图时,PowerShell 将应用它找到的第一个视图。
在 Format.ps1xml
文件中,视图由一组 XML 标记定义,这些标记描述视图的名称、可向其应用的对象类型、列标题以及视图正文中显示的属性。 Format.ps1xml
文件中的格式是在数据呈现给用户之前应用的。
创建新的 Format.ps1xml 文件
随 PowerShell 安装的 .ps1xml
文件经过数字签名以防止篡改,因为格式可能包含脚本块。 若要更改现有对象视图的显示格式或为新对象添加视图,请创建自己的 Format.ps1xml
文件,然后将其添加到 PowerShell 会话。
若要创建新文件,复制现有 Format.ps1xml
文件。 新文件可以具有任何名称,但必须具有 .ps1xml
文件扩展名。 可以将新文件放置在 PowerShell 可访问的任何目录中,但将文件放置在 PowerShell 安装目录 ($PSHOME
) 或安装目录的子目录中会很有用。
若要更改当前视图的格式,请在格式设置文件中找到视图,然后使用标记更改视图。 若要为新对象类型创建视图,请创建新视图,或使用现有视图作为模型。 下一部分将介绍标记。 然后,可以删除文件中的所有其他视图,以便检查该文件的任何人都可以看到这些更改。
保存更改后,请使用 Update-FormatData
cmdlet 将新文件添加到 PowerShell 会话。 如果希望视图优先于内置文件中定义的视图,请使用 PrependPath 参数。
Update-FormatData
仅影响当前会话。 若要对所有将来的会话进行更改,请将 Update-FormatData
命令添加到 PowerShell 配置文件。
示例:将日历数据添加到区域性对象
此示例显示如何更改由 Get-Culture
cmdlet 在当前 PowerShell 会话中生成的区域性对象 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
在任何 XML 或文本编辑器(如 Visual Studio Code)中打开 MyDotNetTypes.Format.ps1xml
文件。 查找 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 属性的值可能很长,因此请指定一个包含 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 $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>
标记(其指定要用作每个组的标签的字符串)或者一个 <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>
标记。
Types.ps1xml 中的默认显示
某些基本对象类型的默认显示在 $PSHOME
目录中的 Types.ps1xml
文件中定义。 节点命名为“PsStandardMembers”,子节点使用以下标签之一:
<DefaultDisplayProperty>
<DefaultDisplayPropertySet>
<DefaultKeyPropertySet>
有关详细信息,请参阅 about_Types.ps1xml。
跟踪 Format.ps1xml 文件使用
若要检测加载或应用 Format.ps1xml
文件时发生的错误,请结合以下任何格式组成部分(用作 Name 参数的值)使用 Trace-Command
cmdlet:
- FormatFileLoading
- FormatViewBinding
有关详细信息,请参阅 Trace-Command 和 Get-TraceSource。
为 Format.ps1xml 文件签名
若要保护 Format.ps1xml
文件的用户,请使用数字签名对文件进行签名。 有关详细信息,请参阅 about_Signing。
Format-Table 自定义视图的示例 XML
以下示例为 Get-ChildItem
创建的 System.IO.DirectoryInfo 和 System.IO.FileInfo 对象创建 Format-Table
自定义视图。 自定义视图命名为 mygciview,并将 CreationTime 列添加到表中。
自定义视图是从 PowerShell 5.1 $PSHOME
中存储的 FileSystem.Format.ps1xml
文件的编辑版本创建的。
保存自定义 .ps1xml
文件后,请使用 Update-FormatData
在 PowerShell 会话中包含视图。 对于此示例,自定义视图必须使用表格式,否则 Format-Table
会失败。
将 Format-Table
与 View 参数一起使用,以指定自定义视图的名称并设置表的输出格式。 有关如何运行命令的示例,请参阅 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>