РАЗДЕЛ
about_Functions
КРАТКОЕ ОПИСАНИЕ
Описывает, как создавать и использовать функции в Windows PowerShell.
ПОЛНОЕ ОПИСАНИЕ
Функция представляет собой список инструкций и имеет имя, выбираемое
пользователем. Для выполнения функции вводится ее имя. Инструкции в списке
выполняются так, как если бы они были введены в командную строку.
Как и у командлетов, у функций могут быть параметры. Это могут
быть именованные, позиционные и динамические параметры, а также
параметры-переключатели. Параметры функций могут считываться из
командной строки или из конвейера.
Функции могут возвращать значения, которые затем могут отображаться,
присваиваться переменным или передаваться другим функциям и командлетам.
Список инструкций функции может содержать списки инструкций
различных типов с ключевыми словами Begin, Process и End. Эти
списки инструкций по-разному обрабатывают поступающий через
конвейер ввод.
Фильтр представляет собой функцию особого типа, использующую
ключевое слово Filter.
Функции могут также выступать в роли командлетов. Можно создать
функцию, которая работает как командлет, без программирования на
языке C#. Дополнительные сведения см. в разделе about_Functions_Ad
vanced.
Синтаксис
Ниже показан синтаксис функции:
function [<область:>]<имя> [([тип]$parameter1[,[тип]$parameter2])]
{
param([тип]$parameter1 [,[тип]$parameter2])
dynamicparam {<список_инструкций>}
begin {<список_инструкций>}
process {<список_инструкций>}
end {<список_инструкций>}
}
Функция включает один из следующих элементов:
- ключевое слово Function;
- область (необязательно);
- выбранное пользователем имя;
- произвольное число именованных параметров (необязательно);
- одну или несколько команд Windows PowerShell, заключенных
в фигурные скобки ({}).
Дополнительные сведения о ключевом слове Dynamicparam и динамических
параметрах в функциях см. в разделе about_Functions_Advanced_Parameters.
Простые функции
Чтобы функции были полезными, они не обязательно должны быть
сложными. Показанная ниже функция получает переменные среды,
которые не относятся к учетной записи System текущей системы:
function other_env
{
get-wmiObject win32_environment |
where {$_.username -ne "<System>"}
}
Чтобы выполнить эту функцию, введите "other_env".
Можно создать набор из небольших полезных функций и добавить
эти функции в профиль Windows PowerShell, как описано в разделе
about_Profiles и далее в этом разделе.
Функции с параметрами
С функциями можно использовать параметры, в том числе
именованные, позиционные и динамические параметры, а также параметры-
переключатели. Дополнительные сведения о динамических параметрах в
функциях см. в разделе about_Functions_Advanced_Parameters.
Именованные параметры
Можно определить произвольное число именованных параметров. Для
именованных параметров можно задать значение по умолчанию, как
показано далее в этом разделе.
Параметры можно определить внутри фигурных скобок, используя
ключевое слово Param, как показано в следующем примере.
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
Кроме того, параметры можно определять вне фигурных скобок без
ключевого слова Param, как показано в следующем примере.
function <имя> [([тип]$parameter1[,[тип]$parameter2])] {
<список_инструкций>
}
Эти два подхода абсолютно равноправны. Можно использовать любой
предпочтительный подход.
При выполнении функции значение, заданное в качестве параметра,
присваивается переменной, которая содержит имя параметра.
Значение этой переменной можно использовать в функции.
Ниже приведен пример функции с именем Small_files. У этой
функции имеется параметр $size. Функция отображает все файлы,
размер которых меньше значения параметра, и исключает каталоги.
function small_files {
param ($size)
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
В этой функции можно использовать переменную $size, которая
представляет собой имя, определенное для параметра.
Чтобы использовать эту функцию, введите следующую команду:
C:\PS> function small_files -size 50
Кроме того, значение именованного параметра можно задать без
указания имени параметра. Например, результат выполнения
следующей команды не отличается от результата выполнения
команды с именем параметра size:
C:\PS> function small_files 50
Чтобы задать для параметра значение по умолчанию, после имени
параметра введите знак равенства и значение, как показано в
следующей версии функции Small_files:
function small_files ($size = 100) {
Get-ChildItem c:\ | where {
$_.length -lt $size -and !$_.PSIsContainer}
}
Если ввести имя функции "small_files" без значения, то
переменной $size будет присвоено значение 100. Если указать
значение, функция будет использовать это значение.
Позиционные параметры
Позиционный параметр - это параметр без имени. Чтобы связать
значение параметра с параметром в функции, в Windows PowerShell
используется порядок следования значений параметров.
При использовании позиционных параметров необходимо ввести одно
или несколько значений после имени функции. Значения
позиционных параметров присваиваются массиву $args. Значение,
указанное непосредственно после имени функции, присваивается
первому элементу массива $args ($args[0]).
Приведенная ниже функция Extension добавляет к задаваемому
имени файла расширение ".txt":
function extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> extension myTextFile
myTextFile.txt
Функция может принимать несколько позиционных параметров. В
следующем примере отображаются все значения, введенные после
имени функции.
function repeat { foreach ($arg in $args) { "The input is
$arg" } }
C:\PS>repeat one
The input is one
C:\PS> repeat one two three
The input is one
The input is two
The input is three
Эту функцию можно использовать с произвольным числом значений.
Данная функция присваивает каждое значение элементу массива $args.
Параметры-переключатели
Переключатель - это параметр, которому не требуется значение.
Имя параметра-переключателя просто указывается после имени функции.
Чтобы определить параметр-переключатель, укажите перед именем
параметра тип [switch], как показано в следующем примере:
function switchExample {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
Если после имени функции ввести параметр-переключатель On,
функция выведет текст "Switch on". Без параметра-переключателя
будет выведен текст "Switch off".
C:\PS> SwitchExample -on
Switch on
C:\PS> SwitchExample
Switch off
Кроме того, при выполнении функции можно присвоить
переключателю логическое значение, как показано в следующем примере:
C:\PS> SwitchExample -on:$true
Switch on
C:\PS> SwitchExample -on:$false
Switch off
Передача объектов в функции по конвейеру
Все функции могут принимать входные данные с помощью конвейера.
Управление обработкой поступающих через конвейер входных данных
осуществляется в функции с помощью ключевых слов Begin, Process
и End. В следующем примере показаны три ключевых слова:
function <имя> {
begin {<список_инструкций>}
process {<список_инструкций>}
end {<список_инструкций>}
}
Список инструкций Begin выполняется только один раз в начале функции.
Список инструкций Process выполняется по одному разу для
каждого из объектов в конвейере. Пока выполняется блок Process,
каждый объект из конвейера присваивается автоматической переменной
$_, по одному объекту за раз.
После того как функция получит все объекты в конвейере, один
раз выполняется список инструкций из блока End. Если ключевые
слова Begin, Process и End не используются, все инструкции
выполняются так, как если бы они находились в блоке End.
В следующей функции используется ключевое слово Process.
Функция отображает примеры из конвейера:
function pipelineFunction
{
process {"The value is: $_"}
}
Чтобы продемонстрировать эту функцию, введите массив
разделенных запятыми чисел, как показано в следующем примере:
C:\PS> 1,2,4 | pipelineFunction
The value is: 1
The value is: 2
The value is: 4
При использовании функции в конвейере направляемые в функцию объекты
присваиваются автоматической переменной $input. Функция выполняет
инструкции с ключевым словом Begin, прежде чем будут получены объекты
из конвейера. Функция выполняет инструкции в блоке End после
получения из конвейера всех объектов.
В следующем примере показано использование автоматической
переменной $input с ключевыми словами Begin и End.
function PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
Если выполнить эту функцию с использованием конвейера, будут
выведены следующие результаты:
C:\PS> 1,2,4 | PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
Когда выполняется инструкция Begin, у функции еще нет входных
данных из конвейера. Инструкция End выполняется после получения
значений функцией.
Если функция содержит ключевое слово Process, то она считывает
данные в переменную $input. Ниже показан пример списка
инструкций Process:
function PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
В этом примере каждый объект, направляемый в функцию по
конвейеру, передается в список инструкций Process. Инструкции в
блоке Process выполняются для каждого объекта по очереди. Когда
функция достигает ключевого слова End, автоматическая
переменная $input пуста.
C:\PS> 1,2,4 | PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
Фильтры
Фильтр - этот тип функции, которая выполняется для каждого объекта в
конвейере. Фильтр напоминает функцию, все инструкции которой
находятся в блоке Process.
Синтаксис фильтра имеет следующий вид:
filter [<область:>]<имя> {<список_инструкций>}
Следующий фильтр принимает из конвейера записи журнала и
отображает либо всю запись, либо только сообщение из записи:
filter ErrorLog ([switch]$message)
{
if ($message) { out-host -inputobject $_.Message }
else { $_ }
}
Область функции
Функция существует в пределах области, в которой она была создана.
Если функция является частью скрипта, эта функция доступна в
инструкциях в этом скрипте. По умолчанию функции в скрипте не
доступны в командной строке.
Область функции можно задать. Например, в следующем примере функция
добавляется в глобальную область:
function global:get-dependentsvs { get-service |
where {$_.dependentservices} }
Если функция принадлежит к глобальной области, ее можно
использовать в скриптах, в функциях и в командной строке.
Обычно функции образуют собственную область. Элементы,
создаваемые внутри функции, например переменные, существуют
только в пределах области этой функции.
Дополнительные сведения об областях в Windows PowerShell см в
разделе about_Scope.
Поиск функций и управление ими с помощью диска Function: Все
функции и фильтры в Windows PowerShell автоматически сохраняются на
диске Function:. Этот диск предоставляется поставщиком функций
Windows PowerShell.
При обращении к диску Function: необходимо ставить двоеточие
после слова Function, как это происходит при обращении к диску
C или D компьютера.
Следующая команда отображает все функции в текущем сеансе
Windows PowerShell:
C:\PS> dir function:
Команды в функции хранятся в виде блока скрипта в свойстве
definition функции. Например, чтобы отобразить команды в
функции Help, входящей в состав Windows PowerShell, введите:
(dir function:help).definition
Дополнительные сведения о диске Function: см. в разделе Function.
Повторное использование функций в новых сеансах
При вводе функции в командной строке Windows PowerShell функция
становится частью текущего сеанса. Она доступна до завершения
сеанса.
Чтобы использовать функцию во всех сеансах Windows PowerShell,
добавьте функцию в профиль Windows PowerShell. Дополнительные
сведения о профилях см. в разделе about_Profiles.
Кроме того, функцию можно сохранить в файле скрипта Windows
PowerShell. Введите функцию в текстовый файл и сохраните файл с
расширением PS1.
Создание справки для функций
Командлет Get-Help возвращает справку для функций, а также для
командлетов, поставщиков и скриптов. Чтобы получить справку для
функции, введите командлет Get-Help и имя функции.
Например, чтобы получить справку для функции MyDisks, введите:
get-help MyDisks
Имеется два способа написания справки для функции.
-- Справка для функции на основе комментариев
Темы справки создаются посредством использования в
комментариях специальных ключевых слов. Чтобы создать для
функции справку на основе комментариев, комментарии
необходимо поместить в начало или конец тела функции или в строки,
предшествующие ключевому слову function. Дополнительные сведения о
справке на основе комментариев см. в разделе about_Comment_Based_Help.
-- Справка для функции на основе XML
Создайте раздел справки XML подобно тому, как это делается
для командлетов. Справка на основе XML нужна в том случае,
если разделы справки локализуются для различных языков.
Чтобы связать функцию с разделом справки XML, воспользуйтесь
ключевым словом комментариев справки .ExternalHelp.
Дополнительные сведения о ключевом слове ExternalHelp см. в
разделе about_Comment_Based_Help. Дополнительные сведения о
справке на основе XML см. в разделе "How to Write Cmdlet
Help" (Как писать справку для командлетов) в библиотеке MSDN.
СМ. ТАКЖЕ
about_Automatic_Variables
about_Comment_Based_Help
about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Parameters
about_Profiles
about_Scopes
about_Script_Blocks
Function (поставщик)