about_Command_Syntax

Artykuł
05/09/2024

Krótki opis

Opisuje diagramy składni używane w programie PowerShell.

Długi opis

Polecenia cmdlet Get-Help i Get-Command wyświetlają diagramy składni, aby ułatwić poprawne konstruowanie poleceń. W tym temacie wyjaśniono, jak interpretować diagramy składniowe.

DIAGRAMY SKŁADNIOWE

Każdy akapit na diagramie składni poleceń reprezentuje prawidłową formę polecenia.

Aby utworzyć polecenie, postępuj zgodnie z diagramem składni od lewej do prawej. Wybierz spośród opcjonalnych parametrów i podaj wartości dla symboli zastępczych.

Program PowerShell używa następującej notacji na potrzeby diagramów składniowych.

<command-name> -<Required Parameter Name> <Required Parameter Value>
[-<Optional Parameter Name> <Optional Parameter Value>]
[-<Optional Switch Parameters>]
[-<Optional Parameter Name>] <Required Parameter Value>

Poniżej przedstawiono składnię polecenia cmdlet New-Alias .

New-Alias [-Name] <string> [-Value] <string> [-Description <string>]
[-Force] [-Option {None | ReadOnly | Constant | Private | AllScope}]
[-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

Składnia jest kapitalizowana w celu czytelności, ale program PowerShell jest bez uwzględniania wielkości liter.

Diagram składniowy zawiera następujące elementy.

Nazwa polecenia

Polecenia zawsze zaczynają się od nazwy polecenia, takiej jak New-Alias. Wpisz nazwę polecenia lub jego alias, taki jak "gcm" dla Get-Commandpolecenia .

Parametry

Parametry polecenia to opcje określające, co robi polecenie. Niektóre parametry przyjmują wartość "value", która jest danymi wejściowymi użytkownika do polecenia.

Na przykład Get-Help polecenie ma parametr Name , który umożliwia określenie nazwy tematu, dla którego jest wyświetlana pomoc. Nazwa tematu jest wartością parametru Name .

W poleceniu programu PowerShell nazwy parametrów zawsze zaczynają się łącznikiem. Łącznik informuje program PowerShell, że element w poleceniu jest nazwą parametru.

Aby na przykład użyć parametru Name elementu New-Alias, wpisz następujące polecenie:

-Name

Parametry mogą być obowiązkowe lub opcjonalne. Na diagramie składni opcjonalne elementy są ujęte w nawiasy [ ].

Aby uzyskać więcej informacji na temat parametrów, zobacz about_Parameters.

Wartości parametrów

Wartość parametru to dane wejściowe, które przyjmuje parametr. Ponieważ Windows PowerShell opiera się na .NET Framework firmy Microsoft, wartości parametrów są reprezentowane na diagramie składniowym według typu platformy .NET.

Na przykład parametr Name parametru Get-Help przyjmuje wartość "Ciąg", która jest ciągiem tekstowym, takim jak jedno słowo lub wiele wyrazów ujęta w cudzysłów.

[-Name] <string>

Typ .NET wartości parametru jest ujęta w nawiasy kątowe < > , aby wskazać, że jest symbolem zastępczym wartości, a nie literałem wpisanym w poleceniu.

Aby użyć parametru, zastąp symbol zastępczy typu .NET obiektem o określonym typie platformy .NET.

Aby na przykład użyć parametru Name , wpisz ciąg "-Name", po którym następuje ciąg, taki jak:

-Name MyAlias

Parametry bez wartości

Niektóre parametry nie akceptują danych wejściowych, więc nie mają wartości parametru. Parametry bez wartości są nazywane "parametrami przełącznika", ponieważ działają jak przełączniki włączone/wyłączone. Należy je uwzględnić (włączone) lub pominąć (wyłączone) z polecenia.

Aby użyć parametru przełącznika, wystarczy wpisać nazwę parametru poprzedzoną łącznikiem.

Aby na przykład użyć parametru New-AliasWhatIf polecenia cmdlet, wpisz następujące polecenie:

-WhatIf

Zestawy parametrów

Parametry polecenia są wymienione w zestawach parametrów. Zestawy parametrów wyglądają jak akapity diagramu składniowego.

Polecenie New-Alias cmdlet ma jeden zestaw parametrów, ale wiele poleceń cmdlet ma wiele zestawów parametrów. Niektóre parametry polecenia cmdlet są unikatowe dla zestawu parametrów, a inne są wyświetlane w wielu zestawach parametrów. Każdy zestaw parametrów reprezentuje format prawidłowego polecenia. Zestaw parametrów zawiera tylko parametry, które mogą być używane razem w poleceniu. Jeśli nie można użyć parametrów w tym samym poleceniu, są one wyświetlane w oddzielnych zestawach parametrów.

Na przykład polecenie cmdlet Get-Random ma następujące zestawy parametrów:

Get-Random [[-Maximum] <Object>] [-Minimum <Object>] [-SetSeed <int>]
[<CommonParameters>]

Get-Random [-InputObject] <Object[]> [-Count <int>] [-SetSeed <int>]
[<CommonParameters>]

Pierwszy zestaw parametrów, który zwraca liczbę losową, ma parametry Minimum i Maksimum . Drugi zestaw parametrów, który zwraca losowo wybrany obiekt z zestawu obiektów, zawiera parametry InputObject i Count . Oba zestawy parametrów mają parametr SetSeed i typowe parametry.

Te zestawy parametrów wskazują, że można użyć parametrów InputObject i Count w tym samym poleceniu, ale nie można użyć parametrów Maksimum i Liczba w tym samym poleceniu.

Wskazujesz, który zestaw parametrów chcesz użyć przy użyciu parametrów w tym zestawie parametrów.

Jednak każde polecenie cmdlet ma również domyślny zestaw parametrów. Domyślny zestaw parametrów jest używany, gdy nie określasz parametrów unikatowych dla zestawu parametrów. Jeśli na przykład używasz Get-Random parametrów bez parametrów, Windows PowerShell zakłada, że używasz zestawu parametrów Liczba i zwraca liczbę losową.

W każdym zestawie parametrów parametry są wyświetlane w kolejności pozycji. Kolejność parametrów w poleceniu ma znaczenie tylko wtedy, gdy pominięto opcjonalne nazwy parametrów. Gdy nazwy parametrów zostaną pominięte, program PowerShell przypisuje wartości do parametrów według pozycji i typu. Aby uzyskać więcej informacji na temat pozycji parametru, zobacz about_Parameters.

Symbole na diagramach składniowych

Diagram składni zawiera nazwę polecenia, parametry polecenia i wartości parametrów. Używa również symboli, aby pokazać, jak utworzyć prawidłowe polecenie.

Diagramy składniowe używają następujących symboli:

Łącznik - wskazuje nazwę parametru. W poleceniu wpisz łącznik bezpośrednio przed nazwą parametru bez interweniujących spacji, jak pokazano na diagramie składniowym.

Aby na przykład użyć parametru Name , New-Aliaswpisz:
```
-Name
```
Nawiasy kątowe <> wskazują tekst zastępczy. Nie należy wpisywać nawiasów kątowych ani tekstu zastępczego w poleceniu. Zamiast tego zastąp go elementem, który opisuje.

Nawiasy kątowe służą do identyfikowania typu .NET wartości, którą przyjmuje parametr. Na przykład aby użyć parametru New-AliasName polecenia cmdlet, zastąp <string> ciąg ciągiem, który jest pojedynczym wyrazem lub grupą wyrazów, które są ujęte w cudzysłów.
Nawiasy kwadratowe [ ] wskazują elementy opcjonalne. Parametr i jego wartość mogą być opcjonalne lub nazwa wymaganego parametru może być opcjonalna.

Na przykład parametr Description i New-Alias jego wartość są ujęte w nawiasy, ponieważ są opcjonalne.
```
[-Description <string>]
```
Nawiasy kwadratowe wskazują również, że wartość <string> parametru Name jest wymagana, ale nazwa parametru "Name" jest opcjonalna.
```
[-Name] <string>
```
Prawy i lewy nawias [] dołączany do typu platformy .NET wskazuje, że parametr może akceptować jedną lub wiele wartości tego typu. Wprowadź wartości na liście rozdzielanej przecinkami.

Na przykład parametr New-AliasName polecenia cmdlet przyjmuje tylko jeden ciąg, ale parametr Namemetody Get-Process może przyjmować jeden lub wiele ciągów.
```
New-Alias [-Name] <string>

New-Alias -Name MyAlias
```
```
Get-Process [-Name] <string[]>

Get-Process -Name Explorer, Winlogon, Services
```
Nawiasy klamrowe {} wskazują "wyliczenie", czyli zestaw prawidłowych wartości dla parametru.

Wartości w nawiasach klamrowych są oddzielone pionowymi paskami |. Te paski wskazują wybór "wyłączny OR", co oznacza, że można wybrać tylko jedną wartość z zestawu wartości wymienionych wewnątrz nawiasów klamrowych.

Na przykład składnia New-Alias polecenia cmdlet zawiera następującą wartość wyliczenia dla parametru Opcja :
```
-Option {None | ReadOnly | Constant | Private | AllScope}
```
Nawiasy klamrowe i pionowe wskazują, że można wybrać dowolną z wymienionych wartości parametru Opcji , na przykład "ReadOnly" lub "AllScope".
```
-Option ReadOnly
```

Elementy opcjonalne

Nawiasy [] otaczają opcjonalne elementy. Na przykład w opisie New-Alias składni polecenia cmdlet parametr Zakres jest opcjonalny. Jest to wskazane w składni nawiasów wokół nazwy parametru i typu:

[-Scope <string>]

Oba poniższe przykłady są poprawne przy użyciu New-Alias polecenia cmdlet:

New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd -Value Update-TypeData -Scope Global

Nazwa parametru może być opcjonalna, nawet jeśli wartość tego parametru jest wymagana. Jest to wskazane w składni nawiasów wokół nazwy parametru, ale nie typu parametru, jak w tym przykładzie New-Alias z polecenia cmdlet:

[-Name] <string> [-Value] <string>

Następujące polecenia prawidłowo używają New-Alias polecenia cmdlet. Polecenia generują ten sam wynik.

New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd Update-TypeData
New-Alias utd -Value Update-TypeData
New-Alias utd Update-TypeData

Jeśli nazwa parametru nie jest uwzględniona w instrukcji zgodnie z typem, Windows PowerShell próbuje użyć pozycji argumentów w celu przypisania wartości do parametrów.

Poniższy przykład nie został ukończony:

New-Alias utd

To polecenie cmdlet wymaga wartości parametrów Nazwa i Wartość .

W przykładach składni nawiasy kwadratowe są również używane w nazewnictwie i rzutowaniu do typów .NET Framework. W tym kontekście nawiasy nie wskazują, że element jest opcjonalny.

Udostępnij za pośrednictwem