about_Functions

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

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

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

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

PowerShell определяет два типа функций:

• Функция — это блок кода, который можно вызывать по имени. Он может принимать входные и возвращаемые выходные данные. Функции определяются с помощью ключевого function слова.
• Фильтр — это тип функции, предназначенной для обработки данных из конвейера. Фильтры определяются с помощью ключевого filter слова.

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

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

Синтаксис функции

Функции определяются с помощью следующего синтаксиса:

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, вложенных в фигурные скобки {}

Если вы не используете одно из ключевых слов (begin, process, , end) cleanв function определении, PowerShell помещает инструкции в end блок.

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

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

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.

Синтаксис фильтра

Цель filter функции — предоставить короткий способ определения функции, которая выполняется на каждом объекте в конвейере.

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

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

Чтобы упростить синтаксис функцийfilter, опустите ключевое слово блока скрипта (begin, , process, endclean). PowerShell помещает инструкции в process блок. Вы можете использовать любой из других блоков в функции фильтра, но намерение было предоставить короткий способ определения функции, которая имеет единственную цель обработки каждого объекта в конвейере.

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

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

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

Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly

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

Методы, описанные в этом разделе, называются методами обработки входных данных. Для функций эти три метода с именем beginprocessend и блоки функции. 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.

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

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-NewPicture {
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse
  $allPics | 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-Command функции можно использовать все параметрыGet-MyCommand. Параметры и значения параметров передаются команде с помощью @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 используемая в блоках int begin и end script.

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()

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

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

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

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

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

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

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

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

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

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

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

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

Get-ChildItem Function:

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

(Get-ChildItem Function:help).Definition

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

$Function:help

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

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

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

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

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

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

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

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

Get-Help Get-MyDisks

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

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

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

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

  Справка на основе XML необходима, если необходимо локализовать содержимое справки на нескольких языках. Чтобы связать функцию с XML-файлом справки, используйте .EXTERNALHELP ключевое слово справки на основе комментариев. Без этого ключевого слова 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