Informationen zu CommonParameters
KURZE BESCHREIBUNG
Beschreibt die Parameter, die mit jedem Cmdlet verwendet werden können.
LANGE BESCHREIBUNG
Die allgemeinen Parameter sind eine Reihe von Cmdletparametern, die Sie mit jedem Cmdlet verwenden können. Sie werden von PowerShell implementiert, nicht vom Cmdlet-Entwickler, und sind automatisch für jedes Cmdlet verfügbar.
Sie können die allgemeinen Parameter mit jedem Cmdlet verwenden, aber sie wirken sich möglicherweise nicht auf alle Cmdlets aus. Wenn ein Cmdlet beispielsweise keine ausführliche Ausgabe generiert, hat die Verwendung des allgemeinen Parameters Verbose keine Auswirkung.
Die allgemeinen Parameter sind auch für erweiterte Funktionen verfügbar, die das CmdletBinding-Attribut oder das Parameter-Attribut verwenden.
Mehrere gängige Parameter überschreiben Systemstandardeinstellungen oder -einstellungen, die Sie mithilfe der PowerShell-Einstellungsvariablen festlegen. Im Gegensatz zu den Einstellungsvariablen wirken sich die allgemeinen Parameter nur auf die Befehle aus, in denen sie verwendet werden.
Weitere Informationen finden Sie unter about_Preference_Variables.
In der folgenden Liste werden die allgemeinen Parameter angezeigt. Ihre Aliase sind in Klammern aufgeführt.
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Ausführlich (vb)
- WarningAction (wa)
- WarningVariable (wv)
Die Aktionsparameter sind Werte vom Typ "ActionPreference" . ActionPreference ist eine Enumeration mit den folgenden Werten:
| Name | Wert |
|---|---|
| Angehalten | 5 |
| Ignorieren | 4 |
| Diagnosetool | 3 |
| Weiter | 2 |
| Beenden | 1 |
| SilentlyContinue | 0 |
Sie können den Namen oder den Wert mit dem Parameter verwenden.
Zusätzlich zu den allgemeinen Parametern bieten viele Cmdlets Parameter zur Risikominderung. Cmdlets, die Risiken für das System oder für Benutzerdaten beinhalten, bieten in der Regel diese Parameter an.
Die Parameter zur Risikominderung sind:
- WhatIf (wi)
- Bestätigen (siehe)
ALLGEMEINE PARAMETERBESCHREIBUNGEN
Debuggen
Zeigt Details auf Programmiererebene über den Vorgang an, der mit dem Befehl ausgeführt wird. Dieser Parameter funktioniert nur, wenn der Befehl eine Debugmeldung generiert. Dieser Parameter funktioniert beispielsweise, wenn ein Befehl das Write-Debug Cmdlet enthält.
Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Standardmäßig werden Debugmeldungen nicht angezeigt, da der Wert der $DebugPreference Variablen SilentlyContinue ist.
Im interaktiven Modus überschreibt der Debug-Parameter den Wert der $DebugPreference Variablen für den aktuellen Befehl und legt den Wert von $DebugPreference auf Inquire fest.
Im nicht interaktiven Modus überschreibt der Debug-Parameter den Wert der $DebugPreference Variablen für den aktuellen Befehl und legt den Wert von $DebugPreference auf Continue fest.
-Debug:$true hat die gleiche Wirkung wie -Debug. Verwenden Sie -Debug:$false , um die Anzeige von Debugnachrichten zu unterdrücken, wenn $DebugPreference nicht SilentlyContinue ist, was der Standard ist.
ErrorAction
Bestimmt, wie das Cmdlet auf einen nicht beendenden Fehler des Befehls reagiert.
Dieser Parameter funktioniert nur, wenn der Befehl einen nicht beendenden Fehler generiert, z. B. aus dem Write-Error Cmdlet.
Type: ActionPreference
Aliases: ea
Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Der ErrorAction-Parameter überschreibt den Wert der $ErrorActionPreference Variablen für den aktuellen Befehl. Da der Standardwert der $ErrorActionPreference Variablen Continue ist, werden Fehlermeldungen angezeigt und die Ausführung wird fortgesetzt, es sei denn, Sie verwenden den ErrorAction-Parameter .
Der ErrorAction-Parameter hat keine Auswirkungen auf das Beenden von Fehlern (z. B. fehlende Daten, ungültige Parameter oder unzureichende Berechtigungen), die verhindern, dass ein Befehl erfolgreich abgeschlossen wird.
-ErrorAction:Continue zeigt die Fehlermeldung an, und setzt die Ausführung des Befehls fort. Continue ist die Standardoption.
-ErrorAction:Ignore unterdrückt die Fehlermeldung und setzt die Ausführung des Befehls fort. Im Gegensatz zu SilentlyContinue fügt Ignore die Fehlermeldung nicht zur automatischen $Error Variablen hinzu. Der Ignore-Wert wird in PowerShell 3.0 eingeführt.
-ErrorAction:Inquire zeigt die Fehlermeldung an und fordert Sie zur Bestätigung auf, bevor Sie mit der Ausführung fortfahren. Dieser Wert wird selten verwendet.
-ErrorAction:SilentlyContinue unterdrückt die Fehlermeldung und setzt die Ausführung des Befehls fort.
-ErrorAction:Stop zeigt die Fehlermeldung an und beendet die Ausführung des Befehls.
-ErrorAction:Suspend ist nur für Workflows verfügbar, die in PowerShell 6 und darüber hinaus nicht unterstützt werden.
Hinweis
Der ErrorAction-Parameter überschreibt, ersetzt aber nicht den Wert der $ErrorAction Einstellungsvariablen, wenn der Parameter in einem Befehl zum Ausführen eines Skripts oder einer Funktion verwendet wird.
ErrorVariable
ErrorVariable speichert Fehlermeldungen zum Befehl in der angegebenen Variablen und in der $Error automatischen Variablen. Weitere Informationen finden Sie unter about_Automatic_Variables.
Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Standardmäßig überschreiben neue Fehlermeldungen Fehlermeldungen, die bereits in der Variablen gespeichert sind. Um die Fehlermeldung an den Variableninhalt anzufügen, geben Sie vor dem Variablennamen ein Pluszeichen (+) ein.
Der folgende Befehl erstellt beispielsweise die $a Variable und speichert dann alle Fehler darin:
Get-Process -Id 6 -ErrorVariable a
Der folgende Befehl fügt der $a Variablen alle Fehlermeldungen hinzu:
Get-Process -Id 2 -ErrorVariable +a
Der folgende Befehl zeigt den Inhalt von an $a:
$a
Mit diesem Parameter können Sie eine Variable erstellen, die nur Fehlermeldungen von bestimmten Befehlen enthält und sich nicht auf das Verhalten der $Error automatischen Variablen auswirkt. Die $Error automatische Variable enthält Fehlermeldungen von allen Befehlen in der Sitzung. Sie können die Arraynotation verwenden, z $a[0] . B. oder $error[1,2] , um auf bestimmte Fehler zu verweisen, die in den Variablen gespeichert sind.
Hinweis
Die benutzerdefinierte Fehlervariable enthält alle vom Befehl generierten Fehler, einschließlich Der Fehler aus Aufrufen geschachtelter Funktionen oder Skripts.
InformationAction
In PowerShell 5.0 eingeführt. Innerhalb des Befehls oder Skripts, in dem er verwendet wird, setzt der allgemeine Parameter InformationAction den Wert der $InformationPreference Einstellungsvariablen außer Kraft, die standardmäßig auf SilentlyContinue festgelegt ist. Wenn Sie in einem Skript mit InformationAction verwendenWrite-Information, Write-Information werden werte abhängig vom Wert des InformationAction-Parameters angezeigt. Weitere Informationen zu $InformationPreferencefinden Sie unter about_Preference_Variables.
Type: ActionPreference
Aliases: ia
Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
-InformationAction:Stop beendet einen Befehl oder ein Skript beim Auftreten des Write-Information Befehls.
-InformationAction:Ignore unterdrückt die Informationsmeldung und setzt die Ausführung des Befehls fort. Im Gegensatz zu SilentlyContinue vergisst Ignore die Informationsnachricht vollständig. Die Informationsmeldung wird dem Informationsstream nicht hinzugefügt.
-InformationAction:Inquire zeigt die Informationsmeldung an, die Sie in einem Write-Information Befehl angeben, und fragt dann, ob Sie fortfahren möchten.
-InformationAction:Continue zeigt die Informationsmeldung an und wird fortgesetzt.
-InformationAction:Suspend wird in PowerShell Core nicht unterstützt, da es nur für Workflows verfügbar ist.
-InformationAction:SilentlyContinue keine Auswirkung, da die Informationsmeldung nicht angezeigt wird (Standard), und das Skript wird ohne Unterbrechung fortgesetzt.
Hinweis
Der InformationAction-Parameter überschreibt, ersetzt jedoch nicht den Wert der $InformationAction Einstellungsvariablen, wenn der Parameter in einem Befehl zum Ausführen eines Skripts oder einer Funktion verwendet wird.
InformationVariable
Eingeführt in PowerShell 5.0. Innerhalb des Befehls oder Skripts, in dem er verwendet wird, speichert der allgemeine Parameter InformationVariable in einer Variablen eine Zeichenfolge, die Sie durch Hinzufügen des Write-Information Befehls angeben. Write-Information -Werte werden abhängig vom Wert des allgemeinen InformationAction-Parameters angezeigt. Wenn Sie den allgemeinen InformationAction-Parameter nicht hinzufügen, Write-Information werden je nach Wert der $InformationPreference Einstellungsvariablen Zeichenfolgen angezeigt. Weitere Informationen zu $InformationPreferencefinden Sie unter about_Preference_Variables.
Hinweis
Die Informationsvariable enthält alle vom Befehl generierten Informationsmeldungen, einschließlich Informationsmeldungen von Aufrufen geschachtelter Funktionen oder Skripts.
Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
OutBuffer
Bestimmt die Anzahl der Objekte, die in einem Puffer gesammelt werden sollen, bevor Objekte über die Pipeline gesendet werden. Wenn Sie diesen Parameter weglassen, werden Objekte gesendet, während sie generiert werden.
Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Dieser Ressourcenverwaltungsparameter ist für fortgeschrittene Benutzer konzipiert. Wenn Sie diesen Parameter verwenden, sendet PowerShell Daten an das nächste Cmdlet in Batches von OutBuffer + 1.
Im folgenden Beispiel wird zwischen ForEach-Object Blöcken angezeigt, die das Write-Host Cmdlet verwenden. Die Anzeige wechselt in Batches von 2 oder 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
OutVariable
Speichert Ausgabeobjekte aus dem Befehl in der angegebenen Variablen zusätzlich zum Senden der Ausgabe entlang der Pipeline.
Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Um der Variablen die Ausgabe hinzuzufügen, geben Sie vor dem Variablennamen ein Pluszeichen (+) ein, anstatt eine Ausgabe zu ersetzen, die möglicherweise bereits dort gespeichert ist.
Mit dem folgenden Befehl wird beispielsweise die $out Variable erstellt und das Prozessobjekt darin gespeichert:
Get-Process PowerShell -OutVariable out
Der folgende Befehl fügt der Variablen das $out Prozessobjekt hinzu:
Get-Process iexplore -OutVariable +out
Der folgende Befehl zeigt den Inhalt der $out Variablen an:
$out
Hinweis
Die vom OutVariable-Parameter erstellte Variable ist eine [System.Collections.ArrayList].
PipelineVariable
PipelineVariable speichert den Wert des aktuellen Pipelineelements als Variable für jeden benannten Befehl, während er durch die Pipeline fließt.
Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Gültige Werte sind Zeichenfolgen, die gleichen wie für alle Variablennamen.
Im Folgenden finden Sie ein Beispiel für die Funktionsweise von PipelineVariable . In diesem Beispiel wird der PipelineVariable-Parameter einem Foreach-Object Befehl hinzugefügt, um die Ergebnisse des Befehls in Variablen zu speichern. Ein Zahlenbereich von 1 bis 10 wird an den ersten Foreach-Object Befehl übergeben, dessen Ergebnisse in einer Variablen mit dem Namen Left gespeichert werden.
Die Ergebnisse des ersten Foreach-Object Befehls werden in einen zweiten Foreach-Object Befehl weitergeleitet, der die vom ersten Foreach-Object Befehl zurückgegebenen Objekte filtert. Die Ergebnisse des zweiten Befehls werden in einer Variablen mit dem Namen Right gespeichert.
Im dritten Foreach-Object Befehl werden die Ergebnisse der ersten beiden Foreach-Object Pipebefehle, dargestellt durch die Variablen Left und Right, mithilfe eines Multiplikationsoperators verarbeitet. Der Befehl weist Objekte an, die in den Variablen Left und Right gespeichert sind, zu multiplizieren, und gibt an, dass die Ergebnisse als "Left range member * Right range member = product" angezeigt werden sollen.
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
...
Ausführlich
Zeigt detaillierte Informationen zu dem Vorgang an, der vom Befehl ausgeführt wird. Diese Informationen ähneln den Informationen in einer Ablaufverfolgung oder in einem Transaktionsprotokoll. Dieser Parameter funktioniert nur, wenn der Befehl eine ausführliche Meldung generiert. Dieser Parameter funktioniert beispielsweise, wenn ein Befehl das Write-Verbose Cmdlet enthält.
Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Der Verbose-Parameter überschreibt den Wert der $VerbosePreference Variablen für den aktuellen Befehl. Da der Standardwert der $VerbosePreference Variablen SilentlyContinue ist, werden ausführliche Meldungen standardmäßig nicht angezeigt.
-Verbose:$true hat die gleiche Wirkung wie -Verbose
-Verbose:$false unterdrückt die Anzeige ausführlicher Meldungen. Verwenden Sie diesen Parameter, wenn der Wert von $VerbosePreference nicht SilentlyContinue (Standard) ist.
WarningAction
Bestimmt, wie das Cmdlet auf eine Warnung des Befehls reagiert. Continue ist der Standardwert. Dieser Parameter funktioniert nur, wenn der Befehl eine Warnmeldung generiert. Dieser Parameter funktioniert beispielsweise, wenn ein Befehl das Write-Warning Cmdlet enthält.
Type: ActionPreference
Aliases: wa
Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Der WarningAction-Parameter überschreibt den Wert der $WarningPreference Variablen für den aktuellen Befehl. Da der Standardwert der $WarningPreference Variablen Continue ist, werden Warnungen angezeigt, und die Ausführung wird fortgesetzt, es sei denn, Sie verwenden den WarningAction-Parameter .
-WarningAction:Continue zeigt die Warnmeldungen an und setzt die Ausführung des Befehls fort. Continue ist die Standardoption.
-WarningAction:Inquire zeigt die Warnmeldung an und fordert Sie zur Bestätigung auf, bevor Sie die Ausführung fortsetzen. Dieser Wert wird selten verwendet.
-WarningAction:SilentlyContinue unterdrückt die Warnmeldung und setzt die Ausführung des Befehls fort.
-WarningAction:Stop zeigt die Warnmeldung an und beendet die Ausführung des Befehls.
Hinweis
Der WarningAction-Parameter überschreibt, ersetzt jedoch nicht den Wert der $WarningAction Einstellungsvariablen, wenn der Parameter in einem Befehl zum Ausführen eines Skripts oder einer Funktion verwendet wird.
WarningVariable
Speichert Warnungen zum Befehl in der angegebenen Variablen.
Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Alle generierten Warnungen werden in der Variablen gespeichert, auch wenn die Warnungen dem Benutzer nicht angezeigt werden.
Um die Warnungen an den Variableninhalt anzufügen, geben Sie ein Pluszeichen (+) vor dem Variablennamen ein, anstatt alle Warnungen zu ersetzen, die möglicherweise bereits dort gespeichert sind.
Der folgende Befehl erstellt z. B. die $a Variable und speichert dann alle Warnungen darin:
Get-Process -Id 6 -WarningVariable a
Der folgende Befehl fügt der $a Variablen alle Warnungen hinzu:
Get-Process -Id 2 -WarningVariable +a
Der folgende Befehl zeigt den Inhalt von an $a:
$a
Sie können diesen Parameter verwenden, um eine Variable zu erstellen, die nur Warnungen von bestimmten Befehlen enthält. Sie können die Arraynotation verwenden, z $a[0] . B. oder $warning[1,2] , um auf bestimmte Warnungen zu verweisen, die in der Variablen gespeichert sind.
Hinweis
Die Warnungsvariable enthält alle Warnungen, die vom Befehl generiert werden, einschließlich Warnungen von Aufrufen geschachtelter Funktionen oder Skripts.
Beschreibungen von Risikomanagementparametern
WhatIf
Zeigt eine Meldung an, die die Auswirkung des Befehls beschreibt, anstatt den Befehl auszuführen.
Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Der WhatIf-Parameter überschreibt den Wert der $WhatIfPreference Variablen für den aktuellen Befehl. Da der Standardwert der $WhatIfPreference Variablen 0 (deaktiviert) ist, erfolgt das WhatIf-Verhalten nicht ohne den WhatIf-Parameter . Weitere Informationen finden Sie unter about_Preference_Variables
-WhatIf:$true hat die gleiche Wirkung wie -WhatIf.
-WhatIf:$false unterdrückt das automatische WhatIf-Verhalten, das sich ergibt, wenn der Wert der $WhatIfPreference Variablen 1 ist.
Der folgende Befehl verwendet beispielsweise den -WhatIf Parameter in einem Remove-Item Befehl:
Remove-Item Date.csv -WhatIf
Anstatt das Element zu entfernen, listet PowerShell die Vorgänge auf, die es ausführen würde, und die elemente, die betroffen wären. Dieser Befehl erstellt die folgende Ausgabe:
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
Confirm
Fordert eine Bestätigung an, bevor der Befehl ausgeführt wird.
Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Der Confirm-Parameter überschreibt den Wert der $ConfirmPreference Variablen für den aktuellen Befehl. Der Standardwert lautet „true“. Weitere Informationen finden Sie unter about_Preference_Variables
-Confirm:$true hat die gleiche Wirkung wie -Confirm.
-Confirm:$false Unterdrückt die automatische Bestätigung, die auftritt, wenn der Wert von $ConfirmPreference kleiner oder gleich dem geschätzten Risiko des Cmdlets ist.
Der folgende Befehl verwendet beispielsweise den Confirm-Parameter mit einem Remove-Item Befehl. Bevor das Element entfernt wird, listet PowerShell die Vorgänge auf, die es ausführen würde, und die elemente, die betroffen wären, und fordert die Genehmigung auf.
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"):
Die Antwortoptionen bestätigen sind wie folgt:
| Antwort | Ergebnis |
|---|---|
| Ja (Y) | Führen Sie die Aktion aus. |
| Ja zu allen (A) | Ausführen aller Aktionen und Unterdrücken nachfolgender Bestätigungsabfragen |
| für diesen Befehl. | |
| Nein (N): | Führen Sie die Aktion nicht aus. |
| Nein zu allen (L): | Führen Sie keine Aktionen aus, und unterdrücken Sie nachfolgende Bestätigen. |
| Abfragen für diesen Befehl. | |
| Anhalten (S): | Halten Sie den Befehl an, und erstellen Sie eine temporäre Sitzung. |
| Hilfe (?) | Hilfe zu diesen Optionen anzeigen. |
Die Option Anhalten setzt den Befehl in den Haltepunkt und erstellt eine temporäre geschachtelte Sitzung, in der Sie arbeiten können, bis Sie die Option Bestätigen auswählen können. Die Eingabeaufforderung für die geschachtelte Sitzung verfügt über zwei zusätzliche Carets (>>), um anzugeben, dass es sich um einen untergeordneten Vorgang des ursprünglichen übergeordneten Befehls handelt. Sie können Befehle und Skripts in der geschachtelten Sitzung ausführen. Um die geschachtelte Sitzung zu beenden und zu den Bestätigen-Optionen für den ursprünglichen Befehl zurückzukehren, geben Sie "exit" ein.
Im folgenden Beispiel wird die Option Anhalten (S) verwendet, um einen Befehl vorübergehend anzuhalten, während der Benutzer die Hilfe auf einen Befehlsparameter überprüft. Nach dem Abrufen der erforderlichen Informationen gibt der Benutzer "exit" ein, um die geschachtelte Eingabeaufforderung zu beenden, und wählt dann die Antwort Ja (y) auf die Abfrage Bestätigen aus.
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
SCHLÜSSELWÖRTER
about_Common_Parameters