diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 8e7518e6e313..ca996409bbef 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- 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. Locale: en-US -ms.date: 04/25/2022 +ms.date: 12/26/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Format.ps1xml @@ -88,7 +88,7 @@ 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 +## 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 @@ -98,9 +98,7 @@ 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. +the new file in any directory that is accessible to PowerShell. 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 @@ -127,12 +125,11 @@ view of the culture objects. The following `Select-String` command finds the file: ```powershell -$Parms = @{ - Path = "$PSHOME\*Format.ps1xml" - Pattern = "System.Globalization.CultureInfo" +$selectParams = @{ + Path = "$PSHOME\*Format.ps1xml" + Pattern = 'System.Globalization.CultureInfo' } - -Select-String @Parms +Select-String @selectParams ``` ```Output @@ -142,14 +139,20 @@ C:\Windows\System32\WindowsPowerShell\v1.0\DotNetTypes.format.ps1xml:115: System.Globalization.CultureInfo ``` -This command reveals that the definition is in the `DotNetTypes.Format.ps1xml` +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`. +The following commands copy the file contents to a new file named +`MyDotNetTypes.Format.ps1xml` in a newly created `$HOME\Format` directory. ```powershell -Copy-Item $PSHOME\DotNetTypes.format.ps1xml MyDotNetTypes.Format.ps1xml +New-Item -Path $HOME\Format -ItemType Directory -Force + +$copyParams = @{ + LiteralPath = "$PSHOME\DotNetTypes.format.ps1xml" + Destination = "$HOME\Format\MyDotNetTypes.Format.ps1xml" +} +Copy-Item @copyParams ``` Open the `MyDotNetTypes.Format.ps1xml` file in any XML or text editor, such as @@ -289,10 +292,10 @@ 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](xref:Microsoft.PowerShell.Utility.Update-FormatData). +[Update-FormatData][03]. ```powershell -Update-FormatData -PrependPath $HOME\Format\CultureInfo.Format.ps1xml +Update-FormatData -PrependPath $HOME\Format\MyDotNetTypes.Format.ps1xml ``` To test the change, type `Get-Culture` and review the output that includes the @@ -310,8 +313,8 @@ LCID Name Calendar DisplayName ## The XML in Format.ps1xml files -The full schema definition can be found in [Format.xsd](https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Format.xsd) -in the PowerShell source code repository on GitHub. +The full schema definition can be found in [Format.xsd][04] in the PowerShell +source code repository on GitHub. The **ViewDefinitions** section of each `Format.ps1xml` file contains the `` tags that define each view. A typical `` tag includes the @@ -376,13 +379,13 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` tag -contains one `` tag. +`` tag contains one or more `` tags. A `` +tag contains one `` tag. A `` tag must include either a `` tag or a -`` tag. A `` tag specifies the property to display at -the specified location in the view. A `` tag specifies a script to -evaluate and display at the specified location in the view. +`` tag. A `` tag specifies the property to display +at the specified location in the view. A `` tag specifies a script +to evaluate and display at the specified location in the view. A `` tag can contain a `` tag that specifies how to display the property. @@ -396,7 +399,7 @@ multiple `` tags. Each `` tag contains a formatting of the specified location in the view, including ``, ``, ``, and `` tags. -## DEFAULT DISPLAYS IN TYPES.PS1XML +## 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 @@ -417,15 +420,12 @@ value of the **Name** parameter: - FormatFileLoading - FormatViewBinding -For more information, see -[Trace-Command](xref:Microsoft.PowerShell.Utility.Trace-Command) and -[Get-TraceSource](xref:Microsoft.PowerShell.Utility.Get-TraceSource). +For more information, see [Trace-Command][05] and [Get-TraceSource][06]. ## 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](about_Signing.md). +digital signature. For more information, see [about_Signing][07]. ## Sample XML for a Format-Table custom view @@ -434,25 +434,38 @@ The following sample creates a `Format-Table` custom view for the `Get-ChildItem`. The custom view is named **MyGciView** and adds the **CreationTime** column to the table. +Use `Select-String` to identify which `Format.ps1xml` file contains data for +the type you're looking for. + 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. +After the custom `.ps1xml` file is saved, use the `Update-FormatData` cmdlet to +include the view in the current PowerShell session. Or, add the update command +to your PowerShell profile if you need the view available in all PowerShell +sessions. + +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](xref:Microsoft.PowerShell.Utility.Format-Table). +name, **MyGciView**, and format the table's output with the **CreationTime** +column. For an example of how the command is run, see [Format-Table][08]. ```powershell -$Parms = @{ - Path = "$PSHOME\*Format.ps1xml" - Pattern = "System.IO.DirectoryInfo" +$selectParams = @{ + 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 +Select-String @selectParams + +$copyParams = @{ + LiteralPath = "$PSHOME\FileSystem.format.ps1xml" + Destination = "$HOME\Format\MyFileSystem.Format.ps1xml" +} +Copy-Item @copyParams + +Update-FormatData -PrependPath $HOME\Format\MyFileSystem.Format.ps1xml ``` > [!NOTE] @@ -582,9 +595,10 @@ Update-FormatData -PrependPath $PSHOME\Format\MyFileSystem.Format.ps1xml [01]: xref:Microsoft.PowerShell.Utility.Get-FormatData [02]: xref:Microsoft.PowerShell.Utility.Export-FormatData [03]: xref:Microsoft.PowerShell.Utility.Update-FormatData - +[04]: https://github.com/PowerShell/PowerShell/blob/master/src/Schemas/Format.xsd [05]: xref:Microsoft.PowerShell.Utility.Trace-Command [06]: xref:Microsoft.PowerShell.Utility.Get-TraceSource - +[07]: about_Signing.md +[08]: xref:Microsoft.PowerShell.Utility.Format-Table [09]: /powershell/scripting/developer/format/format-schema-xml-reference [10]: /powershell/scripting/developer/format/writing-a-powershell-formatting-file diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 64ca92f95698..e4d49cef93ed 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code. 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. Locale: en-US -ms.date: 04/25/2022 +ms.date: 12/26/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Format.ps1xml @@ -93,8 +93,10 @@ To begin, get the format data from the source code file and create a `Format.ps1xml` file that contains the current view of the culture objects. ```powershell +New-Item -Path $HOME\Format -ItemType Directory -Force + Get-FormatData -TypeName System.Globalization.CultureInfo | - Export-FormatData -Path $HOME\Format\CultureInfo.Format.ps1xml + Export-FormatData -LiteralPath $HOME\Format\CultureInfo.Format.ps1xml ``` Open the `CultureInfo.Format.ps1xml` file in any XML or text editor, such as @@ -278,8 +280,8 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` tag -contains one `` tag. +`` tag contains one or more `` tags. A `` +tag contains one `` tag. A `` tag must include either a `` tag or a `` tag. A `` tag specifies the property to display @@ -349,8 +351,9 @@ specific PowerShell version. ```powershell Get-FormatData -PowerShellVersion 5.1 -TypeName System.IO.DirectoryInfo | - Export-FormatData -Path ./MyGciView.Format.ps1xml -Update-FormatData -AppendPath ./MyGciView.Format.ps1xml + Export-FormatData -LiteralPath $HOME\Format\MyGciView.Format.ps1xml + +Update-FormatData -AppendPath $HOME\Format\MyGciView.Format.ps1xml ``` ```xml diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index d74b9d8de1c1..ff09056394e1 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code. 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. Locale: en-US -ms.date: 04/25/2022 +ms.date: 12/26/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Format.ps1xml @@ -93,8 +93,10 @@ To begin, get the format data from the source code file and create a `Format.ps1xml` file that contains the current view of the culture objects. ```powershell +New-Item -Path $HOME\Format -ItemType Directory -Force + Get-FormatData -TypeName System.Globalization.CultureInfo | - Export-FormatData -Path $HOME\Format\CultureInfo.Format.ps1xml + Export-FormatData -LiteralPath $HOME\Format\CultureInfo.Format.ps1xml ``` Open the `CultureInfo.Format.ps1xml` file in any XML or text editor, such as @@ -278,8 +280,8 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` tag -contains one `` tag. +`` tag contains one or more `` tags. A `` +tag contains one `` tag. A `` tag must include either a `` tag or a `` tag. A `` tag specifies the property to display @@ -349,8 +351,9 @@ specific PowerShell version. ```powershell Get-FormatData -PowerShellVersion 5.1 -TypeName System.IO.DirectoryInfo | - Export-FormatData -Path ./MyGciView.Format.ps1xml -Update-FormatData -AppendPath ./MyGciView.Format.ps1xml + Export-FormatData -Path $HOME\Format\MyGciView.Format.ps1xml + +Update-FormatData -AppendPath $HOME\Format\MyGciView.Format.ps1xml ``` ```xml diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 6d6db494c8f3..b8cefcf7a508 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code. 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. Locale: en-US -ms.date: 04/25/2022 +ms.date: 12/26/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Format.ps1xml @@ -93,8 +93,10 @@ To begin, get the format data from the source code file and create a `Format.ps1xml` file that contains the current view of the culture objects. ```powershell +New-Item -Path $HOME\Format -ItemType Directory -Force + Get-FormatData -TypeName System.Globalization.CultureInfo | - Export-FormatData -Path $HOME\Format\CultureInfo.Format.ps1xml + Export-FormatData -LiteralPath $HOME\Format\CultureInfo.Format.ps1xml ``` Open the `CultureInfo.Format.ps1xml` file in any XML or text editor, such as @@ -278,8 +280,8 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` tag -contains one `` tag. +`` tag contains one or more `` tags. A `` +tag contains one `` tag. A `` tag must include either a `` tag or a `` tag. A `` tag specifies the property to display @@ -349,8 +351,9 @@ specific PowerShell version. ```powershell Get-FormatData -PowerShellVersion 5.1 -TypeName System.IO.DirectoryInfo | - Export-FormatData -Path ./MyGciView.Format.ps1xml -Update-FormatData -AppendPath ./MyGciView.Format.ps1xml + Export-FormatData -Path $HOME\Format\MyGciView.Format.ps1xml + +Update-FormatData -AppendPath $HOME\Format\MyGciView.Format.ps1xml ``` ```xml diff --git a/reference/docs-conceptual/developer/format/how-to-create-a-formatting-file-format-ps1xml.md b/reference/docs-conceptual/developer/format/how-to-create-a-formatting-file-format-ps1xml.md index a41ec614682a..4348a6f1d239 100644 --- a/reference/docs-conceptual/developer/format/how-to-create-a-formatting-file-format-ps1xml.md +++ b/reference/docs-conceptual/developer/format/how-to-create-a-formatting-file-format-ps1xml.md @@ -1,25 +1,25 @@ --- -description: How to Create a Formatting File (.format.ps1xml) -ms.date: 08/23/2021 -title: How to Create a Formatting File (.format.ps1xml) +description: How to Create a Formatting File (Format.ps1xml) +ms.date: 12/26/2025 +title: How to Create a Formatting File (Format.ps1xml) --- -# How to Create a Formatting File (.format.ps1xml) +# How to Create a Formatting File (Format.ps1xml) -This topic describes how to create a formatting file (.format.ps1xml). +This topic describes how to create a formatting file (`Format.ps1xml`). > [!NOTE] > You can also create a formatting file by making a copy of one of the files provided by Windows -> PowerShell. If you make a copy of an existing file, delete the existing digital signature, and add -> your own signature to the new file. +> PowerShell. To protect the users of your `Format.ps1xml` file, sign the file using a digital +> signature. For more information, see [about_Signing][01]. -## Create a .format.ps1xml file. +## Create a Format.ps1xml file -1. Create a text file (.txt) using a text editor such as Notepad. +1. Open a new text file using a text editor such as Visual Studio Code. 1. Copy the following lines into the formatting file. ```xml - + @@ -32,14 +32,20 @@ This topic describes how to create a formatting file (.format.ps1xml). - The `` tags define the `ViewDefinitions` node. All views are defined within this node. -1. Save the file to the Windows PowerShell installation folder, to your module folder, or to a +1. Save the file to a folder of your choice. If you are writing a module, save the file to a subfolder of the module folder. Use the following name format when you save the file: - `MyFile.format.ps1xml`. Formatting files must use the `.format.ps1xml` extension. + `MyFile.Format.ps1xml`. Formatting files must use the `.ps1xml` extension. You are now ready to add views to the formatting file. There is no limit to the number of views that can be defined in a formatting file. You can add a single view for each object, multiple views for the same object, or a single view that is used by multiple objects. -## See Also +## See also -[Writing a Windows PowerShell Formatting and Types File](./writing-a-powershell-formatting-file.md) +- [Formatting File Overview][02] +- [Formatting File Concepts][03] + + +[01]: /powershell/module/microsoft.powershell.core/about/about_signing +[02]: ./formatting-file-overview.md +[03]: ./formatting-file-concepts.md