about_Functions_Advanced_Methods

  • Статья

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

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

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

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

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

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

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

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

Методы, описанные в этом разделе, называются методами обработки входных данных. Для функций эти три метода представлены блоками beginprocessфункции и end блоками функции. PowerShell 7.3 добавляет clean метод блочного процесса.

Вам не требуется использовать любой из этих блоков в функциях. Если вы не используете именованный блок, PowerShell помещает код в end блок функции. Однако если вы используете любой из этих именованных блоков или определите dynamicparam блок, необходимо поместить весь код в именованный блок.

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

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

Примечание.

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

begin

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

process

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

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

  • Вызов функции в начале или за пределами конвейера выполняет process блок один раз.
  • В конвейере process блок выполняется один раз для каждого входного объекта, достигающего функции.
  • Если входные данные конвейера, достигающие функции, пусты, process блок не выполняется.
    • endclean И блоки beginпо-прежнему выполняются.

Внимание

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

При создании функции, которая принимает входные данные конвейера и использует ее CmdletBinding, блок должен использовать переменную параметра, process определенную для входных данных конвейера $_$PSItem, а не для него. Например:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1,2,3,4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

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

clean

Блок clean был добавлен в PowerShell 7.3.

Блок clean — удобный способ очистки ресурсов, распределенных между блоками begin, process и end. Семантически он похож на блок finally, охватывающий все другие именованные блоки функции скрипта или командлета скрипта. Очистка ресурсов применяется в следующих сценариях:

  1. Когда выполнение конвейера завершается нормально без неустранимой ошибки.
  2. Когда выполнение конвейера прерывается из-за неустранимой ошибки.
  3. Если конвейер остановлен с помощью Select-Object -First.
  4. Если конвейер остановлен с помощью клавиш CTRL+C или команды StopProcessing().

Внимание

Добавление блока clean является критическим изменением. Поскольку clean анализируется как ключевое слово, пользователи не могут напрямую вызвать команду clean в качестве первой инструкции в блоке скрипта. Однако, скорее всего, это не проблема. Команда по-прежнему может вызываться с помощью оператора вызова (& clean).

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

ShouldProcess

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

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

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

ShouldContinue

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

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

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

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

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

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

WriteCommandDetail

Сведения о методе WriteCommandDetails см. в разделе System.Management.Automation.Командлет.WriteCommandDetail.

WriteDebug

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

WriteError

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

Примечание.

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

WriteObject

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

WriteProgres

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

WriteVerbose

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

WriteWarning

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

Примечание.

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

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

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

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

См. также