如何在 PowerShell 中创建和使用函数

函数在任何编程语言中都非常重要；这同样适用于 PowerShell。如果您想编写 PowerShell 脚本，您应该知道如何在 PowerShell 中创建和使用函数。我在这里向您展示详细信息，以便 PowerShell 初学者也能理解。

PowerShell 中的函数是什么？

PowerShell 中的函数是执行特定任务的命名代码块。函数用于封装代码以便重用和更好的组织。它们可以获取输入参数、处理数据并返回结果。使用函数，您可以避免代码重复，并使脚本更加模块化且更易于维护。

为什么在 PowerShell 中使用函数？

以下是在 PowerShell 中使用函数的一些优点。

1. 代码可重用性：函数允许您编写一段代码一次并在整个脚本中多次重用它。
2. 模块化：将复杂的脚本分解为更小的、可管理的函数，使您的代码更有条理、更易于阅读。
3. 可维护性：函数使更新和维护脚本变得更加容易。如果需要更改特定功能，只需更新该功能即可，无需搜索整个脚本。
4. 测试：可以独立测试函数，这有助于识别错误并确保脚本的每个部分都能正常工作。

PowerShell 函数的语法

在 PowerShell 中，函数是使用 Function 关键字定义的，后跟名称和一对大括号 {}。在大括号内，放置要执行的代码。

在 PowerShell 中定义函数的基本语法如下：

Function FunctionName {
    # Your code here
}

• Function：用于声明函数的关键字。
• FunctionName：您为函数指定的名称。最好使用动词-名词命名约定（例如 Get-UserInfo）。
• {}：花括号括起组成函数的代码块。

这是一个简单的例子。

Function Say-Hello {
    Write-Output "Hello, World!"
}

函数的名称应使用经过批准的动词，例如 Get、Set 或 New，后跟名词。这有助于维护标准命名约定并提高代码可读性。

定义函数时，请确保名称清楚地表明函数的用途。这有助于其他用户（或您自己）了解该函数的用途，而无需筛选代码。

读取 PowerShell 数据类型

在 PowerShell 中创建和使用函数

现在，让我们通过示例来了解如何在 PowerShell 中创建和使用函数。

PowerShell 基本功能

让我们从一个简单的例子开始。假设我们要创建一个向用户打招呼的函数。以下是完整的 PowerShell 脚本代码：

Function Greet-User {
    Write-Output "Hello, welcome to PowerShell scripting!"
}

# Calling the function
Greet-User

在此示例中，我们定义了一个输出问候消息的 Greet-User 函数。然后，我们只需输入函数名称即可调用该函数。

执行 PowerShell 脚本后，您可以在下面的屏幕截图中看到输出。

带参数的 PowerShell 函数

当函数接受参数时，它们会变得更加强大。参数允许您将数据传递到函数中，使其更加灵活。

以下是带参数的 PowerShell 函数的语法。

Function FunctionName {
    param (
        [Parameter1Type]$Parameter1,
        [Parameter2Type]$Parameter2
    )
    # Your code here
}

以下是具有参数的 PowerShell 函数的示例。

让我们创建一个通过名字来问候用户的函数。

Function Greet-User {
    param (
        [string]$FirstName,
        [string]$LastName
    )
    Write-Output "Hello, $FirstName $LastName! Welcome to PowerShell scripting!"
}

# Calling the function with parameters
Greet-User -FirstName "John" -LastName "Doe"

在此示例中，Greet-User 函数采用两个参数：FirstName 和 LastName。调用函数时，我们为这些参数提供值。

在我使用 VS code 执行 PowerShell 脚本后，请看下面的屏幕截图。

阅读带参数的 PowerShell 函数示例

PowerShell 函数默认参数值

您还可以在 PowerShell 函数中设置参数的默认值。如果调用者未提供值，则将使用默认值。

这是一个语法：

Function Greet-User {
    param (
        [string]$FirstName = "John",
        [string]$LastName = "Doe"
    )
    Write-Output "Hello, $FirstName $LastName! Welcome to PowerShell scripting!"
}

# Calling the function without parameters
Greet-User

在这种情况下，如果未提供参数，该函数将使用“John”和“Doe”作为默认值。

PowerShell 函数的返回值

PowerShell 函数也可以返回值。您可以在 PowerShell 函数中使用 return 关键字来返回值。

这是一个例子：

Function Add-Numbers {
    param (
        [int]$Number1,
        [int]$Number2
    )
    return $Number1 + $Number2
}

# Calling the function and storing the result
$result = Add-Numbers -Number1 5 -Number2 10
Write-Output "The sum is: $result"

此处，Add-Numbers 函数采用两个整数作为参数，将它们相加，然后返回结果。

函数中的强制参数和可选参数

PowerShell 函数中的参数可以是强制的，也可以是可选的。调用函数时必须提供强制参数；否则，PowerShell 将提示用户输入一个值。要定义强制参数，请使用 Mandatory 属性：

语法如下：

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

但是，如果未指定值，则可选参数不需要用户输入。可以为它们分配默认值：

param (
    [Parameter(Mandatory=$false)]
    [string]$City = "Unknown"
)

此设置确保该功能可以在最少的用户输入的情况下运行，但在需要时仍然强制执行关键输入。

在 PowerShell 函数中使用多个参数

您还可以创建处理多个参数并包含更复杂逻辑的函数。让我们在 PowerShell 中创建一个函数来计算购物车中商品的总价（包括税费）。

Function Calculate-TotalPrice {
    param (
        [hashtable]$Cart,
        [decimal]$TaxRate = 0.07
    )
    $total = 0
    foreach ($item in $Cart.Keys) {
        $total += $Cart[$item]
    }
    $totalWithTax = $total * (1 + $TaxRate)
    return [math]::Round($totalWithTax, 2)
}

# Simulated shopping cart
$cart = @{
    "Laptop" = 999.99
    "Mouse"  = 25.50
    "Keyboard" = 45.75
}

# Calling the function
$totalPrice = Calculate-TotalPrice -Cart $cart
Write-Output "The total price including tax is: $totalPrice"

在此示例中，Calculate-TotalPrice 函数采用代表购物车的哈希表和税率作为参数。

位置和命名参数

在 PowerShell 中，函数参数可以是位置参数或命名参数。 位置参数依赖于提供参数的顺序：

function Test-Params {
    param ([string]$First, [string]$Second)
    Write-Output "$First $Second"
}

Test-Params "Hello" "World"

对于命名参数，参数名称用于匹配输入：

function Test-Params {
    param ([string]$First, [string]$Second)
    Write-Output "$First $Second"
}

Test-Params -First "Hello" -Second "World"

PowerShell 函数参数集

参数集允许您为函数定义不同的参数集。这是一个例子。

Function Get-Info {
    param (
        [Parameter(Mandatory = $true, ParameterSetName = "ByName")]
        [string]$Name,

        [Parameter(Mandatory = $true, ParameterSetName = "ByID")]
        [int]$ID
    )
    switch ($PSCmdlet.ParameterSetName) {
        "ByName" { Write-Output "Getting info by Name: $Name" }
        "ByID" { Write-Output "Getting info by ID: $ID" }
    }
}

# Calling the function with different parameter sets
Get-Info -Name "John Doe"
Get-Info -ID 12345

管道输入作为函数的参数

PowerShell 函数还可以接受来自管道的输入。这是一个例子。

Function ConvertTo-UpperCase {
    param (
        [Parameter(ValueFromPipeline = $true)]
        [string]$InputString
    )
    process {
        Write-Output $InputString.ToUpper()
    }
}

# Using the function with pipeline input
"john doe", "jane smith" | ConvertTo-UpperCase

在此示例中，ConvertTo-UpperCase 函数接受来自管道的输入并将每个输入字符串转换为大写。

函数中的开始、处理和结束块

PowerShell 函数可以包含 Begin、Process 和 End 块来管理不同的执行阶段。

• Begin 块： 在开始时执行一次，通常用于初始化变量。
• 处理块：处理从管道接收的每个项目，为每个对象执行。
• 结束块：在处理完所有管道输入后运行，对于清理任务很有用。

例子 ：

function Get-Sample {
    [CmdletBinding()]
    param (
        [string]$Name,
        [int]$Age
    )
    begin {
        # Code to initialize
    }
    process {
        # Code to process each item
    }
    end {
        # Code to clean up
    }
}

这是在 PowerShell 函数中使用块的方法。

阅读使用参数从命令行运行 PowerShell 脚本

PowerShell 函数中的错误处理

处理 PowerShell 函数中的错误总是好的。 PowerShell 提供了不同的错误处理方法，例如 try-catch 块和错误变量。让我们看看如何在函数中合并错误处理。

使用尝试捕获

以下是如何在 PowerShell 函数中使用 try-catch。

Function Divide-Numbers {
    param (
        [int]$Dividend,
        [int]$Divisor
    )
    try {
        if ($Divisor -eq 0) {
            throw "Division by zero is not allowed."
        }
        $result = $Dividend / $Divisor
        return $result
    } catch {
        Write-Output "Error: $_"
    }
}

# Calling the function with error handling
$result = Divide-Numbers -Dividend 10 -Divisor 0
Write-Output "Result: $result"

在此示例中，Divide-Numbers 函数检查除数是否为零，如果为零则抛出错误。 try-catch 块捕获错误并输出相应的消息。

使用 -ErrorAction 和 $Error

PowerShell 还允许您使用 -ErrorAction 和 $Error 自动变量来控制错误行为。

以下是如何在 PowerShell 的函数中使用这些变量进行错误处理。

Function Get-FileContent {
    param (
        [string]$FilePath
    )
    Get-Content -Path $FilePath -ErrorAction Stop
}

# Calling the function with error handling
try {
    $content = Get-FileContent -FilePath "nonexistentfile.txt"
    Write-Output $content
} catch {
    Write-Output "Error: $_"
}

此处，Get-FileContent 函数使用 -ErrorAction Stop 确保 Get-Content 遇到的任何错误都被视为终止错误。然后 try-catch 块处理这些错误。

阅读 PowerShell 函数：返回值和多个值

如何在 PowerShell 中调用函数

要在PowerShell中调用函数，用户必须了解语法以及如何有效地传递参数。现在，让我向您展示调用函数的基本方法以及如何在 PowerShell 中向调用函数传递参数。

简单的 PowerShell 函数调用

要在 PowerShell 中调用函数，只需键入函数名称，后跟括号即可。例如，给定一个名为 Greet-User 的函数，您可以通过键入以下内容来调用它：

Greet-User

这将执行 Greet-User 函数中的代码。

将参数传递给函数

PowerShell 函数通常采用参数以使其更加灵活。要传递参数，请将它们包含在函数名称后面的括号中。例如，如果 Greet-User 接受用户名参数：

function Greet-User {
    param ($Name)
    Write-Output "Hello, $Name!"
}

您可以调用此函数并传递名称，如下所示：

Greet-User -Name "Alice"

这将导致输出：Hello, Alice!。参数可以是强制的，也可以是可选的。使用 param 块来定义它们，确保您指定它们是必需的还是具有默认值。

对于多个参数，请用空格分隔每个参数，如下所示：

Greet-User "Alice" 25

PowerShell 函数的最佳实践

在 PowerShell 中创建和使用函数时，您应该遵循一些最佳实践。

命名约定和认可的动词

函数应遵循动词-名词格式。例如，检索进程的函数可以命名为Get-Process。

PowerShell 有一个经过批准的动词列表，应使用这些动词来确保一致性。一些常见的动词包括获取、设置、删除和开始。使用这些动词可以帮助其他人快速理解函数的目的。

此外，函数名称应采用 PascalCase 格式。将每个单词的首字母大写，例如 Start-Service 或 Stop-Process，以提高可读性。

基于评论的帮助和文档

使用基于注释的帮助来记录功能可以增强其可用性。包括描述函数用途、参数和输出的注释。

文档以 .SYNOPSIS 开始，提供简要说明。使用 .DESCRIPTION 了解更多详细信息。使用 .PARAMETER 记录参数有助于澄清所需的输入。例如：

<#
.SYNOPSIS
   Retrieves the list of running processes.
.DESCRIPTION
   Retrieves and displays the list of all running processes on the system.
.PARAMETER Name
   The name of the process to retrieve.
.EXAMPLE
   Get-Process -Name "notepad"
#>

包含这些注释可以让其他人更容易理解和使用这些功能。它还有助于代码维护和未来更新。

PowerShell 函数示例

以下是一些 PowerShell 函数示例。

示例1：检索用户信息

下面的 PowerShell 函数使用哈希表从模拟数据库中检索用户信息。

# Simulated database of users
$users = @{
    "john.doe" = @{
        FirstName = "John"
        LastName  = "Doe"
        Email     = "[email protected]"
    }
    "jane.smith" = @{
        FirstName = "Jane"
        LastName  = "Smith"
        Email     = "[email protected]"
    }
}

Function Get-UserInfo {
    param (
        [string]$Username
    )
    if ($users.ContainsKey($Username)) {
        return $users[$Username]
    } else {
        Write-Output "User not found."
    }
}

# Calling the function
$userInfo = Get-UserInfo -Username "john.doe"
if ($userInfo) {
    Write-Output "First Name: $($userInfo.FirstName)"
    Write-Output "Last Name: $($userInfo.LastName)"
    Write-Output "Email: $($userInfo.Email)"
}

示例 2：计算含税总价

此 PowerShell 函数计算购物车中商品的总价（含税）。

Function Calculate-TotalPrice {
    param (
        [hashtable]$Cart,
        [decimal]$TaxRate = 0.07
    )
    $total = 0
    foreach ($item in $Cart.Keys) {
        $total += $Cart[$item]
    }
    $totalWithTax = $total * (1 + $TaxRate)
    return [math]::Round($totalWithTax, 2)
}

# Simulated shopping cart
$cart = @{
    "Laptop" = 999.99
    "Mouse"  = 25.50
    "Keyboard" = 45.75
}

# Calling the function
$totalPrice = Calculate-TotalPrice -Cart $cart
Write-Output "The total price including tax is: $totalPrice"

示例 3：将文本转换为大写

PowerShell 中的以下函数将输入文本转换为大写并支持管道输入。

Function ConvertTo-UpperCase {
    param (
        [Parameter(ValueFromPipeline = $true)]
        [string]$InputString
    )
    process {
        Write-Output $InputString.ToUpper()
    }
}

# Using the function with pipeline input
"john doe", "jane smith" | ConvertTo-UpperCase

这是下面屏幕截图中的输出：

示例 4：检查磁盘空间

此 PowerShell 函数检查指定驱动器上的可用磁盘空间，如果空间低于特定阈值，则返回警告。

Function Check-DiskSpace {
    param (
        [string]$DriveLetter = "C",
        [int]$ThresholdGB = 10
    )
    $drive = Get-PSDrive -Name $DriveLetter
    $freeSpaceGB = [math]::Round($drive.Free / 1GB, 2)
    if ($freeSpaceGB -lt $ThresholdGB) {
        Write-Output "Warning: Free space on drive $DriveLetter is below $ThresholdGB GB. Current free space: $freeSpaceGB GB."
    } else {
        Write-Output "Drive $DriveLetter has sufficient free space: $freeSpaceGB GB."
    }
}

# Calling the function
Check-DiskSpace -DriveLetter "C" -ThresholdGB 15

示例 5：备份文件

下面的 PowerShell 函数将文件从源目录备份到目标目录。

Function Backup-Files {
    param (
        [string]$SourceDirectory,
        [string]$DestinationDirectory
    )
    if (-Not (Test-Path $SourceDirectory)) {
        Write-Output "Source directory does not exist."
        return
    }
    if (-Not (Test-Path $DestinationDirectory)) {
        New-Item -ItemType Directory -Path $DestinationDirectory
    }
    Copy-Item -Path "$SourceDirectory\*" -Destination $DestinationDirectory -Recurse -Force
    Write-Output "Backup completed from $SourceDirectory to $DestinationDirectory."
}

# Calling the function
Backup-Files -SourceDirectory "C:\Users\JohnDoe\Documents" -DestinationDirectory "D:\Backup\Documents"

结论

我希望本教程能让您完整了解如何创建和使用 PowerShell 函数。我解释了 PowerShell 中函数的语法和一些示例。