about_Functions

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

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

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

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

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

function Get-PowerShellProcess { Get-Process pwsh }

После определения функции его можно использовать как встроенные командлеты. Например, чтобы вызвать только что определенную Get-PowerShellProcess функцию:

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

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

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

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

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

Ключевое слово фильтра используется для создания типа функции, которая выполняется на каждом объекте в конвейере. Фильтр напоминает функцию со всеми его операторами в блоке 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по-прежнему выполняются.

end

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

clean

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

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

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

Чистый блок удаляет все выходные данные, записанные в поток success .

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

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

function <function-name> {statements}

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

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
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Дополнительные сведения о классе атрибутов 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()

Фильтры

Фильтр — это тип функции, которая выполняется на каждом объекте в конвейере. Фильтр напоминает функцию со всеми его операторами в блоке 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: введите двоеточие после функции, как и при ссылке C D на диск компьютера.

Следующая команда отображает все функции в текущем сеансе 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 см. в статье "Создание справки по командлетам".

См. также

• about_Automatic_Variables
• about_Comment_Based_Help
• about_Function_Provider
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Parameters
• about_Profiles
• about_Scopes
• about_Script_Blocks