О функциях

Статья
06/21/2023

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

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

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

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

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

function Get-PowerShellProcess { Get-Process PowerShell }

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

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

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

Список инструкций функции может содержать различные типы списков инструкций с ключевыми словами Begin, Processи End. Эти списки операторов обрабатывают входные данные из конвейера по-разному.

Фильтр — это специальный тип функции, использующий Filter ключевое слово.

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

Синтаксис

Ниже приведен синтаксис функции:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

Функция включает следующие элементы:

ключевое слово Function
область (необязательно)
Выбранное имя
Любое количество именованных параметров (необязательно)
Одна или несколько команд PowerShell, заключенных в фигурные скобки {}

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

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

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

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 см. в разделе Утвержденные команды в Документация Майкрософт.

Функции с параметрами

С функциями можно использовать параметры, включая именованные параметры, позиционные параметры, параметры switch и динамические параметры. Дополнительные сведения о динамических параметрах в функциях см. в разделе 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($one, $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 в описание параметра и указав свойство HelppsDefaultValue. Чтобы предоставить строку справки, описывающую значение по умолчанию (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-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 параметр automatic, который представляет необъявленные параметры командлета и значения из оставшихся аргументов.

Дополнительные сведения о сплаттинге см. в разделе about_Splatting.

Передача объектов в функции

Любая функция может принимать входные данные из конвейера. Вы можете управлять обработкой входных данных из конвейера функцией с помощью Beginключевых слов , Processи End . В следующем примере синтаксиса показаны три ключевых слова:

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

Список Begin инструкций выполняется только один раз в начале функции.

Важно!

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

Список инструкций Process выполняется один раз для каждого объекта в конвейере. Process Во время выполнения блока каждый объект конвейера назначается автоматической $_ переменной по одному объекту конвейера за раз.

После того как функция получит все объекты в конвейере, список инструкций End выполняется один раз. Если ключевые слова , Processили End не Beginиспользуются, все инструкции обрабатываются как End список операторов.

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

При использовании функции в конвейере объекты, переданные в функцию, назначаются автоматической переменной $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 { $_ }
}

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

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

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

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

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

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

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

Дополнительные сведения о область в PowerShell см. в разделе 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 имени файла.

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

Командлет 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 см. в разделе How to Write Cmdlet Help.