PowerShell多文件代理函数模块创建及ScriptMethod替代方案咨询

针对你团队当前用ScriptMethod实现代理函数遇到的痛点——丢失管道支持、无法添加标准帮助文档、代码难以拆分到多文件，我整理了两种最优替代方案，分别适配不同的团队技术习惯：

核心痛点复盘 #

先明确当前方案的三个核心问题：

• 管道功能缺失：ScriptMethod的参数无法直接接收管道输入，不符合PowerShell的惯用交互方式
• 帮助文档空白：没法用PowerShell标准的<# .SYNOPSIS #>注释块为代理函数添加帮助，新人上手困难
• 代码维护困难：所有代理逻辑挤在一个New-StorageArray函数里，随着代理数量增加，代码会变得臃肿不堪，且PowerShell不支持分部类，无法拆分

方案一：PowerShell类+封装函数（推荐面向对象风格） #

PowerShell 5.1及以上版本支持类，我们可以用类来封装阵列的核心属性和通用逻辑，再把每个代理方法拆分到单独的类扩展文件中，最后为每个代理方法封装一个支持管道的外部函数，完美解决所有痛点。

1. 模块结构设计 #

StorageArrayModule/
├── StorageArray.psd1       # 模块清单文件
├── StorageArray.psm1       # 模块入口文件
├── Classes/
│   ├── StorageArray.Base.ps1       # 基础类（属性+通用方法）
│   ├── StorageArray.Cmdlet1.ps1    # Cmdlet1代理方法
│   ├── StorageArray.Cmdlet2.ps1    # Cmdlet2代理方法
│   └── StorageArray.Cmdlet3.ps1    # Cmdlet3代理方法

2. 基础类定义（StorageArray.Base.ps1） #

先定义核心属性和通用的连接/断开逻辑：

class StorageArray {
    # 核心属性（封装为类成员，外部无法随意修改）
    [string]$ArrayName
    [PSCredential]$ArrayCredential
    [version]$ArrayVersion

    # 通用连接方法
    [void]Connect() {
        Connect-StorageArray -ArrayName $this.ArrayName -Credential $this.ArrayCredential
    }

    # 通用断开方法
    [void]Disconnect() {
        Disconnect-StorageArray
    }

    # 构造函数（用于实例化对象）
    StorageArray([string]$Name, [PSCredential]$Credential, [version]$Version) {
        $this.ArrayName = $Name
        $this.ArrayCredential = $Credential
        $this.ArrayVersion = $Version
    }
}

3. 拆分代理方法到单独文件（StorageArray.Cmdlet1.ps1） #

每个代理方法对应一个文件，同时封装一个支持管道的外部函数：

# 扩展StorageArray类，添加Cmdlet1的代理逻辑
class StorageArray {
    [PSCustomObject]InvokeCmdlet1([string]$Property1, [string]$Property2) {
        $status = $true
        $result = $null
        try {
            $this.Connect()
            $result = Cmdlet1 -Property1 $Property1 -Property2 $Property2
        }
        catch {
            $status = $false
            Write-Error "执行Cmdlet1失败: $_"
        }
        finally {
            $this.Disconnect()
        }
        return [PSCustomObject]@{
            Status = $status
            Result = $result
        }
    }
}

# 封装支持管道和帮助文档的外部函数
function Invoke-StorageArrayCmdlet1 {
    <#
    .SYNOPSIS
    调用存储阵列的Cmdlet1操作
    .DESCRIPTION
    自动处理存储阵列的连接与断开，执行Cmdlet1并返回结果状态
    .PARAMETER StorageArray
    要操作的StorageArray对象（支持管道输入）
    .PARAMETER Property1
    Cmdlet1的必填参数1
    .PARAMETER Property2
    Cmdlet1的可选参数2
    .EXAMPLE
    $arrayVersion5 | Invoke-StorageArrayCmdlet1 -Property1 "Disk01" -Property2 "ReadWrite"
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [StorageArray]$StorageArray,
        [Parameter(Mandatory)]
        [string]$Property1,
        [string]$Property2
    )
    process {
        $StorageArray.InvokeCmdlet1($Property1, $Property2)
    }
}

4. 模块入口文件（StorageArray.psm1） #

导入所有类和函数，并导出供外部使用：

# 导入所有类文件
Get-ChildItem (Join-Path $PSScriptRoot "Classes") -Filter *.ps1 | ForEach-Object {
    . $_.FullName
}

# 导出工厂函数和代理函数
Export-ModuleMember -Function New-StorageArray, Invoke-StorageArrayCmdlet1, Invoke-StorageArrayCmdlet2, Invoke-StorageArrayCmdlet3

# 工厂函数：创建StorageArray实例
function New-StorageArray {
    <#
    .SYNOPSIS
    创建存储阵列对象
    .DESCRIPTION
    实例化指定版本的存储阵列，包含所有代理方法
    .PARAMETER Name
    存储阵列的名称或IP地址
    .PARAMETER Credential
    访问存储阵列的认证凭据
    .PARAMETER Version
    存储阵列的版本号
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Name,
        [Parameter(Mandatory)]
        [PSCredential]$Credential,
        [Parameter(Mandatory)]
        [version]$Version
    )
    return [StorageArray]::new($Name, $Credential, $Version)
}

使用方式 #

# 导入模块
Import-Module .\StorageArrayModule

# 创建阵列对象
$arrayVersion5 = New-StorageArray -Name "192.168.1.100" -Credential (Get-Credential) -Version "5.0"

# 管道调用代理函数
$arrayVersion5 | Invoke-StorageArrayCmdlet1 -Property1 "Disk01" -Property2 "ReadWrite"

# 直接调用类方法（适合不需要管道的场景）
$arrayVersion5.InvokeCmdlet1("Disk01", "ReadWrite")

方案二：独立函数+会话变量（适合传统PowerShell风格） #

如果团队更习惯用纯函数开发，不想接触类，可以用会话变量来管理阵列的连接信息，每个代理函数单独放在一个文件里，天然支持管道和帮助文档。

1. 模块结构设计 #

StorageArrayModule/
├── StorageArray.psd1       # 模块清单文件
├── StorageArray.psm1       # 模块入口文件
├── Functions/
│   ├── New-StorageArray.ps1       # 注册阵列信息
│   ├── Invoke-Cmdlet1Proxy.ps1    # Cmdlet1代理函数
│   ├── Invoke-Cmdlet2Proxy.ps1    # Cmdlet2代理函数
│   └── Invoke-Cmdlet3Proxy.ps1    # Cmdlet3代理函数

2. 注册阵列信息（New-StorageArray.ps1） #

用会话变量$Script:StorageArrays存储所有阵列的连接信息：

function New-StorageArray {
    <#
    .SYNOPSIS
    注册存储阵列的连接信息
    .DESCRIPTION
    将存储阵列的名称、凭据和版本保存到会话变量，供后续代理函数使用
    .PARAMETER Name
    存储阵列的唯一标识（名称或IP）
    .PARAMETER Credential
    访问存储阵列的认证凭据
    .PARAMETER Version
    存储阵列的版本号
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Name,
        [Parameter(Mandatory)]
        [PSCredential]$Credential,
        [Parameter(Mandatory)]
        [version]$Version
    )
    # 初始化会话变量
    if (-not $Script:StorageArrays) {
        $Script:StorageArrays = @{}
    }
    # 存储阵列信息
    $Script:StorageArrays[$Name] = [PSCustomObject]@{
        Name = $Name
        Credential = $Credential
        Version = $Version
    }
    return $Script:StorageArrays[$Name]
}

3. 独立代理函数（Invoke-Cmdlet1Proxy.ps1） #

每个代理函数单独实现，支持管道输入阵列名称：

function Invoke-Cmdlet1Proxy {
    <#
    .SYNOPSIS
    调用存储阵列的Cmdlet1操作
    .DESCRIPTION
    自动连接指定存储阵列，执行Cmdlet1后断开，返回结果状态
    .PARAMETER ArrayName
    存储阵列的唯一标识（支持管道输入）
    .PARAMETER Property1
    Cmdlet1的必填参数1
    .PARAMETER Property2
    Cmdlet1的可选参数2
    .EXAMPLE
    "192.168.1.100" | Invoke-Cmdlet1Proxy -Property1 "Disk01" -Property2 "ReadWrite"
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [string]$ArrayName,
        [Parameter(Mandatory)]
        [string]$Property1,
        [string]$Property2
    )
    process {
        # 验证阵列是否已注册
        $array = $Script:StorageArrays[$ArrayName]
        if (-not $array) {
            Write-Error "未找到存储阵列: $ArrayName，请先运行New-StorageArray注册"
            return
        }
        # 执行代理逻辑
        $status = $true
        $result = $null
        try {
            Connect-StorageArray -ArrayName $array.Name -Credential $array.Credential
            $result = Cmdlet1 -Property1 $Property1 -Property2 $Property2
        }
        catch {
            $status = $false
            Write-Error "执行Cmdlet1失败: $_"
        }
        finally {
            Disconnect-StorageArray
        }
        return [PSCustomObject]@{
            Status = $status
            Result = $result
        }
    }
}

4. 模块入口文件（StorageArray.psm1） #

导入所有函数并导出：

# 导入所有函数文件
Get-ChildItem (Join-Path $PSScriptRoot "Functions") -Filter *.ps1 | ForEach-Object {
    . $_.FullName
}

# 导出所有函数
Export-ModuleMember -Function New-StorageArray, Invoke-Cmdlet1Proxy, Invoke-Cmdlet2Proxy, Invoke-Cmdlet3Proxy

使用方式 #

# 导入模块
Import-Module .\StorageArrayModule

# 注册阵列
New-StorageArray -Name "192.168.1.100" -Credential (Get-Credential) -Version "5.0"

# 管道调用代理函数
"192.168.1.100" | Invoke-Cmdlet1Proxy -Property1 "Disk01" -Property2 "ReadWrite"

方案对比与选择 #

如果团队熟悉面向对象思想，类方案是更好的选择，因为它的封装性更强，逻辑更清晰；如果团队更习惯传统PowerShell函数开发，独立函数方案更易上手，维护成本更低。

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