PowerShell 函数参数：构建更好函数的实用指南

教程
PowerShell

在 PowerShell 中构建函数是使脚本模块化和可重用的好方法。但如果您希望这些函数在不同场景中具有适应性，添加函数参数可以将它们提升到一个新水平。

在本教程中，我们将通过添加参数来控制日志消息、文件路径和验证，扩展一个基本的日志记录函数。

到最后，您将看到参数如何使您的函数多功能、抗错误，并成为 PowerShell 工具箱中强大的补充。

定义基本的 Write-Log 函数

我们将从一个基本函数开始，该函数接受一个输入参数用于日志消息，并将其附加到带有时间戳的标准日志文件中。

在这个例子中：

  • $LogMessage 参数被标记为必填，因此如果您不提供值，PowerShell 会提示您输入。
  • 每个日志条目包括格式为 HH:mm:ss 的时间戳。
function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path "C:\Scripts\software_installer.log" -Value "$timeGenerated - $LogMessage"
}

测试 Write-Log 函数

现在，Write-Log 函数具有基本结构并接受参数，是时候测试其功能了。测试有助于确保函数的每个方面，从默认设置到自定义输入，按预期执行并优雅地处理错误。

通过调用带有自定义消息的 Write-Log 函数进行测试：

Write-Log -LogMessage 'Testing a new log message'

此命令将带有时间戳的新条目添加到日志文件中 (C:\Scripts\software_installer.log)。

关于 Write-Log 函数需要注意的几点：

Standardized Information Logging By setting a default path for the log file, you don’t have to specify the file name every time you call the function. This standardizes all log information to a single file, keeping your logs organized.
简化记录过程 该函数抽象了诸如使用Get-Date获取当前日期和时间以及使用Add-Content附加内容等细节。作为该函数的用户，您可以专注于向日志文件写入消息，而无需记住这些细节。
改进的代码可读性 该函数明确将消息记录到指定的日志文件中，清晰地表明其目的是记录，而不仅仅是写入到通用文本文件中。这使得代码在一瞥之间更加自解释且更易理解。

通过这些改进，Write-Log函数有助于简化记录任务，使脚本更加清晰且易于维护。

您可以通过检查日志文件的内容来查看最新的日志消息：

Get-Content -Path "C:\Scripts\software_installer.log"

此命令会显示所有日志条目，包括带有时间戳的最新消息。

但也许您意外地调用了Write-Log而没有LogMessage参数：

Write-Log

您会注意到，由于LogMessage是必需的，PowerShell将阻止该函数的运行。但是，如果LogMessage不是强制性的，将写入一个空消息，从而创建一个意外的“糟糕”条目。

通过重新检查日志文件来验证结果：

Get-Content -Path "C:\Scripts\software_installer.log"

通过自定义日志文件路径增加灵活性

虽然该函数运行良好，但我们可以通过添加一个$LogFilePath参数使其更加灵活。该参数允许您指定自定义文件路径同时提供默认路径。

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [string]$LogFilePath = 'C:\Scripts\software_installer.log'
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

请注意，$LogFilePath的默认路径为C:\Scripts\software_installer.log，但您可以提供任何有效路径。

要指定不同的文件路径，请这样调用Write-Log：

Write-Log -LogMessage 'Custom path log message' -LogFilePath 'C:\Scripts\custom_log.log'

使用ValidateScript强制文件路径

您不希望函数记录不存在的文件。为此，您可以通过使用ValidateScript参数属性在记录之前验证文件是否存在。该属性允许您针对参数值运行代码，验证后再运行函数。

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [ValidateScript({ Test-Path -Path $_ })]
        [string]$LogFilePath = 'C:\Scripts\software_installer.log'
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

通过ValidateScript，Write-Log检查您提供的文件路径是否存在。如果文件不存在，PowerShell会停止并返回错误。

您可以在调用函数之前创建一个空文件，以确保函数按预期工作：

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Log entry in a new file' -LogFilePath 'C:\Scripts\softwarex_installer.log'

测试Write-Log功能和验证

在为函数添加灵活性后，测试其是否按预期工作就显得很自然了。您必须通过检查ValidateScript属性来确保强大的日志功能，并查看它如何增强您的Write-Log函数。

让我们通过尝试记录到一个不存在的文件来看看ValidateScript是如何工作的：

Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

在这种情况下，ValidateScript 属性通过调用 Test-Path 来检查指定的日志文件路径是否存在。如果路径不存在，则函数会返回一个错误。

函数失败是因为 C:\Scripts\softwarex_installer.log 不存在。您可以通过手动运行 Test-Path 来验证这一点：

Test-Path 'C:\Scripts\softwarex_installer.log'

由于 Test-Path 返回 $false，所以文件确实不存在。

为了解决这个问题，请创建一个空的日志文件并重新测试。

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

现在，函数按预期工作。

通过查看日志文件来确认结果：

Get-Content -Path 'C:\Scripts\softwarex_installer.log'

使用 ValidateScript 和其他参数验证属性可以强制执行函数参数的正确使用，减少错误，并使您的 PowerShell 函数更加可靠。

结论

向 PowerShell 函数添加参数极大地增强了其灵活性和实用性。通过结合默认值、强制属性和验证，您的函数可以处理各种输入，并保持可靠性。

使用这些技术，您现在可以构建可扩展、用户友好的函数，使其能够无缝地融入各种脚本中。

随着您创建更多高级的 PowerShell 工具来简化和增强工作流程，继续扩展这些技能。查看这个 PowerShell 参数 教程，深入了解函数参数！

Source:
https://adamtheautomator.com/powershell-function-parameters/