PowerShell 函数参数：初学者指南

任何编程或脚本语言的基石都是函数的概念——执行特定任务的可重用代码块。在 PowerShell 中，函数的有效性通过参数的使用而放大。这些进入函数的小网关使我们能够以灵活、动态的方式控制其操作。函数参数允许您将值传递给函数，使其更加通用和可定制。在本文中，我们将介绍函数参数的基本语法，讨论通过 PowerShell 提供的不同类型，并探索展示它们强大功能的实际示例。

PowerShell 函数参数概述

从较高层次来看，函数参数只是 PowerShell 脚本正确执行所需的输入。这些输入可以以命名参数（例如-Parameter“Value”）的形式或通过管道传递给脚本。它们是函数输入的主要模式，允许我们传递信息并影响函数的行为。将函数想象为执行任务的黑匣子。参数就像这个盒子上的拨盘和开关一样，您可以根据需要进行调整。

从本质上讲，参数使您的函数具有多功能性和可重用性，使您能够生成更高效、可维护和可扩展的脚本。让我们深入了解 PowerShell 函数中参数的创建和使用。

创建带参数的 PowerShell 函数

在 PowerShell 中，函数参数在函数本身的 param 块中定义。该块可以包含各种参数，每个参数都有自己的属性，例如数据类型、默认值、验证逻辑等。您可以定义一个或多个参数，每个参数都有名称、数据类型、验证逻辑和可选的默认值。在 PowerShell 函数中创建参数非常简单。它只是以 param 关键字开头：

让我们考虑另一个例子：

#Create a function with parameter
function Greet-User {
    param (
        [string]$Name
    )

    Write-host "Hello, $Name!"
}

#Call the function with parameter
Greet-User "Alice"

在此函数中，我们声明了 [string] 类型的参数 $Name。调用此函数时，我们可以提供一个名称，如下所示：Greet-User -Name "Alice"。该函数将输出 Hello, Alice!。请注意，参数变量的范围在函数内。

在 PowerShell 中创建具有多个参数的函数

有时，您可能需要创建接受多个参数的函数。 PowerShell 允许您定义具有多个参数的函数，只需在 param 块中指定它们即可。让我们看一个例子。这是一个简单的函数，它接受两个整数参数并返回它们的总和：

Function Add-Numbers {
Param (
    [int]$num1,
    [int]$num2
)
   $sum = $num1 + $num2
   return $sum
}

在此示例中，我们定义了两个参数：$num1 和 $num2。这两个参数的数据类型都是 [int]，这意味着它们应该是整数。您可以以相同的方式添加其他参数，用逗号分隔它们。

PowerShell 还有一个自动变量 $args，其中包含传递给函数、脚本或脚本块的参数值数组。

传递函数参数

如何在 PowerShell 中调用带参数的函数？要使用带参数的函数，您需要在调用函数时向该函数传递值。您可以通过指定参数名称及其值（以逗号分隔）来完成此操作。例如，要使用我们上面定义的 Add-Numbers 函数，您可以这样调用它：

Add-Numbers -num1 5 -num2 3

这将分别将值 5 和 3 传递给 $num1 和 $num2 参数。如果您没有为 $num2 指定值，它将使用默认值 0。

带有参数的 PowerShell 函数模板

您可以使用“代码片段”从模板和参数快速创建 PowerShell 函数。在PowerShell ISE中，您可以从模板快速创建函数。打开PowerShell ISE，在“编辑”菜单中，单击“启动片段”菜单项。这可以作为创建具有参数属性的高级函数的快速入门。

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
#>
function Verb-Noun
{
    [CmdletBinding()]
    [Alias()]
    [OutputType([int])]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true,
                   ValueFromPipelineByPropertyName=$true,
                   Position=0)]
        $Param1,

        # Param2 help description
        [int]
        $Param2
    )

    Begin
    {
    }
    Process
    {
    }
    End
    {
    }
}

参数类型

PowerShell 支持多种参数类型。除了 [string]、[int] 和 [bool] 等基本类型之外，您还可以使用 [ 等更复杂的类型array]、[hashtable]，甚至是您的自定义对象。以下是您可以在 PowerShell 中使用的不同参数类型的摘要：

1. [string]：表示字符序列或文本字符串。
2. [int]：这代表整数（整数）。
3. [double]：这表示可以有小数点的数字（浮点数）。
4. [bool]：这表示布尔值，可以是 $true 或 $false。
5. [array]：这用于项目数组，可以是任何类型。
6. [string[]]：这表示字符串数组。
7. [hashtable]：这代表哈希表（在某些其他语言中也称为字典），它是键值对的集合。
8. [pscustomobject]：这用于自定义对象类型。
9. [DateTime]：这表示日期和时间值。

此外，如果您没有为 PowerShell 参数指定类型，它将被视为泛型类型 [object]，并且 PowerShell 会尝试根据如何将值转换为适当的类型。它在函数中使用。

让我们看一个例子：

function MyFunction {
    param(
        [string]$Name,
        [int]$Age,
        [bool]$IsEnabled
    )
    # Function body
}

在此示例中，函数 MyFunction 接受三个参数：$Name、$Age 和 $IsEnabled。您可以在调用函数时将值传递给这些参数，从而允许您根据特定要求自定义其行为。

函数参数中的参数设置

在 PowerShell 中，参数集是针对单个场景一起运行的一组参数，并且一个函数可以具有多个参数集来处理不同的场景。 ParameterSetName 属性用于指定特定参数属于哪个参数集。这允许您拥有仅适用于函数的某些用例的参数。

一个函数可以有多个参数集，但每次调用该函数时只能使用一个参数集。让我们考虑一个具有两种不同方式检索用户信息的函数——通过用户名或用户 ID。

这是具有两个参数集的函数的示例：

function Get-UserInfo {
    [CmdletBinding(DefaultParameterSetName='ByName')]
    param (
        [Parameter(Mandatory=$true, ParameterSetName='ByName')]
        [string]$Name,
        
        [Parameter(Mandatory=$true, ParameterSetName='ByID')]
        [int]$ID
    )

    switch ($PSCmdlet.ParameterSetName) {
        'ByName' { Write-Output "Fetching user information by Name: $Name" }
        'ByID' { Write-Output "Fetching user information by ID: $ID" }
    }
}

该函数有两个参数集——“ByName”和“ByID”。当使用 -Name 参数调用时，它按名称获取用户信息；当使用 -ID 调用时，它按用户 ID 获取用户信息。要使用此功能，您需要执行以下操作：

Get-UserInfo -Name "Alice"
Get-UserInfo -ID 123

第一个调用将输出 Fetching user information by Name: Alice，第二个调用将输出 Fetching user information by ID: 123。

在 PowerShell 函数中利用开关参数

开关参数是 PowerShell 中一种特殊类型的参数，可用于基于布尔条件控制函数的行为。开关参数通常用于二元期权，其中如果启用开关，则函数执行特定操作，如果禁用开关，则函数执行不同的操作。让我们看看如何使用开关参数：

function Copy-Files {
    param (
        [Parameter(Mandatory=$true)]
        [string]$SourcePath,

        [Parameter(Mandatory=$true)]
        [string]$DestinationPath,

        [switch]$Overwrite
    )

    if (Test-Path $DestinationPath) {
        if ($Overwrite) {
            Write-Output "Overwriting existing files at $DestinationPath."
            Copy-Item -Path $SourcePath -Destination $DestinationPath -Recurse -Force
        } else {
            Write-Output "Destination path $DestinationPath already exists. Use -Overwrite to force."
        }
    } else {
        Write-Output "Copying files to $DestinationPath."
        Copy-Item -Path $SourcePath -Destination $DestinationPath -Recurse
    }
}

在此函数中，$SourcePath 和 $DestinationPath 是强制字符串参数（必需参数），用于指定复制操作的源目录和目标目录。 $Overwrite 是一个开关参数，指示是否覆盖目标处的现有文件。如果您使用 -Overwrite 开关调用此函数，它将覆盖目标处的任何现有文件：

Copy-Files -SourcePath "C:\source" -DestinationPath "C:\destination" -Overwrite

在 PowerShell 函数中使用命名参数

调用 PowerShell 函数时，您可以按名称传递参数，而不是依赖其位置顺序。这可以使您的代码更具可读性并且不易出错，尤其是在处理具有多个参数的函数时。让我们看看如何使用命名参数：

Function Get-FullName($FirstName, $MiddleName, $LastName)
{
    $fullName = ''
    if ($firstName) {
        $fullName += $firstName
    }
    if ($middleName) {
        $fullName += " $middleName"
    }
    if ($lastName) {
        $fullName += " $lastName"
    }
    return $fullName.trim()
}

Get-FullName -FirstName "John" -LastName "Doe"
Get-FullName -FirstName "Jane" -MiddleName "Marie" -LastName "Smith"

在此示例中，使用两个/三个命名参数调用函数 Get-FullName：-FirstName、-MiddleName 和 -姓氏。通过显式指定参数名称，您可以按任意顺序提供值，从而使您的代码更加灵活且易于理解。

强制和可选参数

默认情况下，参数是可选的。但是，PowerShell 允许我们使用 [Parameter(Mandatory=$true)] 属性指定强制参数，如果在函数调用期间未提供这些参数，则函数会提示输入这些参数。让我们看一个例子：

function Greet-User {
    param (
        [Parameter(Mandatory=$true)]
        [string]$Name
    )

    Write-Output "Hello, $Name!"
}

在此版本的 Greet-User 中，$Name 参数是必需的。如果我们尝试在不带 -Name 参数的情况下调用 Greet-User，PowerShell 会提示我们这样做。

位置参数

默认情况下，PowerShell 函数参数是命名的，但它们也可以是位置参数，这意味着可以根据它们在函数调用中的位置传递值。以下是使用位置参数计算矩形面积的函数示例：

function CalculateArea {
    param (
        [Parameter(Position=0)]
        [int]$length,

        [Parameter(Position=1)]
        [int]$width
    )
    return $length * $width
}

在本例中，$length 是第一个位置参数，$width 是第二个。您可以通过按正确顺序传递值来调用此函数，而无需指定参数名称：

$area = CalculateArea 5 10

验证输入参数

验证用户输入是创建健壮、可靠且无错误的 PowerShell 脚本的另一个重要方面。您可以为函数参数指定各种验证逻辑，从简单的数据类型检查到复杂的正则表达式和验证脚本。 PowerShell 提供了多种验证参数的方法，强制执行类型、范围、模式或非空或空等检查。

验证不为空或为空

这可确保参数值不为 null 或空字符串。

function Greet-User {
    param (
        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()]
        [string]$Name
    )

    Write-Output "Hello, $Name!"
}

在这里，我们向 $Name 参数添加了 ValidateNotNullOrEmpty 属性。现在，如果我们调用 Greet-User -Name "" 或 Greet-User -Name $null，PowerShell 将抛出错误。

验证集

这将参数值限制为一组特定的值。以下是如何使用 PowerShell 函数参数和验证集的示例：

Function Get-ProcessInfo {
    Param(
        [ValidateSet("notepad", "explorer")]
        [string]$ProcessName
    )

    Get-Process $ProcessName
}

在此示例中，Get-ProcessInfo 函数采用一个参数 $ProcessName，该参数使用 [ValidateSet()] 属性进行验证。这确保传递给参数的值是“notepad”或“explorer”。

验证范围

这确保了参数值落在特定的数值范围内。

function Grade-Exam {
    param (
        [Parameter(Mandatory=$true)]
        [ValidateRange(0, 100)]
        [double]$Score
    )

    switch ($Score) {
        { $_ -ge 90 } { return "A" }
        { $_ -ge 80 } { return "B" }
        { $_ -ge 70 } { return "C" }
        { $_ -ge 60 } { return "D" }
        default { return "F" }
    }
}
$grade = Grade-Exam -Score 85
#Will Error
$grade = Grade-Exam -Score 105

如果您尝试使用 0-100 范围之外的分数调用此函数，PowerShell 将抛出错误：

验证脚本

这允许您使用自定义脚本进行验证。

function IsPrime {
    param (
        [Parameter(Mandatory=$true)]
        [ValidateScript({
            $number = $_
            if ($number -eq 1) { return $false }
            2..([Math]::Sqrt($number)) | foreach { if ($number % $_ -eq 0) { return $false } }
            return $true
        })]
        [int]$Number
    )

    return "$Number is a prime number."
}

验证模式

例如，如果您想确保 $Email 参数始终是有效的电子邮件地址，您可以像这样设置验证属性：

function Process-UserInfo {
    param (
        [Parameter(Mandatory=$true)]
        [ValidatePattern("^[\w-]+(\.[\w-]+)*@([\w-]+\.)+[a-zA-Z]{2,7}$")]
        [string]$Email,

        [Parameter(Mandatory=$true)]
        [string]$Name
    )

    Write-Output "Name: $Name"
    Write-Output "Email: $Email"
}

Process-UserInfo -Name "John Doe" -Email "not-an-email" #End up in error
Process-UserInfo -Name "John Doe" -Email "[email protected]"

此验证逻辑是使用正则表达式指定的，以确保输入字符串与有效的电子邮件格式匹配。如果用户为此参数传递了无效值，脚本将提示他们更正输入。

在所有这些情况下，如果参数验证失败，PowerShell 将抛出错误，并且该函数将不会被执行。这样，您可以在问题导致其他功能出现问题之前尽早发现问题。

定义参数的默认值

为 PowerShell 函数参数设置默认值是使脚本更加用户友好和高效的好方法。当您定义具有默认值的参数时，您不必在调用函数时指定该值。如果未指定值，PowerShell 将自动使用默认值。您可以在参数声明本身中定义默认值，如下所示：

Function Get-ProcessInfo {
    Param(
        [string]$ProcessName = "notepad"
    )

    Get-Process $ProcessName
}

在此示例中，Get-ProcessInfo 函数采用一个参数 $ProcessName，其默认值为“notepad”。如果调用该函数时未指定 $ProcessName 的值，PowerShell 将使用默认值并返回有关记事本进程的信息。

让我们看另一个如何设置函数参数默认值的例子：

function MyFunction {
    param(
        [string]$Name = "John Doe",
        [int]$Age = 30
    )
    # Function body
}

在此示例中，函数 MyFunction 有两个参数：$Name 和 $Age。如果调用者没有为这些参数提供值，则将分别使用默认值“John Doe”和 30。但是，如果调用者为这些参数提供了值，则提供的值将覆盖默认值。

使用带有函数参数的管道输入

PowerShell还允许您使用带有函数参数的管道输入，这可以使您的脚本更加灵活和高效。为此，您可以使用 [ValueFromPipeline] 属性定义一个参数，该属性指示该函数应接受来自管道的输入。例如，这里有一个函数，它接受一个数字数组并返回它们的总和：

Function Add-Numbers {
Param (
   [Parameter(ValueFromPipeline=$true)]
   [int[]]$numbers
)
   $sum = $numbers | Measure-Object -Sum | Select-Object -ExpandProperty Sum
   return $sum
}

在此示例中，我们定义了一个名为 $numbers 的参数，它接受整数数组。我们还添加了 [ValueFromPipeline] 属性来指示该参数可以接受来自管道的输入。这意味着您可以使用管道输入将数字数组传递给此函数，如下所示：

1, 2, 3, 4, 5 | Add-Numbers

这会将数字数组传递给 $numbers 参数，并且该函数将返回它们的总和。

#PowerShell Function with Parameter from Pipeline
Function Test-Pipeline {
  param (
    [Parameter(ValueFromPipeline)]
    $Param
  )
  process { "$($Param.Name) was passed through the pipeline" }
}

#Call the function by passing parameters through Pipeline
Get-Process | Test-Pipeline

这会将代表每个正在运行的进程的对象传递给 Test-Pipeline 函数，该函数将为每个进程输出一条消息。

PowerShell 中的数组作为函数参数

使用数组作为 PowerShell 函数的参数允许您将多个值传递给参数。当您需要对多个项目执行相同的任务（例如处理多个文件或文件夹）时，这非常有用。

以下是如何使用 PowerShell 参数数组的示例：

Function Get-File {
    Param(
        [Parameter(Mandatory=$true)]
        [string[]]$Path
    )

    ForEach ($Item in $Path) {
        Get-Item $Item
    }
}
#Call the function
Get-File -Path "C:\Temp\AppLog.txt", "C:\Temp\FolderList.csv"

在此示例中，Get-File 函数采用字符串数组作为参数，该参数表示文件或文件夹路径。该函数使用 foreach 循环处理数组中的每个项目，并使用 Get-Item cmdlet 返回该项目。

让我们看一个使用数组的示例：

function Show-Names {
    param (
        [string[]]$Names
    )

    foreach ($Name in $Names) {
        Write-Output "Hello, $Name!"
    }
}

在此函数中，$Names 是一个字符串数组。我们可以传递多个名称，如下所示：Show-Names -Names "Alice", "Bob", "Charlie"。

使用 PowerShell 参数的最佳实践

使用 PowerShell 函数参数时，您应该遵循一些最佳实践，以确保您的脚本易于阅读、维护和调试。以下是一些提示：

• 使用描述性参数名称来解释参数的作用。
• 使用 [Parameter()] 属性指定其他属性，例如参数是否为强制参数或是否接受管道输入。
• 使用可选参数的默认值。
• 使用命名参数而不是位置参数，特别是当涉及许多参数时。
• 使用验证来确保传递给参数的值具有正确的类型。
• 为您的函数提供清晰的文档，包括有关它们接受的参数及其预期行为的信息。

通过遵循这些最佳实践，您可以创建带有易于使用和维护的参数的 PowerShell 函数。

包起来

掌握函数参数是 PowerShell 使用过程中至关重要的一步。它们允许您编写健壮、通用且适应各种场景的函数。在本综合指南中，我们探索了 PowerShell 中函数参数的世界。我们了解了函数参数的基础知识、可用的不同参数类型以及如何设置参数的默认值。我们还了解了如何强制参数、使用命名参数、验证输入值、使用管道中的参数以及利用开关参数。此外，我们还查看了 PowerShell 中函数参数的示例，并讨论了有效使用它们的最佳实践。

通过理解并有效地使用函数中的参数，您将能够编写更灵活、可重用且高效的脚本，从而增强您的 PowerShell 能力。快乐的脚本编写！