РАЗДЕЛ
    about_Functions_Advanced_Methods

КРАТКОЕ ОПИСАНИЕ
    Описывает, каким образом функции, имеющие атрибут CmdletBinding, могут 
    использовать методы и свойства, доступные скомпилированным командлетам.

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


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

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

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

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

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


    Все методы и свойства командлета PSCmdlet доступны расширенным 
    функциям. Дополнительные сведения об этих методах и свойствах см. 
    в разделе System.Management.Automation.PSCmdlet библиотеки MSDN 
    (Microsoft Developer Network) по адресу 
    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_Advanced
    about_Functions_CmdletBindingAttributes
    about_Functions_Advanced_Parameters




Содержание