| external help file | Module Name | online version | schema |
|---|---|---|---|
PSScriptTools-help.xml |
PSScriptTools |
2.0.0 |
Create or modify a format.ps1xml file
New-PSFormatXML [-InputObject] <Object> [[-Properties] <String[]>] [-Typename <String>]
[[-FormatType] <String>] [[-ViewName] <String>] [-Path] <String> [-Append] [-Passthru] [-WhatIf] [-Confirm]
[<CommonParameters>]When defining custom objects with a new typename, PowerShell by default will display all properties. However, you may wish to have a specific default view, be it a table or list. Or you may want to have different views display the object differently. Format directives are stored in format.ps1xml files which can be tedious to create. This command simplifies that process.
Pipe an instance of your custom object to this function and it will generate a format.ps1xml file based on either all the properties or a subset that you provide. You can repeat the process to add additional views. When finished, edit the format.ps1xml file and fine tune it. The file will have notes on how to substitute script blocks.
Note that table views are set to Autosize. But the table definition will include best guesses for column widths. If you prefer a more granular approach you can delete the Autosize tag and experiment with varying widths. Don't forget to run Update-FormatData to load your new file. You may need to start a new PowerShell session to test changes.
PS C:\> $tname = "myThing"
PS C:\> $obj = [PSCustomObject]@{
PSTypeName = $tname
Name = "Jeff"
Date = (Get-Date)
Computername = $env:computername
OS = (get-ciminstance win32_operatingsystem -Property Caption).caption
}
PS C:\> Update-TypeData -TypeName $tname -MemberType "ScriptProperty" -MemberName "Runtime" -value {(Get-Date) - [datetime]"1/1/2019"} -force
PS C:\> $obj
Name : Jeff
Date : 2/10/2019 8:49:10 PM
Computername : BOVINE320
OS : Microsoft Windows 10 Pro
Runtime : 40.20:49:43.9205882This example begins be creating a custom object. You might normally do this in a script or module.
PS C:\> $obj | New-PSFormatXML -Properties Name, Date, Computername, OS -FormatType Table -path "C:\work\$tname.format.ps1xml"
PS C:\> $obj | New-PSFormatXML -Properties Name, OS, Runtime -FormatType Table -view runtime -path "C:\work\$tname.format.ps1xml" -append
PS C:\> $obj | New-PSFormatXML -FormatType List -path "C:\work\$tname.format.ps1xml" -appendThe object is then piped to this command to generate a new format.ps1xml. Subsequent commands add more formatted views. When the file is completed it can be modified.
PS C:\> Update-FormatData -appendpath "C:\work\$tname.format.ps1xml"
PS C:\> $obj
Name Date Computername Operating System
---- ---- ------------ ----------------
Jeff 2/10/2019 8:49:10 PM BOVINE320 Microsoft Windows 10 Pro
PS C:\> $obj | format-table -View runtime
Name OS Runtime
---- -- -------
Jeff 40.20:56:24.5411481
PS C:\> $obj | format-list
Name : Jeff
Date : Sunday, February 10, 2019
Computername : BOVINE320
OperatingSystem : Microsoft Windows 10 Pro
Runtime : 40.21:12:01After the format.ps1xml file is applied, the object can be formatted as designed.
Append the new view to an existing format.ps1xml file.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalsePrompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseSpecify whether to create a table or list view
Type: String
Parameter Sets: (All)
Aliases:
Accepted values: Table, List
Required: False
Position: 2
Default value: Table
Accept pipeline input: False
Accept wildcard characters: FalseSpecify an object to analyze and generate or update a ps1xml file. All you need is one instance of the object.
Type: Object
Parameter Sets: (All)
Aliases:
Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: FalseWrite the ps1xml file object to the pipeline.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseEnter full filename and path for the format.ps1xml file.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseEnter a set of properties to include. If you don't specify anything then all properties will be used.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseEnter the name of your view.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 3
Default value: default
Accept pipeline input: False
Accept wildcard characters: FalseShows what would happen if the cmdlet runs. The cmdlet is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseSpecify the object typename. If you don't, then the command will use the detected object type from the Inputobject.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/