Udostępnij za pośrednictwem


Informacje o parametrach CommonParameters

KRÓTKI OPIS

Opisuje parametry, które mogą być używane z dowolnym poleceniem cmdlet.

DŁUGI OPIS

Typowe parametry to zestaw parametrów polecenia cmdlet, których można użyć z dowolnym poleceniem cmdlet. Są one implementowane przez program PowerShell, a nie przez dewelopera poleceń cmdlet i są automatycznie dostępne dla dowolnego polecenia cmdlet.

Można użyć typowych parametrów z dowolnym poleceniem cmdlet, ale mogą nie mieć wpływu na wszystkie polecenia cmdlet. Jeśli na przykład polecenie cmdlet nie generuje żadnych pełnych danych wyjściowych, użycie parametru Verbose common nie ma wpływu.

Typowe parametry są również dostępne w funkcjach zaawansowanych, które używają atrybutu CmdletBinding lub atrybutu Parametr oraz we wszystkich przepływach pracy.

Kilka typowych parametrów zastępuje wartości domyślne systemu lub preferencje ustawione przy użyciu zmiennych preferencji programu PowerShell. W przeciwieństwie do zmiennych preferencji typowe parametry mają wpływ tylko na polecenia, w których są używane.

Oprócz typowych parametrów wiele poleceń cmdlet oferuje parametry cofa i potwierdzania ograniczania ryzyka. Polecenia cmdlet, które wiążą się z ryzykiem dla systemu lub danych użytkownika, zwykle oferują te parametry.

Poniższa lista zawiera typowe parametry. Ich aliasy są wymienione w nawiasach.

  • Debugowanie (db)
  • ErrorAction (ea)
  • ErrorVariable (ev)
  • InformationAction (infa)
  • InformationVariable (iv)
  • Odchylenie (ov)
  • OutBuffer (ob)
  • PipelineVariable (pv)
  • Pełne (vb)
  • WarningAction (wa)
  • WarningVariable (wv)

Parametry ograniczania ryzyka to:

  • WhatIf (wi)
  • Potwierdź (cf)

Aby uzyskać więcej informacji, zobacz about_Preference_Variables.

TYPOWE OPISY PARAMETRÓW

Debugowanie

Alias debugowania to db.

Wyświetla szczegóły na poziomie programisty dotyczące operacji wykonywanej przez polecenie. Ten parametr działa tylko wtedy, gdy polecenie generuje komunikat debugowania. Na przykład ten parametr działa, gdy polecenie zawiera Write-Debug polecenie cmdlet.

Parametr Debug zastępuje wartość $DebugPreference zmiennej dla bieżącego polecenia, ustawiając wartość na $DebugPreferenceKontynuuj. Ponieważ domyślna wartość zmiennej $DebugPreference to SilentlyContinue, komunikaty debugowania nie są domyślnie wyświetlane.

-Debug:$true ma taki sam efekt jak -Debug. Służy -Debug:$false do pomijania wyświetlania komunikatów debugowania, gdy $DebugPreference nie jest to dyskretniecontinue, co jest wartością domyślną.

Erroraction

Alias usługi ErrorAction to ea.

Określa, jak polecenie cmdlet reaguje na błąd niepowodujący zakończenia polecenia. Ten parametr działa tylko wtedy, gdy polecenie generuje błąd niepowodujący zakończenia, taki jak ten z Write-Error polecenia cmdlet.

Parametr ErrorAction zastępuje wartość $ErrorActionPreference zmiennej dla bieżącego polecenia. Ponieważ wartość domyślna zmiennej $ErrorActionPreference to Kontynuuj, komunikaty o błędach są wyświetlane i wykonywanie będzie kontynuowane, chyba że użyjesz parametru ErrorAction .

Parametr ErrorAction nie ma wpływu na błędy zakończenia (takie jak brakujące dane, parametry, które nie są prawidłowe lub niewystarczające uprawnienia), które uniemożliwiają pomyślne ukończenie polecenia.

-ErrorAction:Continue wyświetla komunikat o błędzie i kontynuuje wykonywanie polecenia. Wartość domyślna to Continue.

-ErrorAction:Ignore pomija komunikat o błędzie i kontynuuje wykonywanie polecenia. W przeciwieństwie do funkcji SilentlyContinueignoruj nie dodaje komunikatu o błędzie do zmiennej automatycznej $Error . Wartość Ignoruj jest wprowadzana w programie PowerShell 3.0.

-ErrorAction:Inquire wyświetla komunikat o błędzie i monituje o potwierdzenie przed kontynuowaniem wykonywania. Ta wartość jest rzadko używana.

-ErrorAction:SilentlyContinue pomija komunikat o błędzie i kontynuuje wykonywanie polecenia.

-ErrorAction:Stop wyświetla komunikat o błędzie i zatrzymuje wykonywanie polecenia.

-ErrorAction:Suspend nie jest obsługiwana w programie PowerShell Core, ponieważ jest dostępna tylko dla przepływów pracy.

Uwaga

Parametr ErrorAction zastępuje, ale nie zastępuje wartości $ErrorAction zmiennej preferencji, gdy parametr jest używany w poleceniu do uruchamiania skryptu lub funkcji.

ErrorVariable

Alias błęduVariable to ev.

ErrorVariable przechowuje komunikaty o błędach dotyczące polecenia w określonej zmiennej i w zmiennej automatycznej $Error . Aby uzyskać więcej informacji, wpisz następujące polecenie:

Get-Help about_Automatic_Variables

Domyślnie nowe komunikaty o błędach zastępują komunikaty o błędach, które są już przechowywane w zmiennej. Aby dołączyć komunikat o błędzie do zawartości zmiennej, wpisz znak plus (+) przed nazwą zmiennej.

Na przykład następujące polecenie tworzy zmienną $a , a następnie przechowuje w niej wszelkie błędy:

Get-Process -Id 6 -ErrorVariable a

Następujące polecenie dodaje do zmiennej $a wszystkie komunikaty o błędach:

Get-Process -Id 2 -ErrorVariable +a

Następujące polecenie wyświetla zawartość elementu $a:

$a

Tego parametru można użyć do utworzenia zmiennej zawierającej tylko komunikaty o błędach z określonych poleceń. Zmienna automatyczna $Error zawiera komunikaty o błędach ze wszystkich poleceń w sesji. Możesz użyć notacji tablicy, takiej jak $a[0] lub $error[1,2] odwoływać się do określonych błędów przechowywanych w zmiennych.

InformationAction

Alias usługi InformationAction to ia.

Wprowadzono w programie PowerShell 5.0. W poleceniu lub skrycie, w którym jest używany, wspólny parametr InformationAction zastępuje wartość $InformationPreference zmiennej preferencji, która domyślnie ma wartość SilentlyContinue. W przypadku użycia Write-Information skryptu z funkcją InformationActionWrite-Information wartości są wyświetlane w zależności od wartości parametru InformationAction. Aby uzyskać więcej informacji na temat $InformationPreferenceprogramu , zobacz about_Preference_Variables.

-InformationAction:Stop zatrzymuje polecenie lub skrypt w wystąpieniu Write-Information polecenia.

-InformationAction:Ignore pomija komunikat informacyjny i kontynuuje uruchamianie polecenia. W przeciwieństwie do silentlyContinue, Ignoruj całkowicie zapomina o wiadomości informacyjnej; nie dodaje komunikatu informacyjnego do strumienia informacji.

-InformationAction:Inquire Wyświetla komunikat informacyjny określony w Write-Information poleceniu, a następnie pyta, czy chcesz kontynuować.

-InformationAction:Continue wyświetla komunikat informacyjny i kontynuuje działanie.

-InformationAction:Suspend nie jest obsługiwana w programie PowerShell Core, ponieważ jest dostępna tylko dla przepływów pracy.

-InformationAction:SilentlyContinue brak wpływu, ponieważ komunikat informacyjny nie jest wyświetlany (wartość domyślna), a skrypt będzie kontynuowany bez przerwy.

Uwaga

Przesłonięcia parametru $InformationActionInformationAction, ale nie zastępuje wartości zmiennej preferencji, gdy parametr jest używany w poleceniu do uruchamiania skryptu lub funkcji.

InformationVariable

Alias informationVariable to iv.

Wprowadzono w programie PowerShell 5.0. W poleceniu lub skrypcie, w którym jest używany, wspólny parametr InformationVariable przechowuje w zmiennej ciąg określony przez dodanie Write-Information polecenia. Write-Information wartości są wyświetlane w zależności od wartości wspólnego parametru InformationAction ; Jeśli nie dodasz wspólnego parametru InformationAction , Write-Information ciągi są wyświetlane w zależności od wartości zmiennej $InformationPreference preferencji. Aby uzyskać więcej informacji na temat $InformationPreferenceprogramu , zobacz about_Preference_Variables.

OutBuffer

Alias dla wartości OutBuffer jest ob i przyjmuje wartość System.Int32 .

Określa liczbę obiektów do gromadzenia się w buforze, zanim jakiekolwiek obiekty zostaną wysłane przez potok. W przypadku pominięcia tego parametru obiekty są wysyłane podczas ich generowania.

Ten parametr zarządzania zasobami jest przeznaczony dla zaawansowanych użytkowników. W przypadku użycia tego parametru program PowerShell wysyła dane do następnego polecenia cmdlet w partiach OutBuffer + 1.

W poniższym przykładzie są wyświetlane alternatywne opcje między ForEach-Object blokami przetwarzania Write-Host , które używają polecenia cmdlet. Wyświetlanie alternatywnych w partiach 2 lub OutBuffer + 1.

1..4 | ForEach-Object {
        Write-Host "$($_): First"; $_
      } -OutBuffer 1 | ForEach-Object {
                        Write-Host "$($_): Second" }
1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second

Odchylenie

Alias zmiennej OutVariable to ov.

Przechowuje obiekty wyjściowe z polecenia w określonej zmiennej oprócz wysyłania danych wyjściowych wzdłuż potoku.

Aby dodać dane wyjściowe do zmiennej, zamiast zastępować wszystkie dane wyjściowe, które mogą być już tam przechowywane, wpisz znak plus (+) przed nazwą zmiennej.

Na przykład następujące polecenie tworzy zmienną $out i przechowuje w nim obiekt procesu:

Get-Process PowerShell -OutVariable out

Następujące polecenie dodaje obiekt procesu do zmiennej $out :

Get-Process iexplore -OutVariable +out

Następujące polecenie wyświetla zawartość zmiennej $out :

$out

Uwaga

Zmienna utworzona przez parametr OutVariable to [System.Collections.ArrayList].

PipelineVariable

Alias elementu PipelineVariable to pv i przyjmuje wartość ciągu .

PipelineVariable przechowuje wartość bieżącego elementu potoku jako zmienną dla dowolnego nazwanego polecenia, gdy przepływa przez potok.

Prawidłowe wartości to ciągi, takie same jak w przypadku wszystkich nazw zmiennych.

Poniżej przedstawiono przykład działania elementu PipelineVariable . W tym przykładzie parametr PipelineVariable jest dodawany do Foreach-Object polecenia w celu przechowywania wyników polecenia w zmiennych. Zakres liczb, od 1 do 10, są przesyłane potokiem do pierwszego Foreach-Object polecenia, z których wyniki są przechowywane w zmiennej o nazwie Left.

Wyniki pierwszego Foreach-Object polecenia są przesyłane potokiem do drugiego Foreach-Object polecenia, które filtruje obiekty zwracane przez pierwsze Foreach-Object polecenie. Wyniki drugiego polecenia są przechowywane w zmiennej o nazwie Right.

W trzecim Foreach-Object poleceniu wyniki pierwszych dwóch Foreach-Object poleceń potokowych reprezentowanych przez zmienne w lewo i w prawo są przetwarzane przy użyciu operatora mnożenia. Polecenie instruuje obiekty przechowywane w zmiennych po lewej i prawej , które mają być mnożone, i określa, że wyniki powinny być wyświetlane jako "Lewy element członkowski zakresu * Element członkowski zakresu prawego = produkt".

1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
  Foreach-Object -PV Right -Process { 1..10 } |
  Foreach-Object -Process { "$Left * $Right = " + ($Left*$Right) }
1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
...

Pełny

Alias verbose to vb.

Wyświetla szczegółowe informacje o operacji wykonanej przez polecenie. Te informacje przypominają informacje w śladzie lub w dzienniku transakcji. Ten parametr działa tylko wtedy, gdy polecenie generuje pełny komunikat. Na przykład ten parametr działa, gdy polecenie zawiera Write-Verbose polecenie cmdlet.

Parametr Verbose zastępuje wartość zmiennej $VerbosePreference dla bieżącego polecenia. Ponieważ domyślna wartość zmiennej $VerbosePreference to SilentlyContinue, pełne komunikaty nie są domyślnie wyświetlane.

-Verbose:$true ma taki sam efekt jak -Verbose

-Verbose:$false pomija wyświetlanie pełnych komunikatów. Użyj tego parametru, gdy wartość parametru $VerbosePreference nie jest dyskretniecontinue (wartość domyślna).

Warningaction

Alias usługi WarningAction to wa.

Określa, jak polecenie cmdlet reaguje na ostrzeżenie z polecenia . Kontynuuj jest wartością domyślną. Ten parametr działa tylko wtedy, gdy polecenie generuje komunikat ostrzegawczy. Na przykład ten parametr działa, gdy polecenie zawiera Write-Warning polecenie cmdlet.

Parametr WarningAction zastępuje wartość $WarningPreference zmiennej dla bieżącego polecenia. Ponieważ wartość domyślna zmiennej $WarningPreference to Kontynuuj, ostrzeżenia są wyświetlane i wykonywanie będzie kontynuowane, chyba że używasz parametru WarningAction .

-WarningAction:Continue wyświetla komunikaty ostrzegawcze i kontynuuje wykonywanie polecenia. Wartość domyślna to Continue.

-WarningAction:Inquire wyświetla komunikat ostrzegawczy i monituje o potwierdzenie przed kontynuowaniem wykonywania. Ta wartość jest rzadko używana.

-WarningAction:SilentlyContinue pomija komunikat ostrzegawczy i kontynuuje wykonywanie polecenia.

-WarningAction:Stop wyświetla komunikat ostrzegawczy i zatrzymuje wykonywanie polecenia.

Uwaga

Przesłonięcia parametru WarningAction , ale nie zastępuje wartości $WarningAction zmiennej preferencji, gdy parametr jest używany w poleceniu do uruchamiania skryptu lub funkcji.

OstrzeżenieVariable

Alias dla warningVariable to wv.

Przechowuje ostrzeżenia dotyczące polecenia w określonej zmiennej.

Wszystkie wygenerowane ostrzeżenia są zapisywane w zmiennej, nawet jeśli ostrzeżenia nie są wyświetlane użytkownikowi.

Aby dołączyć ostrzeżenia do zawartości zmiennej, zamiast zastępować wszelkie ostrzeżenia, które mogą być już tam przechowywane, wpisz znak plus (+) przed nazwą zmiennej.

Na przykład następujące polecenie tworzy zmienną $a , a następnie przechowuje w niej wszelkie ostrzeżenia:

Get-Process -Id 6 -WarningVariable a

Następujące polecenie dodaje wszelkie ostrzeżenia do zmiennej $a :

Get-Process -Id 2 -WarningVariable +a

Następujące polecenie wyświetla zawartość elementu $a:

$a

Tego parametru można użyć do utworzenia zmiennej zawierającej tylko ostrzeżenia z określonych poleceń. Możesz użyć notacji tablicy, takiej jak $a[0] lub $warning[1,2] odwołać się do określonych ostrzeżeń przechowywanych w zmiennej.

Uwaga

Parametr WarningVariable nie przechwytuje ostrzeżeń z zagnieżdżonych wywołań w funkcjach lub skryptach.

Opisy parametrów zarządzania ryzykiem

Instrukcja WhatIf

Alias whatIf to wi.

Wyświetla komunikat opisujący efekt polecenia zamiast wykonywania polecenia.

Parametr WhatIf zastępuje wartość zmiennej $WhatIfPreference dla bieżącego polecenia. Ponieważ wartość domyślna zmiennej $WhatIfPreference to 0 (wyłączone), zachowanie WhatIf nie jest wykonywane bez parametru WhatIf . Aby uzyskać więcej informacji, wpisz następujące polecenie:

Get-Help about_Preference_Variables

-WhatIf:$true ma taki sam efekt jak -WhatIf.

-WhatIf:$false pomija automatyczne zachowanie WhatIf, które powoduje, gdy wartość zmiennej $WhatIfPreference wynosi 1.

Na przykład następujące polecenie używa parametru -WhatIf w Remove-Item poleceniu:

Remove-Item Date.csv -WhatIf

Zamiast usuwać element, program PowerShell wyświetla listę operacji, których dotyczy, i elementów, których dotyczy problem. To polecenie generuje następujące dane wyjściowe:

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

Confirm

Alias potwierdzania jest cf.

Monituje o potwierdzenie przed wykonaniem polecenia.

Parametr Confirm zastępuje wartość zmiennej $ConfirmPreference dla bieżącego polecenia. Wartością domyślną jest true. Aby uzyskać więcej informacji, wpisz następujące polecenie:

Get-Help about_Preference_Variables

-Confirm:$true ma taki sam efekt jak -Confirm.

-Confirm:$false pomija automatyczne potwierdzenie, które występuje, gdy wartość wartości $ConfirmPreference jest mniejsza lub równa szacowanemu ryzyku polecenia cmdlet.

Na przykład następujące polecenie używa parametru Confirm z poleceniem Remove-Item . Przed usunięciem elementu program PowerShell wyświetla listę operacji, których dotyczy, oraz elementów, których dotyczy problem, oraz monituje o zatwierdzenie.

PS C:\ps-test> Remove-Item tmp*.txt -Confirm

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend
[?] Help (default is "Y"):

Opcje potwierdzania odpowiedzi są następujące:

Reakcja Wynik
Tak (Y) Wykonaj akcję.
Tak do wszystkich (A) Wykonaj wszystkie akcje i pomiń kolejne potwierdzenia zapytań
dla tego polecenia.
Nie (N): Nie wykonuj akcji.
Nie do wszystkich (L): Nie wykonuj żadnych akcji i pomijaj kolejne potwierdzanie
kwerendy dla tego polecenia.
Wstrzymywanie (S): Wstrzymaj polecenie i utwórz sesję tymczasową.
Pomoc (?) Wyświetl pomoc dotyczącą tych opcji.

Opcja Wstrzymaj powoduje wstrzymanie polecenia i tworzy tymczasową sesję zagnieżdżona, w której można pracować, dopóki nie będzie można wybrać opcji Potwierdź . Wiersz polecenia dla zagnieżdżonej sesji ma dwa dodatkowe daszki (>>), aby wskazać, że jest to podrzędna operacja oryginalnego polecenia nadrzędnego. Polecenia i skrypty można uruchamiać w sesji zagnieżdżonej. Aby zakończyć sesję zagnieżdżoną i powrócić do opcji Potwierdź dla oryginalnego polecenia, wpisz "exit".

W poniższym przykładzie opcja Wstrzymanie (S) jest używana do tymczasowego zatrzymania polecenia, gdy użytkownik sprawdza pomoc dla parametru polecenia. Po uzyskaniu wymaganych informacji użytkownik wpisze "exit" w celu zakończenia zagnieżdżonego monitu, a następnie wybierze odpowiedź Tak (y) na potwierdzenie zapytania.

PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm

Confirm
Are you sure you want to perform this action?

Performing operation "Create File" on Target "Destination:
C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default
is "Y"): s

PS C:\ps-test> Get-Help New-Item -Parameter ItemType

-ItemType <string>
Specifies the provider-specified type of the new item.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       true (ByPropertyName)
Accept wildcard characters?  false

PS C:\ps-test> exit

Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test
.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (defau
lt is "Y"): y

Directory: C:\ps-test

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         8/27/2010   2:41 PM          0 test.txt

SŁOWA KLUCZOWE

about_Common_Parameters

ZOBACZ RÓWNIEŻ

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose