about_Functions

2015-11-17

Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0

РАЗДЕЛ

about_Functions

КРАТКОЕ ОПИСАНИЕ

В этом разделе объясняется, как создавать и использовать функции в Windows PowerShell®.

ПОДРОБНОЕ ОПИСАНИЕ

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

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

        function Get-PowerShellProcess {Get-Process PowerShell}

или сложными, как командлет или приложение.

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

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

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

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

Функции могут также действовать как командлеты. Можно создать функцию, работающую как командлет, не прибегая к программированию C#. Дополнительные сведения см. в статье about_Functions_Advanced (https://go.microsoft.com/fwlink/?LinkID=144511).

Синтаксис

Для функции используется следующий синтаксис:

          function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]  
          {
              param([type]$parameter1 [,[type]$parameter2])

              dynamicparam {<statement list>}
  
              begin {<statement list>}
              process {<statement list>}
              end {<statement list>}
          }

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

          - A Function keyword
          - A scope (optional)
          - A name that you select
          - Any number of named parameters (optional)
          - One or more Windows PowerShell commands enclosed in braces ({})

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

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

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

          function <function-name> {statements}

Например, следующая функция запускает Windows 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 {$_.LastWriteTime -gt $Start}
          }

Можно создать набор небольших полезных функций. Добавьте эти функции в свой профиль Windows PowerShell, как описано в статье about_Profiles и далее в этом разделе.

Имена функций

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

Имена функций должны состоять из пары глагол-существительное, где глагол определяет действие функции, а существительное — элемент, на который направлено действие командлета.

В функциях следует использовать стандартные глаголы, утвержденные для всех команд Windows PowerShell. С помощью этих глаголов имена команд можно сделать простыми, последовательными и понятными.

Дополнительные сведения о стандартных глаголах Windows PowerShell см. в статье MSDN "Глаголы командлетов" по адресу https://go.microsoft.com/fwlink/?LinkID=160773.

ФУНКЦИИ С ПАРАМЕТРАМИ

С функциями можно использовать параметры, в том числе именованные, позиционные, динамические параметры и параметры-переключатели. Узнать больше о динамических параметрах в функциях можно в статье about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173).

Именованные параметры

Можно определить любое количество именованных параметров. Для именованных параметров можно задать значение по умолчанию, как описано далее в этом разделе.

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

          function <name> { 
               param ([type]$parameter1[,[type]$parameter2])
               <statement list> 
          }

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

          function <name> [([type]$parameter1[,[type]$parameter2])] { 
              <statement list> 
          }

Эти два метода ничем не отличаются. Используйте тот, который вам нравится больше.

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

В следующем примере приведена функция Get-SmallFiles. Эта функция включает параметр $size. Функция отображает все файлы, размер которых меньше значения параметра $size, и исключает каталоги:

          function Get-SmallFiles {
              param ($size)
              Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer} 
          }

В функции можно использовать переменную $size, т. е. имя, определенное для параметра.

Чтобы использовать эту функцию, введите следующую команду:

          C:\PS> function Get-SmallFiles –Size 50

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

          C:\PS> function Get-SmallFiles 50

Чтобы определить значение параметра по умолчанию, после имени параметра введите знак равенства и значение, как показано в следующем варианте примера Get-SmallFiles:

          function Get-SmallFiles ($size = 100) {
              Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer} 
          }

Если ввести Get-SmallFiles без значения, функция присваивает переменной $size значение 100. Если значение указано, функция будет использовать это значение.

При необходимости можно включить краткую справку, описывающую значение параметра по умолчанию. Это можно сделать, добавив атрибут PSDefaultValue к описанию параметра и определив свойство Help этого атрибута. Чтобы включить справку, описывающую значение по умолчанию (100) параметра Size в функции Get-SmallFiles, добавьте атрибут PSDefaultValue, как показано в следующем примере:

          function Get-SmallFiles {
              param (
              [PSDefaultValue(Help = '100')]
              $size = 100
              )

Дополнительные сведения о классе атрибутов PSDefaultValue см. в статье "Элементы PSDefaultValueAttribute" библиотеки MSDN. (https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx

Позиционные параметры

Позиционный параметр — это параметр без имени. Чтобы связать каждое значение с параметром в функции, Windows PowerShell использует порядок значений параметров.

При использовании позиционных параметров одно или несколько значений вводятся после имени функции. Значения позиционных параметров присваиваются переменной массива $args. Значению, которое следует за именем функции, назначается первая позиция в массиве $args — $args[0].

Приведенная ниже функция Get-Extension добавляет расширение имени текстового файла (TXT) к вашему имени файла.

          function Get-Extension {
              $name = $args[0] + ".txt"
              $name
          }

          C:\PS> Get-Extension myTextFile
          myTextFile.txt

ПАРАМЕТРЫ-ПЕРЕКЛЮЧАТЕЛИ

Параметр-переключатель — это параметр, для которого не требуется значение. Вместо этого вводится имя функции, за которым следует имя параметра-переключателя.

Чтобы определить параметр-переключатель, укажите тип [switch] перед именем параметра, как показано в следующем примере:

          function Switch-Item {
              param ([switch]$on)
              if ($on) { "Switch on" }
              else { "Switch off" }
          }

При вводе переключателя On после имени функции для нее отображается значение Switch on. Без переключателя отображается значение Switch off.

          C:\PS> Switch-Item -on
          Switch on

          C:\PS> Switch-Item
          Switch off

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

          C:\PS> Switch-Item -on:$true
          Switch on

          C:\PS> Switch-Item -on:$false
          Switch off

Представление параметров команды методом сплаттинга

Сплаттинг можно использовать для представления параметров команды. Эта возможность появилась в версии Windows PowerShell 3.0.

Этот метод используется в функциях, которые вызывают команды в сеансе. Вам не нужно объявлять или перечислять параметры команды или изменять функцию при изменении параметров команды.

Следующий пример функции вызывает командлет Get-Command. Для представления параметров Get-Command используется компонент @Args.

          function Get-MyCommand { Get-Command @Args }

Все параметры командлета Get-Command можно использовать при вызове функции Get-MyCommand. Параметры и значения параметров передаются в команду с помощью компонента @Args.

         PS C:\>Get-MyCommand -Name Get-ChildItem
         CommandType     Name                ModuleName
         -----------     ----                ----------
         Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Компонент @Args использует автоматический параметр $Args, который представляет необъявленные параметры и значения командлета из остальных аргументов.

Подробнее о сплаттинге можно узнать в статье about_Splatting (https://go.microsoft.com/fwlink/?LinkId=262720).

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

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

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

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

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

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

Следующая функция использует ключевое слово Process. В этой функции показаны примеры из конвейера:

          function Get-Pipeline 
          { 
              process {"The value is: $_"} 
          }

Чтобы продемонстрировать эту функцию, введите список чисел, разделенных запятыми, как показано в следующем примере:

          C:\PS> 1,2,4 | Get-Pipeline
          The value is: 1
          The value is: 2
          The value is: 4

При использовании функции в конвейере объекты, передаваемые в функцию, присваиваются автоматической переменной $_. С помощью ключевого слова Begin функция выполняет операторы до получения каких-либо объектов из конвейера. С помощью ключевого слова End операторы выполняются после получения функцией всех объектов из конвейера.

В следующем примере показана автоматическая переменная $input с ключевыми словами Begin и End:

          function Get-PipelineBeginEnd 
          {
              begin {"Begin: The input is $input"}
              end {"End:   The input is $input" }
          }

Если эта функция выполняется с помощью конвейера, она возвращает следующие результаты:

          C:\PS> 1,2,4 | Get-PipelineBeginEnd
          Begin: The input is 
          End:   The input is 1 2 4

При выполнении оператора Begin функция не получает входные данные из конвейера. Оператор End выполняется после получения функцией необходимых значений.

Если функция использует ключевое слово Process, она считывает данные в переменной $input. Следующий пример содержит список операторов Process:

          function Get-PipelineInput
          {
              process {"Processing:  $_ " }
              end {"End:   The input is: $input" }
          }

В этом примере каждый объект, передаваемый в функцию из конвейера, отправляется в список операторов Process. Операторы Process выполняются отдельно для каждого объекта. При достижении функцией ключевого слова End автоматическая переменная $input принимает пустое значение.

          C:\PS> 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 {$_.DependentServices} }

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

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

Подробнее об области видимости в Windows PowerShell можно узнать в статье about_Scopes (https://go.microsoft.com/fwlink/?LinkID=113260).

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

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

При указании диска Function: используйте двоеточие после слова Function, аналогично меткам дисков C: или D: компьютера.

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

          Get-ChildItem function:

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

          (Get-ChildItem function:help).Definition

Подробнее о диске Function: можно узнать в разделе справки по поставщику функций. Введите Get-Help Function или просмотрите справку в библиотеке TechNet по адресу https://go.microsoft.com/fwlink/?LinkID=113436.

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

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

Чтобы использовать функцию во всех сеансах Windows PowerShell, добавьте ее в свой профиль Windows PowerShell. Дополнительные сведения о профилях см. в статье about_Profiles (https://go.microsoft.com/fwlink/?LinkID=113729).

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

Написание справки по функциям

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

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

        Get-Help Get-MyDisks

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

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

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

Справка по функциям на основе XML

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

Для привязки функции к разделу справки на основе XML нужно использовать ключевое слово справки на основе комментариев — ExternalHelp. Без этого ключевого слова команда Get-Help не сможет найти раздел справки по функции и вернет только автоматически созданную справку.

Подробнее о ключевом слове ExternalHelp см. в разделе about_Comment_Based_Help. Дополнительные сведения о справке на основе XML см. в статье MSDN "Написание справки по командлетам".

СМ. ТАКЖЕ

about_Automatic_Variables

about_Comment_Based_Help

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

Функция (поставщик)

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

about_Functions

РАЗДЕЛ

КРАТКОЕ ОПИСАНИЕ

ПОДРОБНОЕ ОПИСАНИЕ

ФУНКЦИИ С ПАРАМЕТРАМИ

ПАРАМЕТРЫ-ПЕРЕКЛЮЧАТЕЛИ

СМ. ТАКЖЕ

Дополнительные ресурсы