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, polega na parametrach, aby umożliwić użytkownikom wybieranie opcji lub podawanie danych wejściowych. Parametry są zgodne z nazwą polecenia i mają następujący formularz:

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

Nazwa parametru jest poprzedzona łącznikiem (-), który sygnalizuje programOwi PowerShell, że słowo 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 Get-Help 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 w poleceniu.

Możesz również użyć parametru parametru Get-Help polecenia cmdlet, aby znaleźć informacje o określonym parametrze. Możesz też użyć parametru Parametr z wartością symbolu wieloznakowego ( * ), 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ą, czyli wartość używaną lub zakładaną, gdy parametr nie jest określony w poleceniu.

Na przykład domyślną wartością parametru ComputerName wielu poleceń cmdlet jest nazwa komputera lokalnego. W rezultacie 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

W przypadku korzystania z parametrów Pełny, Parametr lub Online polecenia cmdlet Get-Help wyświetla tabelę atrybutów Get-Help parametrów ze szczegółowymi informacjami o parametrze.

Te informacje zawierają szczegółowe informacje potrzebne do użycia parametru. Na przykład temat pomocy dla polecenia cmdlet zawiera następujące szczegóły dotyczące parametru 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

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

Wymagany parametr

To ustawienie wskazuje, czy parametr jest obowiązkowy, czyli czy wszystkie polecenia korzystające z tego polecenia cmdlet muszą zawierać ten parametr. Gdy wartość ma wartość True i brakuje parametru w poleceniu, program PowerShell wyświetli monit o podanie wartości parametru.

Położenie parametru

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

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

Oznacza to, że ścieżka nie wymaga nazwy parametru, ale jego wartość parametru musi być pierwszą lub tylko nienazwaną wartością parametru w poleceniu. Jednak ponieważ parametr Exclude jest nazwanym parametrem, można umieścić go w dowolnej pozycji w poleceniu.

W wyniku Position ustawień 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 dołączyć inny parametr pozycyjny bez uwzględniania nazwy parametru, ten parametr musi zostać umieszczony w kolejności określonej przez Position ustawienie.

Typ parametru

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

Wartość domyślna

To ustawienie określa wartość, którą parametr przyjmie, jeśli nie zostanie podana żadna inna wartość. 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 ma wartości domyślnej, 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. Gdy parametr akceptuje wiele wartości, można wpisać listę rozdzielaną przecinkami jako wartość parametru w poleceniu lub zapisać listę rozdzielaną przecinkami (tablicę) w zmiennej, a następnie określić zmienną jako wartość parametru.

Na przykład parametr Get-ServiceName polecenia cmdlet akceptuje wiele wartości. Oba następujące 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 (|), aby wysłać wartość 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 (by Value)", program PowerShell próbuje skojarzyć wszystkie wartości potokowe z tym parametrem, zanim podejmie próbę zinterpretowania polecenia przy użyciu innych metod.

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 przekazać 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 (by Value) lub (by PropertyName) umożliwia używanie bloków skryptów powiązanych z opóźnieniem w parametrze.

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

Więcej informacji na temat bloków skryptów powiązanych z opóźnieniem można znaleźć tutaj about_Script_Blocks.md

Akceptuje symbole wieloznaczne

To ustawienie wskazuje, czy wartość parametru może zawierać znaki wieloznaczne, aby wartość parametru mogła być dopasowana 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ż