Дополнительные методы функций

Статья
06/21/2023

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

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

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

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

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

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

Дополнительные сведения об атрибуте см. в CmdletBindingразделе about_Functions_CmdletBindingAttribute. Сведения о классе CmdletBindingAttribute см. в разделе System.Management.Automation.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 позволяет просмотреть используемый набор параметров. Наборы параметров позволяют создать функцию, которая выполняет различные задачи на основе параметров, указанных при выполнении функции.