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

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 функции . 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 блок не выполняется.
    • Блоки begin, endи clean по-прежнему выполняются.

Важно!

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

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