about_Functions

Статья
05/09/2024

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

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

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

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

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

function Get-PowerShellProcess { Get-Process PowerShell }

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

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

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

Список операторов функции может содержать различные типы списков операторов с ключевыми словами begin, process, endи 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.

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

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

Важно!

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

`end`

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

`clean`

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

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

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

Внимание!

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

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

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

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 в описание параметра и указав свойство Helpобъекта 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 отображается Switch off.

Switch-Item -on

Switch on

Switch-Item

Switch off

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

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Использование 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ключевых слов , process, endи 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, охватывающий все другие именованные блоки функции скрипта или командлета скрипта. Очистка ресурсов применяется в следующих сценариях:

Когда выполнение конвейера завершается нормально без неустранимой ошибки.
Когда выполнение конвейера прерывается из-за неустранимой ошибки.
Если конвейер остановлен с помощью Select-Object -First.
при остановке конвейера с помощью клавиш 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:

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

(Get-ChildItem function:help).Definition

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

$function:help

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

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

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

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

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

Справка по написанию функций

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

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

Get-Help Get-MyDisks

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

Comment-Based справка по функциям

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

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

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

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

Поделиться через