РАЗДЕЛ
about_Functions_Advanced_Methods
КРАТКОЕ ОПИСАНИЕ
Описывает, каким образом функции, имеющие атрибут CmdletBinding, могут
использовать методы и свойства, доступные скомпилированным командлетам.
ПОЛНОЕ ОПИСАНИЕ
Функции, имеющие атрибут CmdletBinding, могут обращаться к
некоторым методам и свойствам через переменную $pscmdlet. Эти методы
включают следующие:
- методы обработки входных данных, используемые скомпилированными
командлетами;
- методы ShouldProcess и ShouldContinue, используемые для
получения реакции пользователя перед выполнением действия;
- метод ThrowTerminatingError для создания записей об ошибках;
- несколько методов Write, которые возвращают выходные данные
различных типов;
- несколько методов Write, которые возвращают выходные данные
различных типов.
Все методы и свойства командлета PSCmdlet доступны расширенным
функциям. Дополнительные сведения об этих методах и свойствах см.
в разделе System.Management.Automation.PSCmdlet библиотеки MSDN
(Microsoft Developer Network) по адресу
https://go.microsoft.com/fwlink/?LinkId=142139.
Методы обработки ввода
Описанные в этом разделе методы называются методами обработки
ввода. Для функций эти методы представляются блоками Begin,
Process и End в теле функции. Каждая функция должна включать
по крайней мере один из этих блоков. Среда выполнения Windows
PowerShell использует код внутри этих блоков при выполнении функции.
(Кроме того, эти блоки доступны функциям, которые не используют
атрибут CmdletBinding.)
Begin
Этот блок служит для задания в функции необязательных выполняемых
однократно операций предварительной обработки. Среда выполнения
Windows PowerShell использует код в этом блоке один раз для каждого
экземпляра функции в конвейере.
Process
Этот блок служит для задания операция обработки в функции
каждой записи. Этот блок может выполняться неограниченное число
раз или вообще не выполняться в зависимости от передаваемых функции
входных данных. Например, если функция является первой командой в
конвейере, блок Process будет выполнен один раз. Если функция не
является первой командой в конвейере, блок Process будет вызываться
по одному разу для каждого входного объекта, получаемого функцией из
конвейера. Если входные данные через конвейер не поступают, блок
Process не используется.
Этот блок необходимо определить в том случае, если параметры функции
заданы таким образом, что функция должна принимать входные данные из
конвейера. Если этот блок не задан, а параметр принимает входные данные
из конвейера, функция не сможет обработать значения, переданные ей через
конвейер.
Кроме того, если функция поддерживает запросы подтверждения
(параметр SupportsShouldProcess атрибута Parameter имеет
значение $True), вызов метода ShouldProcess должен
осуществляться из блока Process.
End
Этот блок служит для задания в функции необязательных выполняемых
однократно операций последующей обработки.
В следующем примере показан шаблон функции, которая содержит
блок Begin для однократной предварительной обработки, блок
Process для обработки нескольких записей и блок End для однократной
последующей обработки.
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)] Param
($Parameter1)
Begin{}
Process{}
End{}
}
Методы подтверждения
ShouldProcess
Этот метод вызывается, чтобы запросить подтверждение у пользователя,
прежде чем функция выполнит действие, которое изменит систему. Выполнение
функции продолжается в зависимости от возвращаемого этим методом
логического значения. Этот метод можно вызывать только из блока Process{}
функции. Кроме того, должен быть задан атрибут CmdletBinding, подтверждающий,
что функция поддерживает использование метода ShouldProcess (как показано
в предыдущем примере).
Дополнительные сведения об этом методе см. в разделе
System.Management.Automation.Cmdlet.ShouldProcess библиотеки MSDN
по адресу https://go.microsoft.com/fwlink/?LinkId=142142.
Дополнительные сведения о запросах подтверждения см. в разделе
"Запрос подтверждения" библиотеки MSDN по адресу
https://go.microsoft.com/fwlink/?LinkID=136658.
ShouldContinue
Этот метод вызывается, чтобы отобразить второе сообщение с запросом
подтверждения. Он должен вызываться, когда метод ShouldProcess возвращает
значение $true. Дополнительные сведения об этом методе см. в разделе
System.Management.Automation.Cmdlet.ShouldContinue библиотеки
MSDN по адресу https://go.microsoft.com/fwlink/?LinkId=142143.
Методы ошибок
Когда происходит ошибка, функции могут вызывать два различных
метода. Если произошла непрерывающая ошибка, функция должна
вызвать метод WriteError, описанный в разделе "Методы Write".
Если произошла прерывающая ошибка и выполнение функции продолжаться не
может, должен быть вызван метод ThrowTerminatingError. Кроме того для
прерывающих ошибок можно использовать инструкцию Throw, а для
непрерывающих - командлет Write-Error.
Дополнительные сведения см. в разделе System.Management.Automation
.Cmdlet. ThrowTerminatingError библиотеки MSDN по адресу
https://go.microsoft.com/fwlink/?LinkId=142144.
Методы Write
Чтобы возвращать выходные данные различных типов, функция может
вызывать следующие методы. Обратите внимание, что не все
выходные данные передаются следующей команде в конвейере. Кроме
того, можно использовать различные командлеты Write, например
Write-Error.
WriteCommandDetail
Дополнительные сведения о методе WriteCommandDetails см. в разделе
System.Management.Automation.Cmdlet.WriteCommandDetail библиотеки
MSDN по адресу https://go.microsoft.com/fwlink/?LinkId=142155.
WriteDebug
В функции используется вызов метода WriteDebug, чтобы предоставить
сведения, которые могут помочь при устранении неполадок в функции.
Этот метод выводит для пользователя сообщение отладки. Дополнительные
сведения см. в разделе System.Management.Automation.Cmdlet.WriteDebug
библиотеки MSDN по адресу https://go.microsoft.com/fwlink/?LinkId=142156.
WriteError
Функции должны вызывать этот метод, когда возникают непрерывающие ошибки,
а функция должна продолжать обработку записей. Дополнительные сведения см.
в разделе System.Management.Automation.Cmdlet.WriteError библиотеки MSDN
по адресу https://go.microsoft.com/fwlink/?LinkId=142157.
Примечание. Если произошла прерывающая ошибка, функция должна
вызвать метод ThrowTerminatingError.
WriteObject
Этот метод позволяет функции передать объект следующей команде в
конвейере. В большинстве случаев именно этот метод следует использовать
в ситуациях, когда функция должна возвращать данные. Дополнительные
сведения см. в разделе System.Management.Automation.PSCmdlet.WriteObject
библиотеки MSDN по адресу https://go.microsoft.com/fwlink/?LinkId=142158.
WriteProgress
Для функций, которые выполняются в течение длительного времени,
вызов функцией метода WriteProgress позволяет отображать
сведения о ходе ее выполнения. Например, можно отображать
процент выполнения. Дополнительные сведения см. в разделе
System.Management.Automation.PSCmdlet.WriteProgress библиотеки
MSDN по адресу https://go.microsoft.com/fwlink/?LinkId=142160.
WriteVerbose
Чтобы предоставить подробные сведения о действиях функции,
функция может вызывать метод WriteVerbose, и будут отображаться
подробные сообщения для пользователя. По умолчанию подробные
сообщения не отображаются. Дополнительные сведения см. в разделе
System.Management.Automation.PSCmdlet.WriteVerbose библиотеки MSDN
по адресу https://go.microsoft.com/fwlink/?LinkId=142162.
WriteWarning
Чтобы предоставить сведения об условиях, которые могут вызвать
появление непредсказуемых результатов, функция может вызывать метод
WriteWarning, и будут отображаться предупреждения для пользователя.
По умолчанию предупреждения не отображаются.Дополнительные сведения см.
в разделе System.Management.Automation.PSCmdlet.WriteWarning библиотеки
MSDN по адресу https://go.microsoft.com/fwlink/?LinkId=142164.
Примечание. Для отображения предупреждений также можно настроить
переменную WarningPreference или использовать параметры
командной строки Verbose и Debug.
Другие методы и свойства
Дополнительные сведения о других методах и свойствах, которые
доступные через переменную $PSCmdlet, см. в разделе System.Management.
Automation.PSCmdlet библиотеки MSDN по адресу
https://go.microsoft.com/fwlink/?LinkId=142139.
Например, свойство ParameterSetName позволяет определить
используемый набор параметров. Наборы параметров дают возможность
создавать функции, выполняющие различные задачи в зависимости от
параметров, задаваемых при запуске таких функций.
СМ. ТАКЖЕ
about_Functions_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters