PowerShell 函数

Powershell 中的函数使用关键字（function）声明，后面依次跟函数名称、左右大括号。函数将执行的代码包含在这些大括号中。　

函数基本操作：　

#创建函数
Function GetPSversion
{
   $PSVersionTable.PSVersion
}

#调用函数，直接写函数名
GetPSversion

#查看函数定义
$Function:GetPSversion

#导出函数定义到文本
$Function:GetPSversion | Out-File C:\Code\GetPSversion.ps1

#删除函数
del Function:GetPSversion

#查看内部定义函数：
dir function: | ft -AutoSize　　　
　　　　　

 

创建带参数的函数的三种方法#创建带参数的函数

Function GetPSprocess($processname)
{
Get-Process -Name "*$processname*"
}

Function GetPSprocess
{
param($processname)
Get-Process -Name "*$processname*"
}

 

#有默认参数值

Function GetPSprocess
{
param($processname='powershell')
Get-Process -Name "*$processname*"
}

#多个参数

Function GetPSprocess
{
param($processname,$keywords)
Get-Process -Name "*$processname*$keywords*"
}

 

 

调用函数：

 

直接使用函数名加参数方式

GetPSprocess
GetPSprocess power
GetPSprocess -processname power -keywords is

 

 

万能参数，无需声明：

Function GetPSprocess
{
   
   Get-Process -Name "*$args*"
}

 

高级函数

将PowerShell 中的函数转换为高级函数非常简单。函数与高级函数之间的区别是，高级函数具有多个自动添加到函数的通用参数。这些参数通常包括Verbose 和Debug

添加CmdletBinding 以将函数转换为高级函数。

function Test-MrCmdletBinding {
    [CmdletBinding()] #<<-- This turns a regular function into an advanced function
    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

#通过Get-Command 向下钻取参数。
Get-Command -name Test-MrCmdletBinding -Syntax
(Get-Command -Name Test-ModuleManifest).Parameters.Keys

 

 

 

 SupportsShouldProcess 会添加 WhatIf 和 Confirm 参数 。 只有做出更改的命令需要这些参数。

function Test-MrSupportsShouldProcess {

    [CmdletBinding(SupportsShouldProcess)]
    param (
        $ComputerName
    )

    Write-Output $ComputerName

}

现在有 WhatIf 和 Confirm 参数 。

 

 

 

 

参数验证

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [string]$ComputerName
    )

    Write-Output $ComputerName

}

指定参数数据类型 为string ，所以不允许有逗号分隔。

 

 

 强制指定参数 Mandatory

function Test-MrParameterValidation
{
  [CmdletBinding()]
  param
  (
      [Parameter(Mandatory)]
      [string]$ComputerNmae
  )

  Write-Output $ComputerNmae
}

 

 

 如果需要参数有多个值，指定类型为string[]

function Test-MrParameterValidation {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string[]]$ComputerName
    )

    Write-Output $ComputerName

}

 

 

如果需要指定一个默认参数需要将ValidateNotNullOrEmpty 参数验证属性与默认值一起使用，不过不能与必需（Mandatory）参数一起使用！

 

function Test-MrParameterValidation
{
  [CmdletBinding()]
  param
  (
      [ValidateNotNullOrEmpty()]
      [string[]]$ComputerNmae = "s1"
  )

  Write-Output $ComputerNmae
}

默认将输出s1

 

 

 

 使用使用 Write-Verbose 进行注释

function Test-MrVerboseOutput {

    [CmdletBinding()]
    param (
        [ValidateNotNullOrEmpty()]
        [string[]]$ComputerName = $env:COMPUTERNAME
    )

    foreach ($Computer in $ComputerName) {
        Write-Verbose -Message "Attempting to perform some action on $Computer"
        Write-Output $Computer
    }

}

 

 

管道输入

若要接受按值显示管道输入，请为该特定参数指定 ValueFromPipeline 参数属性。

接受按属性名称显示的管道输入是类似的，但它是使用 ValueFromPipelineByPropertyName 参数属性指定的。

管道输入一次输入一个项，这类似于在 foreach 循环中处理项的方式。 如果要接受数组作为输入，则至少需要一个 process 块才能处理所有项。

function Test-MrPipelineInput {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline)]
        [string[]]$ComputerName
    )

    PROCESS {
        Write-Output $ComputerName
    }

}

BEGIN 和 END 块是可选的。 BEGIN 在 PROCESS 块之前指定，用于在从管道接收项之前执行任何初始工作。 了解这一点很重要。 在 BEGIN 块中无法访问通过管道传入的值。 END 块将在 PROCESS 块之后指定，用于在处理完通过管道传入的所有值之后进行清理。

 

错误处理

可采用多种不同的方法在 PowerShell 中处理错误。 Try/Catch 是处理错误的较新式的方法。将 ErrorAction 参数的值指定为 Stop，将非终止错误转换为终止错误 。

function Test-MrErrorHandling {

    [CmdletBinding()]
    param (
        [Parameter(Mandatory,
                   ValueFromPipeline,
                   ValueFromPipelineByPropertyName)]
        [string[]]$ComputerName
    )

    PROCESS {
        foreach ($Computer in $ComputerName) {
            try {
                Test-WSMan -ComputerName $Computer -ErrorAction Stop
            }
            catch {
                Write-Warning -Message "Unable to connect to Computer: $Computer"
            }
        }
    }

}

 

基于注释的帮助

将基于注释的帮助添加到函数，以便你与之共享函数的人知道如何使用它们。

 

function Get-MrAutoStoppedService {

<#
.SYNOPSIS
    Returns a list of services that are set to start automatically, are not
    currently running, excluding the services that are set to delayed start.

.DESCRIPTION
    Get-MrAutoStoppedService is a function that returns a list of services from
    the specified remote computer(s) that are set to start automatically, are not
    currently running, and it excludes the services that are set to start automatically
    with a delayed startup.

.PARAMETER ComputerName
    The remote computer(s) to check the status of the services on.

.PARAMETER Credential
    Specifies a user account that has permission to perform this action. The default
    is the current user.

.EXAMPLE
     Get-MrAutoStoppedService -ComputerName 'Server1', 'Server2'

.EXAMPLE
     'Server1', 'Server2' | Get-MrAutoStoppedService

.EXAMPLE
     Get-MrAutoStoppedService -ComputerName 'Server1' -Credential (Get-Credential)

.INPUTS
    String

.OUTPUTS
    PSCustomObject

.NOTES
    Author:  Mike F Robbins
    Website: http://mikefrobbins.com
    Twitter: @mikefrobbins
#>

    [CmdletBinding()]
    param (

    )

    #Function Body

}

 

 

 

 本文参考：  https://www.cnblogs.com/keepSmile/p/5821358.html

                     https://learn.microsoft.com/zh-cn/powershell/scripting/learn/ps101/09-functions?view=powershell-7.2