about_Functions_Advanced_Methods

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

РАЗДЕЛ

about_Functions_Advanced_Methods

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

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

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

Функции, имеющие атрибут CmdletBinding, могут обращаться к некоторым методам и свойствам через переменную $pscmdlet. Эти методы включают следующие:

– методы обработки входных данных, используемые скомпилированными командлетами;

– методы ShouldProcess и ShouldContinue, используемые для получения реакции пользователя перед выполнением действия;

– метод ThrowTerminatingError для создания записей об ошибках;

– несколько методов Write, которые возвращают выходные данные различных типов.

Все методы и свойства класса PSCmdlet доступны расширенным функциям. Подробнее об этих методах и свойствах см. в разделе «System.Management.Automation.PSCmdlet» в библиотеке MSDN по адресу 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

about_Functions_Advanced

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute