РАЗДЕЛ
    about_Functions_Advanced_Parameters

КРАТКОЕ ОПИСАНИЕ
    Описывает, как добавлять статические и динамические параметры в функции, 
    в которых объявлен атрибут CmdletBinding.

ПОЛНОЕ ОПИСАНИЕ
    При написании функций можно объявлять собственные параметры, а 
    также можно писать функции, которые могут обращаться к общим 
    параметрам, которые доступны скомпилированными командлетам. 
    Дополнительные сведения об общих параметрах Windows PowerShell 
    см. в разделе about_CommonParameters.

Статические параметры
    В следующем примере показано объявление параметра, в котором 
    определяется параметр ComputerName. Этот параметр обладает следующими 
    характеристиками:

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

        Param
          (
            [parameter(Mandatory=$true,
            ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          ) 
  

    Единственным обязательным атрибутом, который необходимо 
    использовать при объявлении параметра, является атрибут 
    Parameter. Но можно также объявить атрибут Alias и несколько 
    аргументов проверки. Количество атрибутов, которые можно включить в 
    объявление параметра, не ограничено.


  Атрибут Parameter

      Атрибут Parameter служит для объявления параметра функции.
      У этого атрибута есть следующие именованные аргументы, которые 
      служат для определения характеристик параметра, например 
      обязательности параметра.


    Именованный аргумент Mandatory

        Аргумент Mandatory указывает, что при запуске функции 
        параметр является обязательным. Если этот аргумент не указан, 
        параметр является необязательным. В следующем примере показано 
        объявление параметра, который обязательно указывать при запуске функции.

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            $ComputerName
          ) 


    Именованный аргумент Position

        Аргумент Position задает позицию параметра. Если этот аргумент не 
        указан, при задании параметра необходимо в явном виде указывать имя или 
        псевдоним параметра. Кроме того, если ни у одного из параметров 
        функции нет позиции, среда выполнения Windows PowerShell назначает 
        позиции для каждого из параметров на основании порядка, в котором 
        происходит получение параметров. 

        В следующем примере показано объявление параметра, значение 
        которого должно указываться в качестве первого аргумента при 
        вызове командлета. Обратите внимание, что эту функцию можно 
        запускать как с указанием имени параметра, так и без него.

        Param
          (
            [parameter(Position=0)]
            [String[]]
            $ComputerName
          ) 


    Именованный аргумент ParameterSetName

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

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")] [String[]]
            $ComputerName
          ) 

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="User")] [String[]]
            $UserName
          ) 

        Дополнительные сведения о наборах параметров см. в разделе 
        "Наборы параметров командлетов" библиотеки MSDN по адресу 
        https://go.microsoft.com/fwlink/?LinkId=142183.


    Именованный аргумент ValueFromPipeline

        Аргумент ValueFromPipeline определяет, что параметр принимает 
        входные данные из объекта конвейера. Этот аргумент следует 
        указывать, если командлет обращается ко всему объекту, а не 
        только к свойству объекта. В следующем примере показано объявление 
        обязательного параметра ComputerName, который принимает входной 
        объект, которые передается функции из конвейера.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipeline=$true)] [String[]]
            $ComputerName
          ) 


    Именованный аргумент ValueFromPipelineByPropertyName

        Аргумент valueFromPipelineByPropertyName определяет, что параметр 
        принимает входные данные из свойства объекта конвейера. Этот атрибут 
        следует указывать, если выполняются следующие условия:

            - параметр используется для доступа к объекту конвейера;

            - имя свойства совпадает с именем параметра или псевдоним 
              свойства совпадает с псевдонимом параметра.

        Например, если у функции есть параметр ComputerName, а у объекта 
        конвейера есть свойство ComputerName, значение свойства ComputerName 
        будет присвоено параметру ComputerName функции.

        В следующем примере показано объявление параметра 
        ComputerName, который принимает входные данные из свойства 
        ComputerName входного объекта, передаваемого командлету.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipelineByPropertyName=$true)] [String[]]
            $ComputerName
          ) 


    Именованный аргумент ValueFromRemainingArguments

        Аргумент ValueFromRemainingArguments определяет, что параметр 
        принимает все оставшиеся аргументы, которые не привязаны к 
        параметрам функции. В следующем примере показано объявление 
        параметра ComputerName, который принимает все оставшиеся аргументы 
        входного объекта, передаваемого функции.

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromRemainingArguments=$true)] [String[]]
            $ComputerName
          ) 


    Именованный аргумент HelpMessage

        Аргумент HelpMessage задает сообщение, которое содержит 
        краткое описание параметра. В следующем примере показано 
        объявление параметра, в котором определяется описание параметра.

        Param
          (
            [parameter(Mandatory=$true,
                      HelpMessage="An array of computer names.")] 
            [String[]]
            $ComputerName
          ) 


  Атрибут Alias

      Атрибут Alias задает другое имя параметра. Для параметра можно 
      определить произвольное число псевдонимов. В следующем примере 
      показано объявление обязательного параметра, в котором для параметра 
      ComputerName определен псевдоним CN.

        Param
          (
            [parameter(Mandatory=$true)]
            [alias("CN")]
            [String[]]
            $ComputerName
          ) 


  Атрибуты проверки параметров

      Эти атрибуты определяют, каким образом среда выполнения Windows 
      PowerShell проверяет аргументы расширенных функций.


    Атрибут проверки AllowNull

       Атрибут AllowNull позволяет устанавливать аргумент обязательного 
       параметра командлета равным Null. В следующем примере параметр 
       ComputerName может содержать значение Null, даже если параметр 
       является обязательным. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String]
            [AllowNull()]
            $ComputerName
          ) 


    Атрибут проверки AllowEmptyString

        Атрибут AllowEmptyString позволяет задавать в качестве аргумента 
        обязательного параметра командлета пустую строку. В следующем примере 
        параметр ComputerName может содержать пустую строку (""), даже если 
        параметр является обязательным. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String]
            [AllowEmptyString()]
            $ComputerName
          ) 


    Атрибут проверки AllowEmptyCollection

        Атрибут AllowEmptyCollection позволяет задавать в качестве 
        аргумента обязательного параметра командлета пустую коллекцию. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [AllowEmptyCollection()]
            $ComputerName
          ) 


    Атрибут проверки ValidateCount

        Атрибут ValidateCount задает минимальное и максимальное число 
        аргументов, которые может принимать параметр. Среда выполнения Windows 
        PowerShell создает ошибку, если число аргументов выходит за эти пределы. 
        В следующем примере у параметра ComputerName может быть от одного до 
        пяти аргументов. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateCount(1,5)]
            $ComputerName
          ) 


    Атрибут проверки ValidateLength

        Атрибут ValidateLength задает минимальную и максимальную 
        длину аргумента параметра. Среда выполнения Windows 
        PowerShell создает ошибку, если длина аргумента параметра 
        выходит за эти пределы.
        В следующем примере задаются имена компьютеров, длина которых 
        должна лежать в интервале от 1 до 10 знаков. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateLength(1,10)]
            $ComputerName
          ) 


    Атрибут проверки ValidatePattern

        Атрибут ValidatePattern задает регулярное выражение, которое 
        проверяет шаблон аргумента параметра. Среда выполнения Windows 
        PowerShell создает ошибку, если аргумент параметра не соответствует 
        этому шаблону. В следующем примере аргументом параметра должно быть 
        четырехзначное число, каждый разряд которого может содержать число от 
        0 до 9. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")] 
            $ComputerName
          ) 


    Атрибут проверки ValidateRange

        Атрибут ValidateRange задает минимальное и максимальное значение 
        аргумента параметра. Среда выполнения Windows PowerShell создает 
        ошибку, если аргумент параметра выходит за эти пределы. В следующем 
        примере аргумент параметра не может быть меньше 0 или больше 10. 


        Param
          (
            [parameter(Mandatory=$true)]
            [Int[]]
            [ValidateRange(0,10)]
            $Count
          ) 


    Атрибут проверки ValidateScript

        Атрибут ValidateScript задает скрипт, который используется 
        для проверки аргумента параметра. Среда выполнения Windows 
        PowerShell создает ошибку, если результатом выполнения 
        скрипта является значение false или если скрипт создает 
        исключение. В следующем примере значение параметра Count 
        должно быть менее 4.

        Param
          (
            [parameter()]
            [Int]
            [ValidateScript({$_ -lt 4})]
            $Count
          ) 


    Атрибут ValidateSet

        Атрибут ValidateSet задает набор допустимых значений аргумента 
        параметра.. Среда выполнения Windows PowerShell создает ошибку, если 
        аргумент параметра не совпадает ни с одним из значений в наборе.
        В следующем примере аргумент параметра может содержать только 
        имена Steve, Mary и Carl. 

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateRange("Steve", "Mary", "Carl")] 
            $UserName
          ) 


    Атрибут проверки ValidateNotNull


        Атрибут ValidateNotNull определяет, что аргумент параметра не 
        может иметь значение Null. Среда выполнения Windows 
        PowerShell создает ошибку, если параметр имеет значение Null.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateNotNull()]
            $UserName
          ) 


    Атрибут проверки ValidateNotNullOrEmpty

        Атрибут ValidateNotNullOrEmpty определяет, что аргумент 
        параметра не может иметь значение Null и не может быть 
        пустым. Среда выполнения Windows PowerShell создает ошибку, если 
        параметр задан, но имеет значение Null, пустой строки или пустого 
        массива.  

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            [ValidateNotNullOrEmpty()]
            $UserName
          ) 

Динамические параметры

    Динамические параметры — это параметры командлета, функции или скрипта, 
    доступные только при определенных условиях.  

    Например, у некоторых командлетов поставщика могут быть параметры, 
    доступные только при использовании командлета в пути поставщика. 
    Одним из динамических параметров является параметр Encoding 
    командлета Set-Item, который доступен только при использовании командлета 
    Set-Item в пути поставщика FileSystem. 

    Для создания динамического параметра функции или скрипта 
    используйте ключевое слово DynamicParam. 

    Синтаксис выглядит следующим образом/ 

    DynamicParam {<список_инструкций>}  

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

    Используйте командлет New-Object для создания объекта 
    System.Management.Automation.RuntimeDefinedParameter, представляющего 
    параметр и задающего его имя.  

    Также можно использовать команду New-Object для создания объекта 
    System.Management.Automation.ParameterAttribute, представляющего атрибуты 
    параметра (например, Mandatory, Position или ValueFromPipeline) 
    или его набор параметров. 

    В следующем примере показана функция со стандартными параметрами Name и 
    Path, а также с дополнительным динамическим параметром DP1. Параметр DP1 
    находится в наборе параметров PSet1 и принадлежит к типу Int32. 
    Параметр DP1 доступен в функции Sample только в том случае, если 
    в значении параметра Path содержится строка "HKLM:", указывающая 
    на использование командлета на диске реестра HKEY_LOCAL_MACHINE. 
     
      
        function Sample { 
          Param ([String]$Name, [String]$Path) 
      
          DynamicParam 
          { 
            if ($path -match "*HKLM*:") 
            { 
              $dynParam1 = new-object  
                System.Management.Automation.RuntimeDefinedParameter("dp1", 
                [Int32], $attributeCollection) 
      
              $attributes = new-object System.Management.Automation.ParameterAttribute 
              $attributes.ParameterSetName = 'pset1' 
              $attributes.Mandatory = $false 
      
              $attributeCollection = new-object  
                -Type System.Collections.ObjectModel.Collection``1[System.Attribute] 
              $attributeCollection.Add($attributes) 
     
              $paramDictionary = new-object  
                System.Management.Automation.RuntimeDefinedParameterDictionary 
              $paramDictionary.Add("dp1", $dynParam1) 
             
              return $paramDictionary 
            } End if 
          } 
        }   
      
    Дополнительные сведения см. в разделе "Класс RuntimeDefinedParameter" 
    библиотеки MSDN (Microsoft Developer Network) 
    по адресу https://go.microsoft.com/fwlink/?LinkID=145130.         


СМ. ТАКЖЕ
    about_Advanced Functions
    about_Functions_Advanced_Methods  
    about_Functions_CmdletBindingAttribute




Содержание