about_Parameters

  • Artykuł

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 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 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 Get-Help Parametr 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ść, 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 poleceń 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 parametrów Get-Help Pełne, Parametr lub Online polecenia cmdlet, Get-Help wyświetla tabelę atrybutów parametrów ze szczegółowymi informacjami na temat parametru.

Te informacje zawierają szczegółowe informacje, które należy wiedzieć, aby użyć parametru . Na przykład temat pomocy dla Get-ChildItem polecenia cmdlet zawiera następujące szczegóły dotyczące 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ę parametrów, 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 używające 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 nieujemną liczbę całkowitą, nazwa parametru nie jest wymagana. Ten typ parametru jest określany jako parametr pozycyjny, a liczba wskazuje położenie, w którym 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 polecenie Get-ChildItem cmdlet ma parametry Path (Ścieżka) i Exclude (Wyklucz). Ustawienie Position ścieżki to 0, co oznacza, że jest to parametr pozycyjny. Ustawienie PositionWykluczanie ma 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 należy uwzględnić inny parametr pozycyjny bez uwzględniania nazwy parametru Position , ten parametr musi zostać umieszczony w kolejności określonej przez ustawienie.

Typ parametru

To ustawienie określa typ programu Microsoft .NET Framework wartości parametru. Jeśli na przykład typ ma wartość Int32, wartość parametru musi być liczbą całkowitą. Jeśli typ to ciąg, 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óra zostanie założona przez parametr, jeśli nie zostanie podana żadna inna wartość. Na przykład wartość domyślna parametru Path jest często bieżącym katalogem. 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 żadnego 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-Service Name 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 korzystanie z bloków skryptów powiązanych z opóźnieniem w parametrze.

Blok skryptu powiązania opóźnienia jest uruchamiany automatycznie podczas parametruBinding. 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ływanego.

Więcej informacji o blokach 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ć symbole 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żywać z dowolnym poleceniem cmdlet. Aby uzyskać więcej informacji na temat typowych parametrów, zobacz about_CommonParameters.

Zobacz też