PowerShell
Функции PowerShell

Вступление

Простая функция без параметров

Это пример функции, которая возвращает строку. В этом примере функция вызывается в инструкции, присваивающей значение переменной. Значение в этом случае является возвращаемым значением функции.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function объявляет следующий код как функцию.

Get-Greeting - это имя функции. В любое время, когда эта функция должна использоваться в скрипте, эту функцию можно вызвать путем вызова ее по имени.

{ ... } - это блок сценария, выполняемый функцией.

Если вышеуказанный код выполняется в ISE, результаты будут выглядеть примерно так:

Hello World
Hello World

Основные параметры

Функция может быть определена с помощью параметров с помощью блока param:

function Write-Greeting {
    param(
        [Parameter(Mandatory,Position=0)]
        [String]$name,
        [Parameter(Mandatory,Position=1)]
        [Int]$age
    )
    "Hello $name, you are $age years old."
}

Или используя простой синтаксис функции:

function Write-Greeting ($name, $age) {
    "Hello $name, you are $age years old."
}

Примечание. Параметры каста не требуются ни в одном определении параметра.

Простой синтаксис функций (SFS) имеет очень ограниченные возможности по сравнению с блоком param.
Хотя вы можете определить параметры, которые должны быть выставлены внутри функции, вы не можете указывать атрибуты параметров , использовать [CmdletBinding()] параметров , включать [CmdletBinding()] , с SFS (и это не исчерпывающий список).

Функции могут вызываться с помощью упорядоченных или именованных параметров.

Порядок параметров в вызове сопоставляется с порядком объявления в заголовке функции (по умолчанию) или может быть задан с использованием атрибута параметра Position (как показано в примере расширенной функции выше).

$greeting = Write-Greeting "Jim" 82

Альтернативно, эта функция может быть вызвана с именованными параметрами

$greeting = Write-Greeting -name "Bob" -age 82

Обязательные параметры

Параметры функции могут быть отмечены как обязательные

function Get-Greeting{
    param
    (
        [Parameter(Mandatory=$true)]$name
    )
    "Hello World $name"
}

Если функция вызывается без значения, в командной строке будет указано значение:

$greeting = Get-Greeting 

cmdlet Get-Greeting at command pipeline position 1
Supply values for the following parameters:
name: 

Расширенные функции

Это копия расширенного функционального фрагмента из PowerShell ISE. В основном это шаблон для многих вещей, которые вы можете использовать с расширенными функциями в Powershell. Ключевые моменты:

• интеграция get-help - начало функции содержит блок комментариев, который настроен для чтения командлетом get-help. Функциональный блок может быть расположен в конце, если это необходимо.
• cmdletbinding - функция будет вести себя как командлет
• параметры
• наборы параметров

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
.INPUTS
   Inputs to this cmdlet (if any)
.OUTPUTS
   Output from this cmdlet (if any)
.NOTES
   General notes
.COMPONENT
   The component this cmdlet belongs to
.ROLE
   The role this cmdlet belongs to
.FUNCTIONALITY
   The functionality that best describes this cmdlet
#>
function Verb-Noun
{
    [CmdletBinding(DefaultParameterSetName='Parameter Set 1', 
                  SupportsShouldProcess=$true, 
                  PositionalBinding=$false,
                  HelpUri = 'http://www.microsoft.com/',
                  ConfirmImpact='Medium')]
    [Alias()]
    [OutputType([String])]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true, 
                   ValueFromPipeline=$true,
                   ValueFromPipelineByPropertyName=$true, 
                   ValueFromRemainingArguments=$false, 
                   Position=0,
                   ParameterSetName='Parameter Set 1')]
        [ValidateNotNull()]
        [ValidateNotNullOrEmpty()]
        [ValidateCount(0,5)]
        [ValidateSet("sun", "moon", "earth")]
        [Alias("p1")] 
        $Param1,

        # Param2 help description
        [Parameter(ParameterSetName='Parameter Set 1')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateScript({$true})]
        [ValidateRange(0,5)]
        [int]
        $Param2,

        # Param3 help description
        [Parameter(ParameterSetName='Another Parameter Set')]
        [ValidatePattern("[a-z]*")]
        [ValidateLength(0,15)]
        [String]
        $Param3
    )

    Begin
    {
    }
    Process
    {
        if ($pscmdlet.ShouldProcess("Target", "Operation"))
        {
        }
    }
    End
    {
    }
}

Проверка параметров

Существует множество способов проверки ввода параметров в PowerShell.

Вместо того, чтобы писать код внутри функций или скриптов для проверки значений параметров, эти ParameterAttributes будут выдавать, если передаются недопустимые значения.

ValidateSet

Иногда нам нужно ограничить возможные значения, которые может принимать параметр. Предположим, мы хотим разрешить только красный, зеленый и синий для параметра $Color в скрипте или функции.

Мы можем использовать атрибут параметра ValidateSet для ограничения этого. У этого есть дополнительное преимущество, позволяющее завершить вкладку при настройке этого аргумента (в некоторых средах).

param(
    [ValidateSet('red','green','blue',IgnoreCase)]
    [string]$Color
)

Вы также можете указать IgnoreCase для отключения чувствительности к регистру.

ValidateRange

Этот метод проверки параметров принимает минимальное и максимальное значение Int32 и требует, чтобы параметр находился в этом диапазоне.

param(
    [ValidateRange(0,120)]
    [Int]$Age
)

ValidatePattern

Этот метод проверки параметров принимает параметры, соответствующие указанному шаблону регулярного выражения.

param(
    [ValidatePattern("\w{4-6}\d{2}")]
    [string]$UserName
)

ValidateLength

Этот метод проверки параметров проверяет длину переданной строки.

param(
    [ValidateLength(0,15)]
    [String]$PhoneNumber
)

ValidateCount

Этот метод проверки параметров проверяет количество аргументов, переданных, например, массивом строк.

param(
    [ValidateCount(1,5)]
    [String[]]$ComputerName
)

ValidateScript

Наконец, метод ValidateScript необычайно гибкий, принимая скриптовый блок и оценивая его с помощью $ _ для представления переданного аргумента. Затем он передает аргумент, если результат равен $ true (включая любой вывод как действительный).

Это можно использовать для проверки наличия файла:

param(
    [ValidateScript({Test-Path $_})]
    [IO.FileInfo]$Path 
)

Чтобы проверить, существует ли пользователь в AD:

param(
    [ValidateScript({Get-ADUser $_})]
    [String]$UserName
)

И почти все, что вы можете написать (как это не ограничивается oneliners):

param(
    [ValidateScript({
        $AnHourAgo = (Get-Date).AddHours(-1)
        if ($_ -lt $AnHourAgo.AddMinutes(5) -and $_ -gt $AnHourAgo.AddMinutes(-5)) {
            $true
        } else {
            throw "That's not within five minutes. Try again."
        }
    })]
    [String]$TimeAboutAnHourAgo
)