about_Functions
Краткое описание
Описывает создание и использование функций в PowerShell.
Подробное описание
Функция — это список инструкций PowerShell, которые имеют имя, которое вы назначаете. При запуске функции введите имя функции. Инструкции в списке выполняются так, как если бы вы ввели их в командной строке.
Функции могут быть как простые, так и:
function Get-PowerShellProcess { Get-Process PowerShell }
После определения функции его можно использовать как встроенные командлеты. Например, чтобы вызвать только что определенную Get-PowerShellProcess
функцию:
Get-PowerShellProcess
NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName
------ ----- ----- ------ -- -- -----------
110 78.72 172.39 10.62 10936 1 powershell
Функция также может быть сложной как командлет или приложение.
Как и командлеты, функции могут иметь параметры. Параметры могут быть именованы, позиционные, коммутаторы или динамические параметры. Параметры функции можно считывать из командной строки или из конвейера.
Функции могут возвращать значения, которые могут отображаться, назначаться переменным или передаваться другим функциям или командлетам. Можно также указать возвращаемое значение с помощью ключевого return
слова. Ключевое return
слово не влияет на другие выходные данные, возвращаемые функцией. Однако ключевое return
слово завершает функцию в этой строке. Дополнительные сведения см. в about_Return.
Список инструкций функции может содержать различные типы списков инструкций с ключевыми словами begin
иprocess
end
. Эти инструкции перечисляют входные данные из конвейера по-разному.
Ключевое слово фильтра используется для создания типа функции, которая выполняется на каждом объекте в конвейере. Фильтр напоминает функцию со всеми его операторами в блоке process
.
Функции также могут выступать как командлеты. Вы можете создать функцию, которая работает так же, как командлет, без использования C#
программирования. Дополнительные сведения см. в about_Functions_Advanced.
Внимание
В файлах скриптов и модулях на основе скриптов необходимо определить функции перед их вызовом.
Синтаксис
Ниже приведен синтаксис функции:
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
function [<scope:>]<name>
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
Функция включает следующие элементы:
- Ключевое
function
слово - Область (необязательно)
- Выбранное имя
- Любое число именованных параметров (необязательно)
- Одна или несколько команд PowerShell, вложенных в фигурные скобки
{}
Дополнительные сведения о ключевых словах и динамических параметрах в функциях см. в dynamicparam
about_Functions_Advanced_Parameters.
Методы обработки входных данных
Методы, описанные в этом разделе, называются методами обработки входных данных. Для функций эти три метода представлены блоками begin
process
функции и end
блоками функции.
Вам не требуется использовать любой из этих блоков в функциях. Если вы не используете именованный блок, 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
блок не выполняется.end
Блокиbegin
по-прежнему выполняются.
Внимание
Если для параметра функции задано принятие входных данных конвейера, а process
блок не определен, обработка записей по записи завершится ошибкой. В этом случае функция будет выполняться только один раз, независимо от входных данных.
end
Этот блок используется для предоставления необязательной одноразовой последующей обработки для функции.
Простые функции
Функции не должны быть сложными, чтобы быть полезными. Простейшие функции имеют следующий формат:
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
process
слов и end
ключевых слов. В следующем примере синтаксиса показаны следующие ключевые слова:
Список 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:
Дополнительные сведения см. в разделе "Использование перечислителей"
Фильтры
Фильтр — это тип функции, которая выполняется на каждом объекте в конвейере. Фильтр напоминает функцию со всеми его операторами в блоке 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
PowerShell