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

about_Functions_Advanced_Methods

  • Статья

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

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

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

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

  • Методы обработки входных данных, скомпилированные командлеты, используют для выполнения своей работы.
  • Методы ShouldProcess и ShouldContinue , используемые для получения отзывов пользователей перед выполнением действия.
  • Метод ThrowTerminatingError для создания записей об ошибках.
  • Несколько Write методов, возвращающих различные типы выходных данных.

Все методы и свойства класса PSCmdlet доступны для расширенных функций. Дополнительные сведения см. в разделе System.Management.Automation.PSCmdlet.

Дополнительные сведения об атрибуте см. в CmdletBindingразделе about_Functions_CmdletBindingAttribute. Класс CmdletBindingAttribute см. в разделе System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Методы обработки входных данных

Методы, описанные в этом разделе, называются методами обработки входных данных. Для функций эти три метода представлены блоками Begin, Processи End функции . Вам не требуется использовать какие-либо из этих блоков в функциях.

Примечание

Эти блоки также доступны для функций, которые не используют CmdletBinding атрибут .

Начать

Этот блок используется для предоставления необязательной однократной предварительной обработки для функции. Среда выполнения PowerShell использует код в этом блоке один раз для каждого экземпляра функции в конвейере.

Процесс

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

Автоматическая переменная $_ или $PSItem содержит текущий объект в конвейере для использования в блоке Process . Автоматическая переменная $input содержит перечислитель, доступный только для функций и блоков скриптов. Дополнительные сведения см. в статье about_Automatic_Variables.

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

Важно!

Если параметр функции настроен на прием входных данных конвейера Process , а блок не определен, обработка записей по записям завершится ошибкой. В этом случае функция будет выполняться только один раз, независимо от входных данных.

Конец

Этот блок используется для предоставления необязательной одноразовой постобработки для функции.

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

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

Примечание

Begin Для использования блока или End необходимо определить все три блока. При использовании всех трех блоков весь код PowerShell должен находиться внутри одного из блоков.

Методы подтверждения

ShouldProcess

Этот метод вызывается для запроса подтверждения у пользователя до того, как функция выполнит действие, которое изменит систему. Функция может продолжаться на основе логического значения, возвращаемого методом . Этот метод может вызываться только из Process{} блока функции. Атрибут CmdletBinding также должен объявлять, что функция поддерживает ShouldProcess (как показано в предыдущем примере).

Дополнительные сведения об этом методе см. в разделе System.Management.Automation.Cmdlet.ShouldProcess.

Дополнительные сведения о том, как запросить подтверждение, см. в разделе Запрос подтверждения.

ShouldContinue

Этот метод вызывается для запроса второго сообщения подтверждения. Он должен вызываться, ShouldProcess когда метод возвращает $true. Дополнительные сведения об этом методе см. в разделе System.Management.Automation.Cmdlet.ShouldContinue.

Методы ошибок

Функции могут вызывать два разных метода при возникновении ошибок. При возникновении неустранимой ошибки функция должна вызвать WriteError метод , который описан в Write разделе methods. Если возникает неустранимая ошибка и функция не может продолжить работу, она должна вызвать ThrowTerminatingError метод . Можно также использовать инструкцию Throw для устранения ошибок и командлет Write-Error для неустранимых ошибок.

Дополнительные сведения см. в разделе System.Management.Automation.Cmdlet.ThrowTerminatingError.

Методы записи

Функция может вызывать следующие методы для возврата различных типов выходных данных. Обратите внимание, что не все выходные данные переходят к следующей команде в конвейере. Можно также использовать различные Write командлеты, например Write-Error.

WriteCommandDetail

Дополнительные сведения о методе см. в WriteCommandDetails разделе System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Чтобы предоставить сведения, которые можно использовать для устранения неполадок функции, вызовите WriteDebug метод . Метод WriteDebug отображает сообщения отладки для пользователя. Дополнительные сведения см. в разделе System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Функции должны вызывать этот метод при возникновении неустранимых ошибок, а функция предназначена для продолжения обработки записей. Дополнительные сведения см. в разделе System.Management.Automation.Cmdlet.WriteError.

Примечание

При возникновении неустранимой ошибки функция должна вызвать метод ThrowTerminatingError .

WriteObject

Метод WriteObject позволяет функции отправлять объект в следующую команду в конвейере. В большинстве случаев является методом, WriteObject используемым, когда функция возвращает данные. Дополнительные сведения см. в разделе System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

Для функций с действиями, которые выполняются долго, этот метод позволяет функции вызывать WriteProgress метод , чтобы отображались сведения о ходе выполнения. Например, можно отобразить процент завершения. Дополнительные сведения см. в разделе System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Чтобы предоставить подробные сведения о том, что делает функция, вызовите WriteVerbose метод для отображения подробных сообщений пользователю. По умолчанию подробные сообщения не отображаются. Дополнительные сведения см. в разделе System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Чтобы предоставить сведения об условиях, которые могут привести к непредвиденным результатам, вызовите функцию метода WriteWarning для отображения предупреждающих сообщений пользователю. По умолчанию отображаются предупреждающие сообщения. Дополнительные сведения см. в разделе System.Management.Automation.PSCmdlet.WriteWarning.

Примечание

Вы также можете отображать предупреждающие сообщения, настроив $WarningPreference переменную или используя параметры командной Verbose строки и Debug . Дополнительные сведения о переменной см. в $WarningPreferenceразделе about_Preference_Variables.

Другие методы и свойства

Сведения о других методах и свойствах, доступ к которым можно получить через переменную, см. в $PSCmdlet разделе System.Management.Automation.PSCmdlet.

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

См. также раздел