about_Functions

РАЗДЕЛ
	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 (поставщик)