about_Functions

Краткое описание

Описывает создание и использование функций в PowerShell.

Подробное описание

Функция — это список инструкций PowerShell, которые имеют имя, которое вы назначаете. При запуске функции введите имя функции. Инструкции в списке выполняются так, как если бы вы ввели их в командной строке.

Функции могут быть как простые, так и:

function Get-PowerShellProcess { Get-Process PowerShell }

Функция также может быть сложной как командлет или приложение.

Как и командлеты, функции могут иметь параметры. Параметры могут быть именованы, позиционные, коммутаторы или динамические параметры. Параметры функции можно считывать из командной строки или из конвейера.

Функции могут возвращать значения, которые могут отображаться, назначаться переменным или передаваться другим функциям или командлетам. Можно также указать возвращаемое значение с помощью return ключевое слово. Ключевое слово return не влияет на другие выходные данные, возвращаемые функцией. return Однако ключевое слово завершает функцию в этой строке. Дополнительные сведения см. в about_Return.

Список инструкций функции может содержать различные типы списков beginинструкций с ключевое слово , и endprocessclean. Эти инструкции перечисляют входные данные из конвейера по-разному.

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

Функции также могут выступать как командлеты. Вы можете создать функцию, которая работает так же, как командлет, без использования C# программирования. Дополнительные сведения см. в about_Functions_Advanced.

Внимание

В файлах скриптов и модулях на основе скриптов необходимо определить функции перед их вызовом.

Синтаксис

Ниже приведен синтаксис функции:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}
function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

Функция включает следующие элементы:

  • Ключевое слово function
  • область (необязательно)
  • Выбранное имя
  • Любое число именованных параметров (необязательно)
  • Одна или несколько команд PowerShell, вложенных в фигурные скобки {}

Дополнительные сведения о ключевое слово и динамических dynamicparam параметрах в функциях см. в about_Functions_Advanced_Parameters.

Методы обработки входных данных

Методы, описанные в этом разделе, называются методами обработки входных данных. Для функций эти три метода представлены блоками beginprocessфункции и end блоками функции. PowerShell 7.3 добавляет clean метод блочного процесса.

Вам не требуется использовать любой из этих блоков в функциях. Если вы не используете именованный блок, PowerShell помещает код в end блок функции. Однако если вы используете любой из этих именованных блоков или определите dynamicparam блок, необходимо поместить весь код в именованный блок.

В следующем примере показана структура функции, содержащей begin блок для однократной предварительной обработки, process блок для нескольких операций записи и end блок для однократной последующей обработки.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

begin

Этот блок используется для предоставления необязательной однократной предварительной обработки для функции. Среда выполнения PowerShell использует код в этом блоке один раз для каждого экземпляра функции в конвейере.

process

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

Автоматическая переменная $_ или $PSItem содержит текущий объект в конвейере для использования в блоке process . Автоматическая $input переменная содержит перечислитель, доступный только для функций и блоков скриптов. Дополнительные сведения см. в статье about_Automatic_Variables.

  • Вызов функции в начале или за пределами конвейера выполняет process блок один раз.
  • В конвейере process блок выполняется один раз для каждого входного объекта, достигающего функции.
  • Если входные данные конвейера, достигающие функции, пусты, process блок не выполняется.
    • endclean И блоки beginпо-прежнему выполняются.

Внимание

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

end

Этот блок используется для предоставления необязательной одноразовой последующей обработки для функции.

clean

Блок clean был добавлен в PowerShell 7.3.

Блок clean — удобный способ очистки ресурсов, распределенных между блоками begin, process и end. Семантически он похож на блок finally, охватывающий все другие именованные блоки функции скрипта или командлета скрипта. Очистка ресурсов применяется в следующих сценариях:

  1. Когда выполнение конвейера завершается нормально без неустранимой ошибки.
  2. Когда выполнение конвейера прерывается из-за неустранимой ошибки.
  3. Если конвейер остановлен с помощью Select-Object -First.
  4. Если конвейер остановлен с помощью клавиш CTRL+C или команды StopProcessing().

Внимание

Добавление блока clean является критическим изменением. Поскольку clean анализируется как ключевое слово, пользователи не могут напрямую вызвать команду clean в качестве первой инструкции в блоке скрипта. Однако, скорее всего, это не проблема. Команда по-прежнему может вызываться с помощью оператора вызова (& clean).

Простые функции

Функции не должны быть сложными, чтобы быть полезными. Простейшие функции имеют следующий формат:

function <function-name> {statements}

Например, следующая функция запускает PowerShell с параметром Запуска от имени Администратор istrator.

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Чтобы использовать функцию, введите: Start-PSAdmin

Чтобы добавить операторы в функцию, введите каждую инструкцию в отдельной строке или используйте точку с запятой ; для разделения инструкций.

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

function Get-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

Вы можете создать панель элементов полезных небольших функций. Добавьте эти функции в профиль PowerShell, как описано в about_Profiles и более поздних версиях этого раздела.

Имена функций

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

Имена функций должны состоять из пары существительных команд, в которой команда определяет действие, выполняемое функцией, и существительное определяет элемент, на котором командлет выполняет свое действие.

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

Дополнительные сведения о стандартных командах PowerShell см. в разделе "Утвержденные команды".

Функции с параметрами

Можно использовать параметры с функциями, включая именованные параметры, позиционные параметры, параметры коммутатора и динамические параметры. Дополнительные сведения о динамических параметрах в функциях см. в about_Functions_Advanced_Parameters.

именованных параметров

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

Параметры внутри фигурных скобок можно определить с помощью param ключевое слово, как показано в следующем примере синтаксиса:

function <name> {
  param ([type]$parameter1 [,[type]$parameter2])
  <statement list>
}

Можно также определить параметры вне фигурных скобок без Param ключевое слово, как показано в следующем примере синтаксиса:

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

Ниже приведен пример этого альтернативного синтаксиса.

function Add-Numbers([int]$one, [int]$two) {
    $one + $two
}

Хотя первый метод предпочтителен, разница между этими двумя методами отсутствует.

При запуске функции значение, указанное для параметра, назначается переменной, содержащей имя параметра. Значение этой переменной можно использовать в функции.

В следующем примере называется Get-SmallFilesфункция. Эта функция имеет $Size параметр. Функция отображает все файлы, которые меньше значения $Size параметра, и он исключает каталоги:

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

В функции можно использовать $Size переменную, которая является именем, определенным для параметра.

Чтобы использовать эту функцию, введите следующую команду:

Get-SmallFiles -Size 50

Можно также ввести значение именованного параметра без имени параметра. Например, следующая команда дает тот же результат, что и команда, которая называет параметр Size :

Get-SmallFiles 50

Чтобы определить значение по умолчанию для параметра, введите знак равенства и значение после имени параметра, как показано в следующем варианте Get-SmallFiles примера:

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Если вы вводите Get-SmallFiles значение без значения, функция назначает 100 $size. Если указать значение, функция использует это значение.

При необходимости можно указать краткую строку справки, описывающую значение по умолчанию параметра, добавив атрибут PSDefaultValue в описание параметра и указав свойство справки PSDefaultValue. Чтобы предоставить строку справки, описывающую значение по умолчанию (100) параметра Size в Get-SmallFiles функции, добавьте атрибут PSDefaultValue , как показано в следующем примере.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

Дополнительные сведения о классе атрибутов PSDefaultValue см. в разделе "Элементы атрибутов PSDefaultValue".

Позиционные параметры

Позиционный параметр — это параметр без имени параметра. PowerShell использует порядок значения параметра для связывания каждого значения параметра с параметром в функции.

При использовании позиционных параметров введите одно или несколько значений после имени функции. Значения позиционных параметров назначаются переменной массива $args . Значение, следующее за именем функции, назначается первой позиции в массиве $args$args[0].

Get-Extension Следующая функция добавляет .txt расширение имени файла в указанное имя файла:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}
Get-Extension myTextFile
myTextFile.txt

Переключение параметров

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

Чтобы определить параметр switch, укажите тип [switch] перед именем параметра, как показано в следующем примере:

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

При вводе On параметра switch после имени функции отображается Switch onфункция. Без параметра коммутатора отображается Switch off.

Switch-Item -on
Switch on
Switch-Item
Switch off

При запуске функции можно также назначить логическое значение переключателю, как показано в следующем примере:

Switch-Item -on:$true
Switch on
Switch-Item -on:$false
Switch off

Использование Splatting для представления параметров команд

Вы можете использовать splatting для представления параметров команды. Эта функция представлена в Windows PowerShell 3.0.

Используйте этот метод в функциях, вызывающих команды в сеансе. Не нужно объявлять или перечислять параметры команды или изменять функцию при изменении параметров команды.

В следующем примере функции вызывается Get-Command командлет. Команда используется @Args для представления параметров Get-Command.

function Get-MyCommand { Get-Command @Args }

При вызове Get-MyCommand функции можно использовать все параметрыGet-Command. Параметры и значения параметров передаются команде с помощью @Args.

Get-MyCommand -Name Get-ChildItem
CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Эта @Args функция использует автоматический $Args параметр, представляющий необъявленные параметры и значения командлетов из оставшихся аргументов.

Дополнительные сведения см. в about_Splatting.

Передача объектов в функции

Любая функция может принимать входные данные из конвейера. Вы можете контролировать, как функция обрабатывает входные данные из конвейера с помощью begin, processendи clean ключевое слово. В следующем примере синтаксиса показаны следующие ключевое слово:

Список process инструкций выполняется один раз для каждого объекта в конвейере. process Во время выполнения блока каждый объект конвейера назначается автоматической $_ переменной, один объект конвейера за раз.

Следующая функция использует process ключевое слово. Функция отображает значения из конвейера:

function Get-Pipeline
{
  process {"The value is: $_"}
}

1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4

Если требуется функция, которая может принимать входные или входные данные конвейера из параметра, process блок должен обрабатывать оба варианта. Например:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

PS> 1,2,3,4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1,2,3,4
10

При использовании функции в конвейере объекты, которые передаются в функцию, назначаются автоматической переменной $input . Функция выполняет инструкции с begin ключевое слово до появления объектов из конвейера. Функция выполняет инструкции с end ключевое слово после получения всех объектов из конвейера.

В следующем примере показана автоматическая $input переменная с begin ключевое слово end .

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

Если эта функция выполняется с помощью конвейера, отображаются следующие результаты:

1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End:   The input is 1 2 4

При выполнении инструкции begin функция не имеет входных данных из конвейера. Оператор end выполняется после того, как функция имеет значения.

Если функция имеет ключевое слово, каждый объект в ней process удаляется $input и назначается$_.$input В следующем примере содержится список инструкций process :

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

В этом примере каждый объект, передаваемый в функцию, отправляется в список инструкций process . Инструкции process выполняются в каждом объекте, один объект за раз. Автоматическая переменная пуста$input, когда функция достигает end ключевое слово.

1,2,4 | Get-PipelineInput
Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Дополнительные сведения см. в разделе "Использование перечислителей"

PowerShell 7.3 добавил блок clean . Блок clean — это удобный способ очистки ресурсов, созданных и используемых в beginблоках, processи end в блоках. Семантически он похож на блок finally, охватывающий все другие именованные блоки функции скрипта или командлета скрипта. Очистка ресурсов применяется в следующих сценариях:

  1. Когда выполнение конвейера завершается нормально без неустранимой ошибки.
  2. Когда выполнение конвейера прерывается из-за неустранимой ошибки.
  3. Если конвейер остановлен с помощью Select-Object -First.
  4. При остановке конвейера с помощью CTRL+C или StopProcessing()

Внимание

Добавление блока clean является критическим изменением. Поскольку clean анализируется как ключевое слово, пользователи не могут напрямую вызвать команду clean в качестве первой инструкции в блоке скрипта. Однако, скорее всего, это не проблема. Команда по-прежнему может вызываться с помощью оператора вызова (& clean).

Фильтры

Фильтр — это тип функции, которая выполняется на каждом объекте в конвейере. Фильтр напоминает функцию со всеми его операторами в блоке process .

Синтаксис фильтра выглядит следующим образом:

filter [<scope:>]<name> {<statement list>}

Следующий фильтр принимает записи журнала из конвейера, а затем отображает либо всю запись, либо только часть сообщения записи:

filter Get-ErrorLog ([switch]$Message)
{
  if ($Message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Эта функция используется следующим образом.

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

Область функции

Функция существует в область, в которой она создана.

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

Можно указать область функции. Например, функция добавляется в глобальный область в следующем примере:

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Если функция находится в глобальной область, можно использовать функцию в сценариях, в функциях и в командной строке.

Функции создают новый область. Элементы, созданные в функции, такие как переменные, существуют только в область функции.

Дополнительные сведения см. в about_Scopes.

Поиск функций и управление ими с помощью функции: диск

Все функции и фильтры в PowerShell автоматически хранятся на Function: диске. Этот диск предоставляется поставщиком функций PowerShell.

При обращении к диску Function: введите двоеточие после функции, как и при ссылке CD на диск компьютера.

Следующая команда отображает все функции в текущем сеансе PowerShell:

Get-ChildItem function:

Команды в функции хранятся в виде блока скрипта в свойстве определения функции. Например, чтобы отобразить команды в функции справки, которая поставляется с PowerShell, введите:

(Get-ChildItem function:help).Definition

Можно также использовать следующий синтаксис.

$function:help

Дополнительные сведения о Function: диске см. в разделе справки для поставщика функций . Введите Get-Help Function.

Повторное использование функций в новых сеансах

При вводе функции в командной строке PowerShell функция становится частью текущего сеанса. Эта функция доступна до окончания сеанса.

Чтобы использовать функцию во всех сеансах PowerShell, добавьте функцию в профиль PowerShell. Дополнительные сведения о профилях см. в about_Profiles.

Вы также можете сохранить функцию в файле скрипта PowerShell. Введите функцию в текстовом файле и сохраните файл с расширением .ps1 имени файла.

Написание справки по функциям

Командлет Get-Help получает справку по функциям, а также для командлетов, поставщиков и скриптов. Чтобы получить справку по функции, введите Get-Help имя функции.

Например, чтобы получить справку по Get-MyDisks функции, введите:

Get-Help Get-MyDisks

Вы можете написать справку для функции с помощью одного из двух следующих методов:

  • Справка на основе комментариев для функций

    Создайте раздел справки с помощью специальных ключевое слово в комментариях. Чтобы создать справку на основе комментариев для функции, комментарии должны размещаться в начале или конце текста функции или в строках, предшествующих функции ключевое слово. Дополнительные сведения о справке на основе комментариев см. в about_Comment_Based_Help.

  • Справка на основе XML для функций

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

    Чтобы связать функцию с разделом справки на основе XML, используйте .EXTERNALHELP справку на основе комментариев ключевое слово. Без этого ключевое слово Get-Help не удается найти раздел справки по функции и вызовы Get-Help для функции возвращать только автоматическую справку.

    Дополнительные сведения о ключевое слово см. в .EXTERNALHELP about_Comment_Based_Help. Дополнительные сведения о справке на основе XML см. в статье "Создание справки по командлетам".

См. также