Skip to content

Latest commit

 

History

History
226 lines (170 loc) · 9.41 KB

ConvertTo-Expression.md

File metadata and controls

226 lines (170 loc) · 9.41 KB
Raw

ConvertTo-Expression

Serializes an object to a PowerShell expression.

Syntax

ConvertTo-Expression
    -InputObject <Object>
    [-LanguageMode <PSLanguageMode> = 'Restricted']
    [-ExpandDepth <Int32> = [Int]::MaxValue]
    [-Explicit]
    [-FullTypeName]
    [-HighFidelity]
    [-ExpandSingleton]
    [-Indent <String> = '    ']
    [-MaxDepth <Int32> = [PSNode]::DefaultMaxDepth]
    [<CommonParameters>]

Description

The ConvertTo-Expression cmdlet converts (serializes) an object to a PowerShell expression. The object can be stored in a variable, (.psd1) file or any other common storage for later use or to be ported to another system.

expressions might be restored to an object using the native Invoke-Expression cmdlet:

$Object = Invoke-Expression ($Object | ConvertTo-Expression)

Warning

Take reasonable precautions when using the Invoke-Expression cmdlet in scripts. When using Invoke-Expression to run a command that the user enters, verify that the command is safe to run before running it. In general, it is best to restore your objects using ConvertFrom-Expression.

Note

Some object types can not be reconstructed from a simple serialized expression.

Parameters

-InputObject <Object>

Specifies the objects to convert to a PowerShell expression. Enter a variable that contains the objects, or type a command or expression that gets the objects. You can also pipe one or more objects to ConvertTo-Expression.

Type:Object
Mandatory:True
Position:Named
Default value:
Accept pipeline input:False
Accept wildcard characters:False

-LanguageMode <PSLanguageMode>

Defines which object types are allowed for the serialization, see: About language modes If a specific type isn't allowed in the given language mode, it will be substituted by:

  • $Null in case of a null value
  • $False in case of a boolean false
  • $True in case of a boolean true
  • A number in case of a primitive value
  • A string in case of a string or any other leaf node
  • @(...) for an array (list node)
  • @{...} for any dictionary, PSCustomObject or Component (aka map node)

See the PSNode Object Parser for a detailed definition on node types.

Type:PSLanguageMode
Mandatory:False
Position:Named
Default value:'Restricted'
Accept pipeline input:False
Accept wildcard characters:False

-ExpandDepth <Int32>

Defines up till what level the collections will be expanded in the output.

  • A -ExpandDepth 0 will create a single line expression.
  • A -ExpandDepth -1 will compress the single line by removing command spaces.

Note

White spaces (as newline characters and spaces) will not be removed from the content of a (here) string.

Type:Int32
Mandatory:False
Position:Named
Default value:[Int]::MaxValue
Accept pipeline input:False
Accept wildcard characters:False

-Explicit

By default, restricted language types initializers are suppressed. When the Explicit switch is set, all values will be prefixed with an initializer (as e.g. [Long] and [Array])

Note

The -Explicit switch can not be used in restricted language mode

Type:SwitchParameter
Mandatory:False
Position:Named
Default value:
Accept pipeline input:False
Accept wildcard characters:False

-FullTypeName

In case a value is prefixed with an initializer, the full type name of the initializer is used.

Note

The -FullTypename switch can not be used in restricted language mode and will only be meaningful if the initializer is used (see also the -Explicit switch).

Type:SwitchParameter
Mandatory:False
Position:Named
Default value:
Accept pipeline input:False
Accept wildcard characters:False

-HighFidelity

If the -HighFidelity switch is supplied, all nested object properties will be serialized.

By default the fidelity of an object expression will end if:

  1. the (embedded) object is a leaf node (see: PSNode Object Parser)
  2. the (embedded) object expression is able to round trip.

An object is able to roundtrip if the resulted expression of the object itself or one of its properties (prefixed with the type initializer) can be used to rebuild the object.

The advantage of the default fidelity is that the resulted expression round trips (aka the object might be rebuild from the expression), the disadvantage is that information hold by less significant properties is lost (as e.g. timezone information in a DateTime] object).

The advantage of the high fidelity switch is that all the information of the underlying properties is shown, yet any constrained or full object type will likely fail to rebuild due to constructor limitations such as readonly property.

Note

Objects properties of type [Reflection.MemberInfo] are always excluded.

Type:SwitchParameter
Mandatory:False
Position:Named
Default value:
Accept pipeline input:False
Accept wildcard characters:False

-ExpandSingleton

(List or map) collections nodes that contain a single item will not be expanded unless this -ExpandSingleton is supplied.

Type:SwitchParameter
Mandatory:False
Position:Named
Default value:
Accept pipeline input:False
Accept wildcard characters:False

-Indent <String>

Type:String
Mandatory:False
Position:Named
Default value:' '
Accept pipeline input:False
Accept wildcard characters:False

-MaxDepth <Int32>

Specifies how many levels of contained objects are included in the PowerShell representation. The default value is define by the PowerShell object node parser ([PSNode]::DefaultMaxDepth).

Type:Int32
Mandatory:False
Position:Named
Default value:[PSNode]::DefaultMaxDepth
Accept pipeline input:False
Accept wildcard characters:False

Inputs

Any. Each objects provided through the pipeline will converted to an expression. To concatenate all piped objects in a single expression, use the unary comma operator, e.g.: ,$Object | ConvertTo-Expression

Outputs

String[]. ConvertTo-Expression returns a PowerShell String expression for each input object.

Related Links