about_CommonParameters
Letzte Aktualisierung: August 2012
Betrifft: Windows PowerShell 2.0, Windows PowerShell 3.0
Einführung hier einfügen.
THEMA
about_CommonParameters
KURZE BESCHREIBUNG
Beschreibt die Parameter, die mit jedem Cmdlet verwendet werden können.
LANGE BESCHREIBUNG
Allgemeine Parameter sind eine Reihe von Cmdlet-Parametern, die Sie mit jedem Cmdlet verwenden können. Sie werden durch Windows PowerShell® implementiert, nicht durch den Cmdlet-Entwickler, und sie stehen automatisch für alle Cmdlets zur Verfügung.
Sie können die allgemeinen Parameter mit jedem Cmdlet verwenden, aber sie wirken sich möglicherweise nicht auf alle Cmdlets aus. Wenn z. B. ein Cmdlet keine ausführliche Ausgabe erzeugt, 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, und für alle Workflows.
Einige allgemeine Parameter setzen Systemstandards oder Voreinstellungen außer Kraft, die Sie mit den Windows PowerShell-Voreinstellungsvariablen festlegen. Im Gegensatz zu den Voreinstellungsvariablen wirken sich die allgemeinen Parameter nur auf die Befehle aus, in denen sie verwendet werden.
Zusätzlich zu den allgemeinen Parametern bieten viele Cmdlets WhatIf- und Confirm-Parameter zur Risikominderung. Cmdlets, die mit einem Risiko für das System oder für Benutzerdaten verbunden sind, bieten in der Regel diese Parameter.
Die folgende Liste enthält die allgemeinen Parameter. Ihre Aliase werden in Klammern aufgeführt.
-Debug (db)
-ErrorAction (ea)
-ErrorVariable (ev)
-OutVariable (ov)
-OutBuffer (ob)
-PipelineVariable (pv)
-Verbose (vb)
-WarningAction (wa)
-WarningVariable (wv
Die Parameter zur Risikominderung sind:
-WhatIf (wi)
-Confirm (cf)
Um weitere Informationen zu Voreinstellungsvariablen zu erhalten, geben Sie ein:
help about_Preference_Variables
BESCHREIBUNG DER ALLGEMEINEN PARAMETER
-DEBUG[:{$TRUE | $FALSE}]
Alias: db
Zeigt die Details auf Programmiererebene über den Vorgang an, der durch den Befehl ausgeführt wird. Dieser Parameter funktioniert nur, wenn der Befehl eine Debugging-Meldung generiert. Dieser Parameter funktioniert beispielsweise, wenn ein Befehl das Write-Debug-Cmdlet enthält.
Der Debug-Parameter überschreibt den Wert der $DebugPreference-Variablen für den aktuellen Befehl und legt den Wert von $DebugPreference auf „Inquire“ fest. Da der Standardwert der $DebugPreference-Variable „SilentlyContinue“ ist, werden standardmäßig keine Debugging-Meldungen angezeigt.
Gültige Werte:
$true (-Debug:$true). Has the same effect as -Debug.
$false (-Debug:$false). Suppresses the display of debugging
messages when the value of the $DebugPreference is not
SilentlyContinue (the default).
-ERRORACTION[:{CONTINUE | IGNORE | INQUIRE | SILENTLYCONTINUE | STOP |SUSPEND }]
Alias: ea
Bestimmt, wie das Cmdlet auf einen durch den Befehl verursachten nicht zum Abbruch führenden Fehler reagiert. Dieser Parameter funktioniert nur, wenn der Befehl einen nicht zum Abbruch führenden Fehler generiert, wie etwa das Write-Error-Cmdlet.
Der ErrorAction-Parameter überschreibt den Wert der $ErrorActionPreference-Variablen für den aktuellen Befehl. Weil der Standardwert der $ErrorActionPreference-Variable „Continue“ lautet, werden Fehlermeldungen angezeigt, und die Ausführung wird fortgesetzt, es sei denn, Sie verwenden den ErrorAction-Parameter.
Der ErrorAction-Parameters hat keine Auswirkung auf zum Abbruch führende Fehler (z. B. fehlende Daten, ungültige Parameter oder unzureichende Berechtigungen), die verhindern, dass ein Befehl erfolgreich abgeschlossen werden kann.
Gültige Werte:
Continue. Zeigt die Fehlermeldung an und setzt die Ausführung des Befehls fort. „Continue“ ist der Standardwert.
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 wurde mit Windows PowerShell 3.0 eingeführt.
Inquire. Zeigt die Fehlermeldung an und fordert Sie vor dem Fortsetzen der Ausführung zur Bestätigung auf. Dieser Wert wird nur selten verwendet.
SilentlyContinue. Unterdrückt die Fehlermeldung und setzt die Ausführung des Befehls fort.
Stop. Zeigt die Fehlermeldung an und stoppt die Ausführung des Befehls.
Suspend. Dieser Wert ist nur in Windows PowerShell-Workflows verfügbar. Wenn ein Workflow in einem zum Abbruch führenden Fehler resultiert, hält diese Aktionsvoreinstellung automatisch den Auftrag an, um eine weitere Untersuchung zu ermöglichen. Nach der Untersuchung kann der Workflow fortgesetzt werden.
-ERRORVARIABLE [+]<VARIABLE-NAME>
Alias: ev
Speichert die Fehlermeldungen zum Befehl in der angegebenen Variablen und in der automatischen $Error-Variablen. Um weitere Informationen zu erhalten, geben Sie den folgenden Befehl ein:
get-help about_Automatic_Variables
Neue Fehlermeldungen überschreiben standardmäßig Fehlermeldungen, die bereits in der Variablen gespeichert wurden. Um die Fehlermeldung an den Inhalt der Variablen anzufügen, geben Sie ein Pluszeichen (+) vor dem Variablennamen ein.
Beispielsweise erstellt der folgende Befehl die $a-Variable und speichert dann alle darin enthaltenen Fehler:
Get-Process -Id 6 -ErrorVariable a
Der folgende Befehl fügt alle Fehlermeldungen zur $a-Variablen hinzu:
Get-Process -Id 2 -ErrorVariable +a
Der folgende Befehl zeigt den Inhalt von $a an:
$a
Sie können diesen Parameter verwenden, um eine Variable zu erstellen, die nur Fehlermeldungen von speziellen Befehlen enthält. Die automatische $Error-Variable enthält Fehlermeldungen aus allen Befehlen in der Sitzung. Sie können die Array-Notation verwenden, z. B. $a[0] oder $error[1,2], um auf bestimmte in den Variablen gespeicherte Fehler zu verweisen.
-OUTBUFFER <INT32>
Alias: ob
Bestimmt die Anzahl der Objekte, die in einem Puffer gesammelt werden, bevor irgendwelche Objekte über die Pipeline gesendet werden. Wenn Sie diesen Parameter weglassen, werden die Objekte gesendet, sobald sie erstellt werden.
Dieser Ressourcenmanagement-Parameter ist für erfahrene Benutzer vorgesehen. Wenn Sie diesen Parameter verwenden, ruft Windows PowerShell das nächste Cmdlet in der Pipeline erst dann auf, wenn die Anzahl der generierten Objekte OutBuffer + 1 beträgt. Danach sendet es alle Objekte, sobald sie generiert werden.
-OUTVARIABLE [+]<VARIABLE-NAME>
Alias: ov
Speichert die Ausgabeobjekte des Befehls in der angegebenen Variablen und zeigt sie in der Befehlszeile an.
Um die Ausgabe zur Variablen hinzuzufügen, anstatt alle Ausgaben zu ersetzen, die dort bereits gespeichert sein könnten, ein Pluszeichen (+) vor dem Variablennamen ein.
Der folgende Befehl erstellt z. B. die $out-Variable und speichert das Prozessobjekt darin:
Get-Process PowerShell -OutVariable out
Der folgende Befehl fügt das Prozessobjekt zur $out-Variablen hinzu:
Get-Process iexplore -OutVariable +out
Der folgende Befehl zeigt den Inhalt der $out-Variablen an:
$out
-PIPELINEVARIABLE <STRING>
Alias: pv
PipelineVariable speichert den Wert des aktuellen Elements der Pipeline als Variable, und zwar für jeden benannten Befehl, während er die Pipeline durchläuft.
Gültige Werte sind Zeichenfolgen, genauso wie bei jedem Variablennamen.
Das Folgende ist ein Beispiel der Funktionsweise von PipelineVariable. In diesem Beispiel wird ein PipelineVariable-Parameter zu einem Foreach-Object-Befehl hinzugefügt, um die die Ergebnisse des Befehls in Variablen zu speichern. Ein Bereich von Zahlen, 1 bis 10, werden in den ersten Foreach-Object-Befehl geleitet, und dessen Ergebnisse werden in einer Variablen namens „Left“ gespeichert.
Die Ergebnisse des ersten Foreach-Befehls werden an einer zweiten Foreach-Object-Befehl weitergeleitet, welcher die Objekte filtert, die von der ersten Foreach-Object-Befehl zurückgegeben wurden. Die Ergebnisse des zweiten Befehls werden in einer Variablen namens „Right“ gespeichert.
Im dritten Foreach-Object-Befehl werden die Ergebnisse der ersten beiden weitergeleiteten Foreach-Object-Befehle, die durch die Variablen „Left“ und „Right “ repräsentiert werden, durch einen Multiplikationsoperator verarbeitet. Der Befehl weist an, die in den Variablen „Left“ und „Right“ gespeicherten Objekte zu multiplizieren, und legt fest, 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
-VERBOSE[:{$TRUE | $FALSE}]
Alias: vb
Zeigt ausführliche Informationen über den Vorgang an, durch den 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.
Der Verbose-Parameter überschreibt den Wert der $VerbosePreference-Variablen für den aktuellen Befehl. Da der Standardwert der $VerbosePreference-Variable „SilentlyContinue“ ist, werden standardmäßig keine ausführlichen Meldungen angezeigt.
Gültige Werte:
$true (-Verbose:$true) has the same effect as -Verbose.
$false (-Verbose:$false) suppresses the display of verbose
messages. Use this parameter when the value of $VerbosePreference
is not SilentlyContinue (the default).
-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]
Alias: wa
Bestimmt, wie das Cmdlet auf eine Warnung von dem Befehl 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.
Der WarningAction-Parameter überschreibt den Wert der $WarningPreference-Variablen für den aktuellen Befehl. Da der Standardwert der $WarningPreference-Variablen „Continue“ ist, werden die Warnungen angezeigt, und die Ausführung wird fortgesetzt, außer wenn Sie den WarningAction-Parameter verwenden.
Gültige Werte:
Continue. Zeigt die Warnmeldung an und setzt die Ausführung des Befehls fort. „Continue“ ist der Standardwert.
Inquire. Zeigt die Warnmeldung an und fordert Sie vor dem Fortsetzen der Ausführung zur Bestätigung auf. Dieser Wert wird nur selten verwendet.
SilentlyContinue. Unterdrückt die Warnmeldung und setzt die Ausführung des Befehls fort.
Stop. Zeigt die Warnmeldung an und stoppt die Ausführung des Befehls.
HINWEIS: Der WarningAction-Parameter überschreibt nicht den Wert der Voreinstellungsvariablen $WarningAction, wenn der Parameter in einem Befehl verwendet wird, um ein Skript oder eine Funktion auszuführen.
-WARNINGVARIABLE [+]<VARIABLE-NAME>
Alias: wv
Speichert die Warnungen zu dem Befehl in der angegebenen Variablen.
Alle generierte Warnungen werden in der Variablen gespeichert, auch wenn die Warnung für den Benutzer nicht angezeigt werden.
Um die Warnungen zum Variableninhalt hinzuzufügen, anstatt alle Warnungen zu ersetzen, die dort bereits gespeichert sein könnten, ein Pluszeichen (+) vor dem Variablennamen ein.
Beispielsweise erstellt der folgende Befehl die $a-Variable und speichert dann alle darin enthaltenen Warnungen:
Get-Process -Id 6 -WarningVariable a
Der folgende Befehl fügt alle Warnungen zur $a-Variablen hinzu:
Get-Process -Id 2 -WarningVariable +a
Der folgende Befehl zeigt den Inhalt von $a an:
$a
Sie können diesen Parameter verwenden, um eine Variable zu erstellen, die nur Warnungen von speziellen Befehlen enthält. Sie können die Array-Notation verwenden, z. B. $a[0] oder $warning[1,2], um auf bestimmte in der Variablen gespeicherte Warnungen zu verweisen.
HINWEIS: Der WarningVariable-Parameter erfasst keine Warnungen aus geschachtelten Aufrufen in Funktionen oder Skripts.
BESCHREIBUNG DER RISIKOMANAGEMENT-PARAMETER
-WHATIF[:{$TRUE | $FALSE}]
Alias: wi
Zeigt eine Meldung an, welche die Auswirkung des Befehls beschreibt, anstatt den Befehl auszuführen.
Der WhatIf-Parameter überschreibt den Wert der $WhatIfPreference-Variablen für den aktuellen Befehl. Da der Standardwert der $WhatIfPreference-Variablen 0 (deaktiviert) ist, wird das WhatIf-Verhalten nicht ohne den WhatIf-Parameter aktiviert. Um weitere Informationen zu erhalten, geben Sie den folgenden Befehl ein:
Get-Help about_Preference_Variables
Gültige Werte:
$true (-WhatIf:$true). Has the same effect as -WhatIf.
$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
that results when the value of the $WhatIfPreference variable
is 1.
Beispielsweise verwendet den folgenden Befehl den WhatIf-Parameter in einem Remove-Item-Befehl:
PS> Remove-Item Date.csv -WhatIf
Statt das Element entfernen, listet Windows PowerShell die Vorgänge auf, die es ausführen würde, sowie die Elemente, die betroffen wären. Dieser Befehl erzeugt die folgende Ausgabe:
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
-CONFIRM[:{$TRUE | $FALSE}]
Alias: cf
Fordert Sie vor der Ausführung des Befehls zum Bestätigen auf.
Der Confirm-Parameter überschreibt den Wert der $ConfirmPreference-Variablen für den aktuellen Befehl. Der Standardwert ist „High“. Um weitere Informationen zu erhalten, geben Sie den folgenden Befehl ein:
Get-Help about_Preference_Variables
Gültige Werte:
$true (-Confirm:$true). Has the same effect as -Confirm.
$false(-Confirm:$false). Suppresses automatic confirmation,
which occurs when the value of $ConfirmPreference is less than
or equal to the estimated risk of the cmdlet.
Beispielsweise verwendet den folgenden Befehl den Confirm-Parameter in einem Remove-Item-Befehl: Bevor das Element entfernt wird, listet Windows PowerShell die Vorgänge auf, die es ausführen würde, sowie die Elemente, die betroffen wären, und fordert zur Bestätigung auf.
PS C:\ps-test> Remove-Item tmp*.txt -Confirm
Dieser Befehl erzeugt die folgende Ausgabe:
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 Confirm-Antwortoptionen lauten wie folgt:
Yes (Y) Perform the action.
Yes to All (A) Perform all actions and suppress subsequent
Confirm queries for this command.
No (N): Do not perform the action.
No to All (L): Do not perform any actions and suppress subsequent
Confirm queries for this command.
Suspend (S): Pause the command and create a temporary session.
Help (?) Display help for these options.
Die Suspend-Option hält den Befehl an und erstellt eine temporäre geschachtelte Sitzung, in der Sie arbeiten können, bis Sie bereit sind, eine Confirm-Option auszuwählen. Die Befehlszeile für die geschachtelte Sitzung verfügt über zwei zusätzliche Caretzeichen (>>). Damit wird angegeben, dass es eine einen untergeordneten Vorgang des ursprünglichen übergeordneten-Befehls handelt. Sie können Befehle und Skripts in der geschachtelten Sitzung ausführen. Zum Beenden der geschachtelten Sitzung und um zu den Confirm-Optionen für den ursprünglichen Befehl zurückzukehren, geben Sie „exit“ ein.
Im folgenden Beispiel wird die Suspend-Option (S) verwendet, um einen Befehl vorübergehend anzuhalten, während der Benutzer in der Hilfe für einen Befehlsparameter nachliest. Nach dem Abrufen der benötigten Informationen gibt der Benutzer „exit“ ein, um die geschachtelte Befehlszeile zu beenden und wählt dann die Antwort „Yes“ (y) für die Confirm-Abfrage.
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 (default 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
SIEHE AUCH
about_Preference_Variables
Write-Debug
Write-Warnung
Write-Error
Write-Verbose