| Server IP : 134.29.175.74 / Your IP : 216.73.216.160 Web Server : nginx/1.10.2 System : Windows NT CST-WEBSERVER 10.0 build 19045 (Windows 10) i586 User : Administrator ( 0) PHP Version : 7.1.0 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Windows/System32/WindowsPowerShell/v1.0/en-US/ |
Upload File : |
ABOUT FORMAT.PS1XML
Short description
The Format.ps1xml files in PowerShell define the default display of objects
in the PowerShell console. You can create your own Format.ps1xml files to
change the display of objects or to define default displays for new object
types that you create in PowerShell.
Long description
The Format.ps1xml files in PowerShell define the default display of objects
in PowerShell. You can create your own Format.ps1xml files to change the
display of objects or to define default displays for new object types that
you create in PowerShell.
When PowerShell displays an object, it uses the data in structured
formatting files to determine the default display of the object. The data
in the formatting files determines whether the object is rendered in a
table or in a list, and it determines which properties are displayed by
default.
The formatting affects the display only. It doesn't affect which object
properties are passed down the pipeline or how they're passed.
Format.ps1xml files can't be used to customize the output format for hash
tables.
PowerShell includes seven formatting files. These files are located in the
installation directory ($PSHOME). Each file defines the display of a group
of Microsoft .NET Framework objects:
1. Certificate.Format.ps1xml
Objects in the Certificate store, such as X.509 certificates and
certificate stores.
2. DotNetTypes.Format.ps1xml
Other .NET Framework types, such as CultureInfo, FileVersionInfo, and
EventLogEntry objects.
3. FileSystem.Format.ps1xml
File system objects, such as files and directories.
4. Help.Format.ps1xml
Help views, such as detailed and full views, parameters, and examples.
5. PowerShellCore.Format.ps1xml
Objects generated by PowerShell core cmdlets, such as Get-Member and
Get-History.
6. PowerShellTrace.Format.ps1xml
Trace objects, such as those generated by the Trace-Command cmdlet.
7. Registry.Format.ps1xml
Registry objects, such as keys and entries.
A formatting file can define four different views of each object:
- Table
- List
- Wide
- Custom
For example, when the output of a Get-ChildItem command is piped to a
Format-List command, Format-List uses the view in the
FileSystem.Format.ps1xml file to determine how to display the file and
folder objects as a list.
When a formatting file includes more than one view of an object, PowerShell
applies the first view that it finds.
In a Format.ps1xml file, a view is defined by a set of XML tags that
describe the name of the view, the type of object to which it can be
applied, the column headers, and the properties that are displayed in the
body of the view. The format in Format.ps1xml files is applied just before
the data is presented to the user.
Creating new Format.ps1xml files
The .ps1xml files that are installed with PowerShell are digitally signed
to prevent tampering because the formatting can include script blocks. To
change the display format of an existing object view, or to add views for
new objects, create your own Format.ps1xml files, and then add them to your
PowerShell session.
To create a new file, copy an existing Format.ps1xml file. The new file can
have any name, but it must have a .ps1xml file name extension. You can
place the new file in any directory that is accessible to PowerShell, but
it's useful to place the files in the PowerShell installation directory
($PSHOME) or in a subdirectory of the installation directory.
To change the formatting of a current view, locate the view in the
formatting file, and then use the tags to change the view. To create a view
for a new object type, create a new view, or use an existing view as a
model. The tags are described in the next section. You can then delete all
the other views in the file so that the changes are obvious to anyone
examining the file.
After you save the changes, use the Update-FormatData cmdlet to add the new
file to your PowerShell session. If you want your view to take precedence
over a view defined in the built-in files, use the PREPENDPATH parameter.
Update-FormatData affects only the current session. To make the change to
all future sessions, add the Update-FormatData command to your PowerShell
profile.
Example: Adding calendar data to culture objects
This example shows how to change the formatting of the culture objects
SYSTEM.GLOBALIZATION.CULTUREINFO generated by the Get-Culture cmdlet in the
current PowerShell session. The commands in the example add the CALENDAR
property to the default table view display of culture objects.
The first step is to find the Format.ps1xml file that contains the current
view of the culture objects. The following Select-String command finds the
file:
$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>
This command reveals that the definition is in the
DotNetTypes.Format.ps1xml file.
The next command copies the file contents to a new file,
MyDotNetTypes.Format.ps1xml.
Copy-Item $PSHome\DotNetTypes.format.ps1xml MyDotNetTypes.Format.ps1xml
Open the MyDotNetTypes.Format.ps1xml file in any XML or text editor, such
as Visual Studio Code. Find the SYSTEM.GLOBALIZATION.CULTUREINFO object
section. The following XML defines the views of the CULTUREINFO object. The
object has only a TABLECONTROL view.
<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>
Delete the remainder of the file, except for the opening <?xml>,
<Configuration>, and <ViewDefinitions> tags and the closing
<ViewDefinitions> and <Configuration> tags. If there is a digital
signature, delete it from your custom Format.ps1xmlfile.
The MyDotNetTypes.Format.ps1xml file should now look like the following
sample:
<?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>
Create a new column for the CALENDAR property by adding a new set of
<TableColumnHeader> tags. The value of the CALENDAR property can be long,
so specify a value of 45 characters as the <Width>.
<TableHeaders>
<TableColumnHeader>
<Width>16</Width>
</TableColumnHeader>
<TableColumnHeader>
<Width>16</Width>
</TableColumnHeader>
<TableColumnHeader>
<Width>45</Width>
</TableColumnHeader>
<TableColumnHeader/>
</TableHeaders>
Add a new column item for CALENDAR in the table rows using the
<TableColumnItem> and <PropertyName tags:
<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>
Save and close the file. Use Update-FormatData to add the new format file
to the current PowerShell session.
This example uses the PREPENDPATH parameter to place the new file in a
higher precedence order than the original file. For more information, see
Update-FormatData.
Update-FormatData -PrependPath $PSHOME\MyDotNetTypes.Format.ps1xml
To test the change, type Get-Culture and review the output that includes
the CALENDAR property.
Get-Culture
LCID Name Calendar DisplayName
---- ---- -------- -----------
1033 en-US System.Globalization.GregorianCalendar English (United States)
The XML in Format.ps1xml files
The full schema definition can be found in Format.xsd in the PowerShell
source code repository on GitHub.
The VIEWDEFINITIONS section of each Format.ps1xml file contains the <View>
tags that define each view. A typical <View> tag includes the following
tags:
- <Name> identifies the name of the view.
- <ViewSelectedBy> specifies the object type or types to which the view
applies.
- <GroupBy> specifies how items in the view will be combined in groups.
- <TableControl>, <ListControl>, <WideControl>, and <CustomControl>
contain the tags that specify how each item will be displayed.
ViewSelectedBy tag
The <ViewSelectedBy> tag can contain a <TypeName> tag for each object type
to which the view applies. Or, it can contain a <SelectionSetName> tag that
references a selection set that is defined elsewhere by using a
<SelectionSet> tag.
GroupBy tag
The <GroupBy> tag contains a <PropertyName> tag that specifies the object
property by which items are to be grouped. It also contains either a
<Label> tag that specifies a string to be used as a label for each group or
a <CustomControlName> tag that references a custom control defined
elsewhere using a <Control> tag. The <Control> tag contains a <Name> tag
and a <CustomControl> tag.
TableControlTag
The <TableControl> tag typically contains <TableHeaders> and
<TableRowEntries> tags that define the formatting for the table's heads and
rows. The <TableHeaders> tag typically contains <TableColumnHeader> tags
that contain <Label>, <Width>, and <Alignment> tags. The <TableRowEntries>
tag contains <TableRowEntry> tags for each row in the table. The
<TableRowEntry> tag contains a <TableColumnItems> tag that contains a
<TableColumnItem> tag for each column in the row. Typically, the
<TableColumnItem> tag contains either a <PropertyName> tag that identifies
the object property to be displayed in the defined location, or a
<ScriptBlock> tag that contains script code that calculates a result that
is to be displayed in the location.
[!NOTE] Script blocks can also be used elsewhere in locations where
calculated results can be useful.
The <TableColumnItem> tag can also contain a <FormatString> tag that
specifies how the property or the calculated results will be displayed.
ListControl tag
The <ListControl> tag typically contains a <ListEntries> tag. The
<ListEntries> tag contains a <ListEntry> tag. The <ListEntry> tag contains
a <ListItems> tag. The <ListItems> tag contains <ListItem> tags, which
contain <PropertyName> tags. The <PropertyName> tags specify the object
property to be displayed at the specified location in the list. If the view
selection is defined using a selection set, the <ListControl> and
<ListEntry> tags can also contain an <EntrySelectedBy> tag that contains
one or more <TypeName> tags. These <TypeName> tags specify the object type
that the <ListControl> tag is intended to display.
WideControl tag
The <WideControl> tag typically contains a <WideEntries> tag. The
<WideEntries> tag contains one or more <WideEntry> tags. A <WideEntry> tag
typically contains a <PropertyName> tag that specifies the property to be
displayed at the specified location in the view. The <PropertyName> tag can
contain a <FormatString> tag that specifies how the property is to be
displayed.
CustomControl tag
The <CustomControl> tag lets you use a script block to define a format. A
<CustomControl> tag typically contains a <CustomEntries> tag that contains
multiple <CustomEntry> tags. Each <CustomEntry> tag contains a <CustomItem>
tag that can contain a variety of tags that specify contents and formatting
of the specified location in the view, including <Text>, <Indentation>,
<ExpressionBinding>, and <NewLine> tags.
Default displays in Types.ps1xml
The default displays of some basic object types are defined in the
Types.ps1xml file in the $PSHOME directory. The nodes are named
PSSTANDARDMEMBERS, and the subnodes use one of the following tags:
- <DefaultDisplayProperty>
- <DefaultDisplayPropertySet>
- <DefaultKeyPropertySet>
For more information, see about_Types.ps1xml.
Tracing Format.ps1xml file use
To detect errors in the loading or application of Format.ps1xml files, use
the Trace-Command cmdlet with any of the following format components as the
value of the NAME parameter:
- FormatFileLoading
- FormatViewBinding
For more information, see Trace-Command and Get-TraceSource.
Signing a Format.ps1xml file
To protect the users of your Format.ps1xml file, sign the file using a
digital signature. For more information, see about_Signing.
Sample XML for a Format-Table custom view
The following sample creates a Format-Table custom view for the
SYSTEM.IO.DIRECTORYINFO and SYSTEM.IO.FILEINFO objects created by
Get-ChildItem. The custom view is named MYGCIVIEW and adds the CREATIONTIME
column to the table.
The custom view is created from an edited version of the
FileSystem.Format.ps1xml file that's stored in $PSHOME on PowerShell 5.1.
After your custom .ps1xml file is saved, use Update-FormatData to include
the view in a PowerShell session. For this example, the custom view must
use the table format, otherwise, Format-Table fails.
Use Format-Table with the VIEW parameter to specify the custom view's name
and format the table's output. For an example of how the command is run,
see 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
[!NOTE] To fit the XML sample within line width limitations, it was
necessary to compress some indentation and use line breaks within the
code.
<?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>
See also
Export-FormatData
Get-FormatData
Get-TraceSource
Format Schema XML Reference
Trace-Command
Update-FormatData
Writing a PowerShell Formatting File