about_Parameters

Статья
04/13/2023

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

Описывает работу с параметрами команд в PowerShell.

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

Большинство команд PowerShell, таких как командлеты, функции и скрипты, полагаются на параметры, чтобы разрешить пользователям выбирать параметры или предоставлять входные данные. Параметры следуют имени команды и имеют следующую форму:

-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>

Имя параметра предшествует дефису (-), которое сигнализирует PowerShell о том, что слово, следующее за дефисом, является именем параметра. Имя и значение параметра можно разделить пробелом или символом двоеточия. Некоторые параметры не требуют или принимают значение параметра. Другие параметры требуют значения, но не требуют имени параметра в команде.

Тип параметров и требования для этих параметров зависят. Чтобы найти сведения о параметрах команды, используйте Get-Help командлет. Например, чтобы найти сведения о параметрах командлета Get-ChildItem , введите:

Get-Help Get-ChildItem

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

Get-Help $HOME\Documents\Scripts\Get-Function.ps1

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

Параметр параметра командлета можно также использовать для поиска сведений Get-Help о конкретном параметре. Кроме того, можно использовать параметр параметра с значением wild карта ( * ) для поиска сведений обо всех параметрах команды. Например, следующая команда получает сведения обо всех параметрах командлета Get-Member :

Get-Help Get-Member -Parameter *

Значения параметров по умолчанию

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

Например, значение по умолчанию параметра ComputerName многих командлетов — это имя локального компьютера. В результате имя локального компьютера используется в команде, если параметр ComputerName не указан.

Чтобы найти значение параметра по умолчанию, см. раздел справки для командлета. Описание параметра должно содержать значение по умолчанию.

Можно также задать настраиваемое значение по умолчанию для любого параметра командлета или расширенной функции. Сведения о настройке пользовательских значений по умолчанию см. в about_Parameters_Default_Values.

Таблица атрибутов параметров

При использовании параметров Get-Help Full, Parameter или Online командлета Get-Help отображается таблица атрибутов параметров с подробными сведениями о параметре.

Эти сведения содержат сведения, необходимые для использования параметра. Например, раздел справки для командлета содержит следующие сведения о параметре Get-ChildItem Path:

-Path <string[]>
    Specifies a path of one or more locations. Wildcard characters are
    permitted. The default location is the current directory (.).

Required?                    false
Position?                    0
Default value                Current directory
Accept pipeline input?       true (ByValue, ByPropertyName)
Accept wildcard characters?  true

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

Обязательный параметр

Этот параметр указывает, является ли параметр обязательным, то есть, должны ли все команды, использующие этот командлет, включать этот параметр. Если значение равно True , а параметр отсутствует в команде, PowerShell запрашивает значение параметра.

Позиция параметра

Position Если для параметра задано неотрицательное целое число, имя параметра не обязательно. Этот тип параметра называется позициальным параметром, а число указывает позицию, в которой параметр должен отображаться относительно других позиционных параметров. Именованный параметр можно указать в любой позиции после имени командлета. Если указать имя параметра для позиционного параметра, этот параметр можно указать в любой позиции после имени командлета.

Например, Get-ChildItem командлет имеет параметры Path и Exclude. Значение Positionpath равно 0, что означает, что это позиционный параметр. Параметр Position исключения называется.

Это означает, что Путь не требует имени параметра, но его значение параметра должно быть первым или единственным значением неназванного параметра в команде. Однако, поскольку параметр Exclude является именованным параметром, его можно поместить в любую позицию в команде.

В результате Position параметров для этих двух параметров можно использовать любую из следующих команд:

Get-ChildItem -Path c:\techdocs -Exclude *.ppt
Get-ChildItem c:\techdocs -Exclude *.ppt
Get-ChildItem -Exclude *.ppt -Path c:\techdocs
Get-ChildItem -Exclude *.ppt c:\techdocs

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

Тип параметра

Этот параметр задает тип параметра microsoft платформа .NET Framework значения параметра. Например, если тип имеет значение Int32, значение параметра должно быть целым числом. Если тип является строкой, значение параметра должно быть символьной строкой. Если строка содержит пробелы, значение должно быть заключено в кавычки или пробелы должны предшествовать escape-символу (`).

Значение по умолчанию

Этот параметр указывает значение, которое параметр будет предполагать, если другое значение не указано. Например, значение по умолчанию параметра Path часто является текущим каталогом. Обязательные параметры никогда не имеют значения по умолчанию. Для многих необязательных параметров значение по умолчанию отсутствует, так как параметр не действует, если он не используется.

Принимает несколько значений

Этот параметр указывает, принимает ли параметр несколько значений параметров. Если параметр принимает несколько значений, можно ввести разделенный запятыми список в качестве значения параметра в команде или сохранить разделенный запятыми список (массив) в переменной, а затем указать переменную в качестве значения параметра.

Например, параметр Name командлета принимает несколько значений Get-Service . Следующие команды являются допустимыми:

Get-Service -Name winrm, netlogon

$s = "winrm", "netlogon"
Get-Service -Name $s

Принимает входные данные конвейера

Этот параметр указывает, можно ли использовать оператор конвейера (|) для отправки значения параметру.

Value                    Description
-----                    -----------
False                    Indicates that you cannot pipe a value to the
                         parameter.

True (by Value)          Indicates that you can pipe any value to the
                         parameter, just so the value has the .NET
                         Framework type specified for the parameter or the
                         value can be converted to the specified .NET
                         Framework type.

Если параметр имеет значение True (по значению), PowerShell пытается связать все значения с этим параметром, прежде чем пытаться интерпретировать команду другими методами.

True (by Property Name)  Indicates that you can pipe a value to the
                         parameter, but the .NET Framework type of the
                         parameter must include a property with the same
                         name as the parameter.

Например, можно передать значение параметру Name только в том случае, если значение имеет свойство с именем Name.

Примечание.

Типизированный параметр, принимаюющий входные данные конвейера (by Value) или (by PropertyName) позволяет использовать блоки скриптов задержки привязывания к параметру.

Блок скрипта отложенной привязки выполняется автоматически во время ParameterBinding. Результат привязан к параметру. Привязка задержки не работает для параметров, определенных как тип ScriptBlock или System.Objectблок скрипта передается без вызова.

Вы можете прочитать о блоках скриптов задержки привязки здесь about_Script_Blocks.md

Принимает символы wild карта

Этот параметр указывает, может ли значение параметра содержать дикие карта символы, чтобы значение параметра можно было сопоставить с несколькими существующими элементами в целевом контейнере.

Общие параметры

Общие параметры — это параметры, которые можно использовать с любым командлетом. Дополнительные сведения о распространенных параметрах см. в about_CommonParameters.