about_Type_Operators

Short description

Describes the operators that work with Microsoft .NET types.

Long description

The Boolean type operators (-is and -isnot) tell whether an object is an instance of a specified .NET type. The -is operator returns a value of TRUE if the type matches and a value of FALSE otherwise. The -isnot operator returns a value of FALSE if the type matches and a value of TRUE otherwise.

The -as operator tries to convert the input object to the specified .NET type. If it succeeds, it returns the converted object. If it fails, it returns $null. It does not return an error.

PowerShell has the following type operators:

  • -is |Returns TRUE when the input is an instance of the specified .NET type.

    (get-date) -is [DateTime]     # Result is True
    
  • -isnot|Returns TRUE when the input not an instance of the specified.NET type.

    (get-date) -isnot [DateTime]  # Result is False
    
  • -as |Converts the input to the specified .NET type.

    "5/7/07" -as [DateTime]       # Result is Monday, May 7, 2007 12:00:00 AM
    

The syntax of the type operators is as follows:

<input> <operator> [.NET type]

You can also use the following syntax:

<input> <operator> ".NET type"

The .NET type can be written as a type name in brackets or a string, such as [DateTime] or "DateTime" for System.DateTime. If the type is not at the root of the system namespace, specify the full name of the object type. You can omit "System.". For example, to specify System.Diagnostics.Process, enter [System.Diagnostics.Process], [Diagnostics.Process], or "Diagnostics.Process".

The type operators always operate on the input object as a whole. That is, if the input object is a collection, it is the collection type that is tested, not the types of the collection's elements.

-is/isnot operators

The Boolean type operators (-is and -isnot) always return a Boolean value, even if the input is a collection of objects.

If <input> is a type that is the same as or is derived from the .NET Type, the -is operator returns $True.

For example, the DirectoryInfo type is derived from the FileSystemInfo type. Therefore, both of these examples return True.

PS> (Get-Item /) -is [System.IO.DirectoryInfo]
True
PS> (Get-Item /) -is [System.IO.FileSystemInfo]
True

The -is operator can also match interfaces if the <input> implements the interface in the comparison. In this example, the input is an array. Arrays implement the System.Collections.IList interface.

PS> 1, 2 -is [System.Collections.IList]
True

-as operator

The -as operator tries to convert the input object to the specified .NET type. If it succeeds, it returns the converted object. It if fails, it returns $null. It does not return an error.

If the <input> is a type that is derived from the .NET Type -as passes through returns input object unchanged. For example, the DirectoryInfo type is derived from the FileSystemInfo type. Therefore, the object type is unchanged in the following example:

PS> $fsroot = (Get-Item /) -as [System.IO.FileSystemInfo]
PS> $fsroot.GetType().FullName
System.IO.DirectoryInfo

Converting the DateTime type is culture-sensitive

Unlike type casting, converting to [DateTime] type using the -as operator only works with strings that are formatted according to the rules of the current culture.

PS> [cultureinfo]::CurrentCulture = 'fr-FR'
PS> '13/5/20' -as [datetime]

mercredi 13 mai 2020 00:00:00

PS> '05/13/20' -as [datetime]
PS> [datetime]'05/13/20'

mercredi 13 mai 2020 00:00:00

PS> [datetime]'13/05/20'
InvalidArgument: Cannot convert value "13/05/20" to type "System.DateTime".
Error: "String '13/05/20' was not recognized as a valid DateTime."

To find the .NET type of an object, use the Get-Member cmdlet. Or, use the GetType method of all the objects together with the FullName property of this method. For example, the following statement gets the type of the return value of a Get-Culture command:

PS> (Get-Culture).GetType().FullName
System.Globalization.CultureInfo

Examples

The following examples show some uses of the Type operators:

PS> 32 -is [Float]
False

PS> 32 -is "int"
True

PS> (get-date) -is [DateTime]
True

PS> "12/31/2007" -is [DateTime]
False

PS> "12/31/2007" -is [String]
True

PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process]
True

PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo]
True

The following example shows that when the input is a collection of objects, the matching type is the .NET type of the collection, not the type of the individual objects in the collection.

In this example, although both the Get-Culture and Get-UICulture cmdlets return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array.

PS> (get-culture) -is [System.Globalization.CultureInfo]
True

PS> (get-uiculture) -is [System.Globalization.CultureInfo]
True

PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo]
False

PS> (get-culture), (get-uiculture) -is [Array]
True

PS> (get-culture), (get-uiculture) | foreach {
  $_ -is [System.Globalization.CultureInfo])
}
True
True

PS> (get-culture), (get-uiculture) -is [Object]
True

The following examples show how to use the -as operator.

PS> "12/31/07" -is [DateTime]
False

PS> "12/31/07" -as [DateTime]
Monday, December 31, 2007 12:00:00 AM

PS> $date = "12/31/07" -as [DateTime]

C:\PS>$a -is [DateTime]
True

PS> 1031 -as [System.Globalization.CultureInfo]

LCID      Name      DisplayName
----      ----      -----------
1031      de-DE     German (Germany)

The following example shows that when the -as operator cannot convert the input object to the .NET type, it returns $null.

PS> 1031 -as [System.Diagnostics.Process]
PS>

See also