about_Parameters

Krótki opis

Opisuje sposób pracy z parametrami poleceń w programie PowerShell.

Długi opis

Większość poleceń programu PowerShell, takich jak polecenia cmdlet, funkcje i skrypty, korzysta z parametrów, aby umożliwić użytkownikom wybieranie opcji lub wprowadzanie danych wejściowych. Parametry są zgodne z nazwą polecenia i mają następującą postać:

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

Nazwa parametru jest poprzedzona łącznikiem ( ), który sygnalizuje programowi PowerShell, że wyraz następujący po łączniku - jest nazwą parametru. Nazwa parametru i wartość mogą być oddzielone spacją lub dwukropkiem. Niektóre parametry nie wymagają ani nie akceptują wartości parametru. Inne parametry wymagają wartości, ale nie wymagają nazwy parametru w poleceniu.

Typ parametrów i wymagania dotyczące tych parametrów różnią się. Aby znaleźć informacje o parametrach polecenia, użyj Get-Help polecenia cmdlet . Aby na przykład znaleźć informacje o parametrach Get-ChildItem polecenia cmdlet, wpisz:

Get-Help Get-ChildItem

Aby znaleźć informacje o parametrach skryptu, użyj pełnej ścieżki do pliku skryptu. Na przykład:

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

Polecenie cmdlet zwraca różne szczegóły dotyczące polecenia, w tym opis, składnię polecenia, informacje o parametrach i przykłady pokazujące, jak używać parametrów Get-Help w poleceniu.

Można również użyć parametru polecenia cmdlet , aby Get-Help znaleźć informacje o określonym parametrze. Można też użyć parametru Parameter z wartością symbolu wieloznacznego ( ), aby znaleźć informacje * o wszystkich parametrach polecenia. Na przykład następujące polecenie pobiera informacje o wszystkich parametrach Get-Member polecenia cmdlet:

Get-Help Get-Member -Parameter *

Domyślne wartości parametrów

Parametry opcjonalne mają wartość domyślną, która jest wartością, która jest używana lub zakładana, gdy parametr nie jest określony w poleceniu .

Na przykład wartość domyślna parametru ComputerName wielu polecenia cmdlet to nazwa komputera lokalnego. W związku z tym nazwa komputera lokalnego jest używana w poleceniu, chyba że określono parametr ComputerName.

Aby znaleźć domyślną wartość parametru, zobacz temat pomocy dla polecenia cmdlet . Opis parametru powinien zawierać wartość domyślną.

Można również ustawić niestandardową wartość domyślną dla dowolnego parametru polecenia cmdlet lub funkcji zaawansowanej. Aby uzyskać informacje na temat ustawiania niestandardowych wartości domyślnych, zobacz about_Parameters_Default_Values.

Tabela atrybutów parametrów

Jeśli używasz pełnej, parametru lub online parametrów polecenia cmdlet, wyświetla tabelę atrybutów parametrów ze szczegółowymi informacjami Get-Help Get-Help o parametrze.

Te informacje zawierają szczegółowe informacje, które należy znać, aby użyć parametru . Na przykład temat pomocy dla polecenia cmdlet zawiera następujące szczegóły Get-ChildItem dotyczące jego parametru 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

Informacje o parametrach obejmują składnię parametru, opis parametru i atrybuty parametru. W poniższych sekcjach opisano atrybuty parametru.

Wymagany parametr

To ustawienie wskazuje, czy parametr jest obowiązkowy, czyli czy wszystkie polecenia, które używają tego polecenia cmdlet, muszą zawierać ten parametr. Jeśli w poleceniu brakuje wartości True i brakuje parametru , program PowerShell wyświetli monit o wartość parametru .

Położenie parametru

Jeśli ustawienie Position jest ustawione na nieujemną liczbę całkowitą, nazwa parametru nie jest wymagana. Ten typ parametru jest określany jako parametr pozytowy, a liczba wskazuje pozycję, w której parametr musi występować w odniesieniu do innych parametrów pozyacyjnych. Nazwany parametr może być wymieniony w dowolnej pozycji po nazwie polecenia cmdlet. Jeśli dołączysz nazwę parametru dla parametru pozyczkowego, parametr może być wymieniony w dowolnej pozycji po nazwie polecenia cmdlet.

Na przykład polecenie Get-ChildItem cmdlet ma parametry Ścieżka i Wyklucz. Ustawienie Position dla ścieżki jest 0, co oznacza, że jest to parametr pozycytny. Ustawienie Position wykluczania ma nazwę.

Oznacza to, że ścieżka nie wymaga nazwy parametru, ale jego wartość parametru musi być pierwszą lub jedyną nienazwane wartością parametru w poleceniu. Jednak ponieważ exclude parametr jest nazwany parametr, można umieścić go w dowolnej pozycji w poleceniu.

W wyniku ustawienia Position tych dwóch parametrów można użyć dowolnego z następujących poleceń:

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

Jeśli chcesz uwzględnić inny parametr pozytowy bez uwzględnienia nazwy parametru, ten parametr musi być umieszczony w kolejności określonej przez Position ustawienie.

Typ parametru

To ustawienie określa typ .NET Framework Microsoft dla wartości parametru. Jeśli na przykład typ to Int32, wartość parametru musi być liczbą całkowitą. Jeśli typem jest ciąg, wartość parametru musi być ciągiem znaków. Jeśli ciąg zawiera spacje, wartość musi być ujęta w znaki cudzysłowu lub spacje muszą być poprzedzone znakiem ucieczki ( ` ).

Wartość domyślna

To ustawienie określa wartość, która zostanie założona przez parametr, jeśli nie podano żadnej innej wartości. Na przykład domyślną wartością parametru Path jest często bieżący katalog. Wymagane parametry nigdy nie mają wartości domyślnej. W przypadku wielu parametrów opcjonalnych nie istnieje wartość domyślna, ponieważ parametr nie ma wpływu, jeśli nie jest używany.

Akceptuje wiele wartości

To ustawienie wskazuje, czy parametr akceptuje wiele wartości parametrów. Jeśli parametr akceptuje wiele wartości, można wpisać listę rozdzielaną przecinkami jako wartość parametru w poleceniu lub zapisać listę rozdzieloną przecinkami (tablicę) w zmiennej, a następnie określić zmienną jako wartość parametru.

Na przykład nazwa parametru Get-Service polecenia cmdlet akceptuje wiele wartości. Oba poniższe polecenia są prawidłowe:

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

Akceptuje dane wejściowe potoku

To ustawienie wskazuje, czy można użyć operatora potoku ( ) do | wysłania wartości do parametru.

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.

Gdy parametr ma wartość "True (według wartości)", program PowerShell próbuje skojarzyć wszystkie wartości potokowe z tym parametrem, zanim spróbuje zinterpretować polecenie innymi metodami.

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.

Można na przykład potokować wartość do parametru Name tylko wtedy, gdy wartość ma właściwość o nazwie Name.

Uwaga

Typowany parametr, który akceptuje dane wejściowe potoku ( ) lub ( ), umożliwia korzystanie z bloków skryptu powiązania opóźnienia by Value by PropertyName w parametrze.

Blok skryptu powiązania opóźnienia jest uruchamiany automatycznie podczas powiązania parametru. Wynik jest powiązany z parametrem . Powiązanie opóźnienia nie działa w przypadku parametrów zdefiniowanych jako typ lub , blok skryptu jest przekazywany bez ScriptBlock System.Object wywoływania.

Informacje o blokach skryptów powiązania opóźnienia można znaleźć tutaj about_Script_Blocks.md

Akceptuje symbole wieloznaczne

To ustawienie wskazuje, czy wartość parametru może zawierać symbole wieloznaczne, aby można było dopasować wartość parametru do więcej niż jednego istniejącego elementu w kontenerze docelowym.

Typowe parametry

Typowe parametry to parametry, których można użyć z dowolnym poleceniem cmdlet. Aby uzyskać więcej informacji na temat typowych parametrów, zobacz about_CommonParameters.

Zobacz też

about_Command_syntax

about_Comment_Based_Help

about_Functions_Advanced

about_Parameters_Default_Values

about_Pipelines

about_Wildcards