PowerShell中op_Explicit单属性PSCustomObject转换异常排查

问题原因 #

PowerShell对仅含单个属性的PSCustomObject存在特殊的自动展开行为：在类型转换过程中，会直接将对象替换为其唯一属性的值，而非保留PSCustomObject实例。这就导致自定义的op_Explicit([PSCustomObject])方法无法接收到预期的参数，转而尝试将属性值的原始类型（比如字符串、数字）转换为自定义类，最终抛出类型转换错误。

而当PSCustomObject包含多个属性时，PowerShell不会执行自动展开，自定义转换方法能正常接收PSCustomObject实例，因此转换正常。

解决方法 #

针对这个问题，有两种直接的解决思路：

思路1：重载转换方法，适配展开后的类型 #

为自定义类添加针对单属性展开后可能出现的类型的op_Explicit重载方法，覆盖单属性场景的转换逻辑。

示例代码：

class MyCustomClass {
    [string] $Name
    [int] $Age

    # 处理多属性PSCustomObject的转换
    static [MyCustomClass] op_Explicit([PSCustomObject]$obj) {
        $instance = [MyCustomClass]::new()
        $instance.Name = $obj.Name ?? ""
        $instance.Age = $obj.Age ?? 0
        return $instance
    }

    # 处理单属性展开后的字符串类型（对应Name属性的场景）
    static [MyCustomClass] op_Explicit([string]$name) {
        $instance = [MyCustomClass]::new()
        $instance.Name = $name
        $instance.Age = 0
        return $instance
    }

    # 如果有其他单属性场景（比如仅Age），可以继续添加对应类型的重载
    static [MyCustomClass] op_Explicit([int]$age) {
        $instance = [MyCustomClass]::new()
        $instance.Name = ""
        $instance.Age = $age
        return $instance
    }
}

# 单属性测试：正常转换
$singleNameObj = [PSCustomObject]@{ Name = "Alice" }
[MyCustomClass]$singleNameObj

$singleAgeObj = [PSCustomObject]@{ Age = 25 }
[MyCustomClass]$singleAgeObj

# 多属性测试：正常转换
$multiPropObj = [PSCustomObject]@{ Name = "Bob"; Age = 30 }
[MyCustomClass]$multiPropObj

思路2：阻止PowerShell自动展开，保留PSCustomObject实例 #

通过修改转换方法的参数类型，或者在转换时强制包裹对象，避免PowerShell的自动展开行为。

方式A：修改转换方法参数为[psobject]

将op_Explicit的参数类型从[PSCustomObject]改为[psobject]，PowerShell不会对psobject类型的参数执行自动展开，确保方法能接收到原始的PSCustomObject实例。

示例代码：

class MyCustomClass {
    [string] $Name
    [int] $Age

    static [MyCustomClass] op_Explicit([psobject]$obj) {
        $instance = [MyCustomClass]::new()
        # 通过PSObject.Properties获取属性值，兼容有无该属性的情况
        $instance.Name = $obj.PSObject.Properties['Name'].Value ?? ""
        $instance.Age = $obj.PSObject.Properties['Age'].Value ?? 0
        return $instance
    }
}

# 单属性测试：正常转换
$singlePropObj = [PSCustomObject]@{ Name = "Alice" }
[MyCustomClass]$singlePropObj

# 多属性测试：正常转换
$multiPropObj = [PSCustomObject]@{ Name = "Bob"; Age = 30 }
[MyCustomClass]$multiPropObj

方式B：转换前强制包裹为[psobject]

如果不想修改自定义类的代码，可以在转换时手动将单属性对象转为[psobject]，阻止自动展开：

# 假设使用最初的自定义类（仅支持[PSCustomObject]参数）
class MyCustomClass {
    [string] $Name
    [int] $Age

    static [MyCustomClass] op_Explicit([PSCustomObject]$obj) {
        $instance = [MyCustomClass]::new()
        $instance.Name = $obj.Name ?? ""
        $instance.Age = $obj.Age ?? 0
        return $instance
    }
}

# 单属性测试：通过[psobject]包裹阻止展开
$singlePropObj = [PSCustomObject]@{ Name = "Alice" }
[MyCustomClass][psobject]$singlePropObj

内容的提问来源于stack exchange，提问作者Martin Z