Über CommonParameters

KURZE BESCHREIBUNG

Beschreibt die Parameter, die mit jedem Cmdlet verwendet werden können.

LANGE BESCHREIBUNG

Die allgemeinen Parameter sind eine Reihe von Cmdlet-Parametern, die Sie mit jedem cmdlet verwenden können. Sie werden von PowerShell implementiert, nicht vom Cmdlet-Entwickler, und sie sind automatisch für jedes Cmdlet verfügbar.

Sie können die allgemeinen Parameter für jedes Cmdlet verwenden, haben aber möglicherweise keine Auswirkungen auf alle Cmdlets. Wenn ein Cmdlet z. B. keine ausführliche Ausgabe generiert, hat die Verwendung des allgemeinen Parameters Ausführlichkeit keine Auswirkungen.

Die allgemeinen Parameter sind auch für erweiterte Funktionen verfügbar, die das CmdletBinding-Attributoder das Parameter-Attribut verwenden, sowie für alle Workflows.

Mehrere allgemeine Parameter überschreiben Systemstandards oder -einstellungen, die Sie mithilfe der PowerShell-Einstellungsvariablen festgelegt haben. Im Gegensatz zu den Einstellungsvariablen wirken sich die allgemeinen Parameter nur auf die Befehle aus, in denen sie verwendet werden.

Zusätzlich zu den allgemeinen Parametern bieten viele Cmdlets die Parameter "WhatIf " und "Confirm zur Risikominderung" an. Cmdlets, die ein Risiko für das System oder benutzerspezifische Daten beinhalten, bieten in der Regel diese Parameter an.

In der folgenden Liste werden die allgemeinen Parameter angezeigt. Ihre Aliase werden in Klammern aufgeführt.

• Debug- (db)
• FehlerAktion (ea)
• FehlerVariable (ev)
• InformationAction (infa)
• InformationVariable (iv)
• OutVariable (ov)
• OutBuffer (ob)
• PipelineVariable (pv)
• Ausführlich (vb)
• WarnungAktion (wa)
• WarnungVariable (wv)

Die Risikominderungsparameter sind:

• WaswäreWenn (wi)
• Bestätigen (cf)

Weitere Informationen finden Sie unter about_Preference_Variables.

BESCHREIBUNGEN ALLGEMEINER PARAMETER

Fehlersuche

Der Alias für Debug ist db.

Zeigt Details auf Programmiererebene zum Vorgang an, der vom Befehl ausgeführt wird. Dieser Parameter funktioniert nur, wenn der Befehl eine Debugmeldung generiert. Dieser Parameter funktioniert beispielsweise, wenn ein Befehl das cmdlet Write-Debug enthält.

Der Parameter Debug überschreibt den Wert der $DebugPreference Variablen für den aktuellen Befehl und legt den Wert von $DebugPreference auf Continue fest. Da der Standardwert der $DebugPreference Variablen SilentlyContinue ist, werden Debugmeldungen standardmäßig nicht angezeigt.

-Debug:$true hat die gleiche Wirkung wie -Debug. Wird verwendet -Debug:$false , um die Anzeige von Debugmeldungen zu unterdrücken, wenn $DebugPreferencedies nicht "SilentlyContinue" ist, was die Standardeinstellung ist.

FehlerAktion

Der Alias für ErrorAction ist ea.

Bestimmt, wie das Cmdlet auf einen nicht beendeten Fehler des Befehls reagiert. Dieser Parameter funktioniert nur, wenn der Befehl einen nicht beendeten Fehler generiert, z. B. solche aus dem Cmdlet Write-Error.

Der ErrorAction-Parameter überschreibt den Wert der $ErrorActionPreference Variablen für den aktuellen Befehl. Da der Standardwert der $ErrorActionPreference Variablen "Weiter" lautet, 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 Zeigen Sie die Fehlermeldung an und fahren Sie mit der Ausführung des Befehls fort. Continue ist die Standardeinstellung.

-ErrorAction:Ignore unterdrückt die Fehlermeldung und führt den Befehl weiter aus. Im Gegensatz zu SilentlyContinue fügt Ignore die Fehlermeldung nicht zur $Error automatischen Variablen hinzu. Der Wert "Ignorieren" wird in PowerShell 3.0 eingeführt.

-ErrorAction:Inquire zeigt die Fehlermeldung an und fordert Sie zur Bestätigung auf, bevor Sie die Ausführung fortsetzen. Dieser Wert wird selten verwendet.

-ErrorAction:SilentlyContinue unterdrückt die Fehlermeldung und führt den Befehl weiter aus.

-ErrorAction:Stop zeigt die Fehlermeldung an und beendet die Ausführung des Befehls.

-ErrorAction:Suspend wird in PowerShell Core nicht unterstützt, da es nur für Workflows verfügbar ist.

FehlerVariable

Der Alias für ErrorVariable ist ev.

ErrorVariable speichert Fehlermeldungen über den Befehl in der angegebenen Variablen und in der $Error automatischen Variablen. Geben Sie den folgenden Befehl ein, um weitere Informationen zu erhalten:

Get-Help about_Automatic_Variables

Standardmäßig überschreiben neue Fehlermeldungen Fehlermeldungen, die bereits in der Variablen gespeichert sind. Um die Fehlermeldung an den Variableninhalt anzuhängen, geben Sie ein Pluszeichen (+) vor dem Variablennamen ein.

Der folgende Befehl erstellt z. B. die $a Variable und speichert dann alle Darin enthaltenen Fehler:

Get-Process -Id 6 -ErrorVariable a

Mit dem folgenden Befehl werden der variablen $a Fehlermeldungen hinzugefügt:

Get-Process -Id 2 -ErrorVariable +a

Der folgende Befehl zeigt den Inhalt von $aan:

$a

Sie können diesen Parameter verwenden, um eine Variable zu erstellen, die nur Fehlermeldungen von bestimmten Befehlen enthält. Die $Error automatische Variable enthält Fehlermeldungen aller Befehle in der Sitzung. Sie können arraynotation verwenden, z. B. $a[0] oder $error[1,2], um auf bestimmte Fehler zu verweisen, die in den Variablen gespeichert sind.

InformationAktion

Der Alias für InformationAction ist ia.

In PowerShell 5.0 eingeführt. Innerhalb des Befehls oder Skripts, in dem er verwendet wird, überschreibt der allgemeine InformationAction-Parameter den Wert der $InformationPreference Einstellungsvariable, die standardmäßig auf SilentlyContinue festgelegt ist. Wenn Sie in einem Skript mit Write-Information verwenden, Write-Information werden Werte abhängig vom Wert des InformationAction-Parameters angezeigt. Weitere Informationen zu $InformationPreference finden Sie unter about_Preference_Variables.

-InformationAction:Stop stoppt einen Befehl oder ein Skript an einem Vorkommen des befehls Write-Information.

-InformationAction:Ignore unterdrückt die Informationsmeldung und führt den Befehl weiter aus. Im Gegensatz zu SilentlyContinue wird die Informationsmeldung von Ignore vollständig vergessen; die Informationsmeldung wird dem Informationsdatenstrom nicht hinzugefügt.

-InformationAction:Inquire zeigt die Informationsmeldung an, die Sie in einem Write-Information-Befehl angeben, und fragt dann, ob Sie den Vorgang fortsetzen 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 (Standardeinstellung), und das Skript wird ohne Unterbrechung fortgesetzt.

InformationVariable

Der Alias für InformationVariable ist iv.

In PowerShell 5.0 eingeführt. 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 Die Werte werden in Abhängigkeit vom Wert des allgemeinen Parameters InformationAction angezeigt. Wenn Sie den allgemeinen Parameter InformationAction nicht hinzufügen, Write-Information werden Zeichenfolgen abhängig vom Wert der $InformationPreference Einstellungsvariablen angezeigt. Weitere Informationen zu $InformationPreference finden Sie unter about_Preference_Variables.

OutBuffer

Der Alias für OutBuffer ist ob und nimmt den Wert System.Int32 an.

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, sobald sie generiert werden.

Dieser Ressourcenverwaltungsparameter wurde für erweiterte Benutzer entwickelt. Wenn Sie diesen Parameter verwenden, sendet PowerShell Daten in Batches von OutBuffer + 1an das nächste Cmdlet.

Das folgende Beispiel wechselt zwischen ForEach-Object Prozessblöcken, die das cmdlet Write-Host 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

Der Alias für OutVariable ist ov.

Speichert Ausgabeobjekte aus dem Befehl in der angegebenen Variablen zusätzlich zum Senden der Ausgabe entlang der Pipeline.

Wenn Sie die Ausgabe der Variablen hinzufügen möchten, geben Sie vor dem Variablennamen ein Pluszeichen (+) ein, anstatt alle dort möglicherweise bereits gespeicherten Ausgaben zu ersetzen.

Beispielsweise erstellt der folgende Befehl die $out Variable und speichert das Prozessobjekt darin:

Get-Process PowerShell -OutVariable out

Mit dem folgenden Befehl wird das Prozessobjekt der variablen $out hinzugefügt:

Get-Process iexplore -OutVariable +out

Der folgende Befehl zeigt den Inhalt der $out Variablen an:

$out

Pipeline-Variable

Der Alias für PipelineVariable ist pv und nimmt einen Zeichenfolgenwert an.

PipelineVariable speichert den Wert des aktuellen Pipelineelements als Variable für jeden benannten Befehl, während er die Pipeline durchläuft.

Gültige Werte sind Zeichenfolgen, identisch mit variablen Namen.

Im Folgenden sehen Sie ein Beispiel für die Funktionsweise von PipelineVariable . In diesem Beispiel wird der Parameter PipelineVariable einem Foreach-Object Befehl hinzugefügt, um die Ergebnisse des Befehls in Variablen zu speichern. Ein Zahlenbereich von 1 bis 10 wird in den ersten Foreach-Object Befehl weitergeleitet, 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 weitergeleiteten Befehle, dargestellt durch die Variablen Left und Right, mithilfe eines Multiplikationsoperators verarbeitet. Der Befehl weist an, dass Objekte, die in den Variablen "Links " und "Rechts " gespeichert sind, multipliziert werden sollen, und gibt an, dass die Ergebnisse als "Linkes Bereichselement * Rechtes Bereichselement = Produkt" 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

Der Alias für Verbose ist vb.

Zeigt detaillierte Informationen über den 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 ausgibt. Dieser Parameter funktioniert beispielsweise, wenn ein Befehl das cmdlet Write-Verbose enthält.

Der Verbose-Parameter überschreibt den Wert der $VerbosePreference Variablen für den aktuellen Befehl. Da der Standardwert der $VerbosePreference Variablen SilentlyContinueist, werden ausführliche Nachrichten standardmäßig nicht angezeigt.

-Verbose:$true hat die gleiche Wirkung wie -Verbose

-Verbose:$false unterdrückt die Anzeige von ausführlichen Meldungen. Verwenden Sie diesen Parameter, wenn der Wert von $VerbosePreference " SilentlyContinue " (Standardeinstellung) nicht lautet.

WarnungAktion

Der Alias für WarningAction ist wa.

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 cmdlet Write-Warning enthält.

Der WarningAction-Parameter überschreibt den Wert der $WarningPreference Variablen für den aktuellen Befehl. Da der Standardwert der $WarningPreference Variablen "Weiter" lautet, werden Warnungen angezeigt, und die Ausführung wird fortgesetzt, es sei denn, Sie verwenden den WarningAction-Parameter .

-WarningAction:Continue zeigt die Warnmeldungen an und führt den Befehl weiterhin aus. Continue ist die Standardeinstellung.

-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 führt den Befehl weiter aus.

-WarningAction:Stop zeigt die Warnmeldung an und beendet die Ausführung des Befehls.

WarnungVariable

Der Alias für WarningVariable ist wv.

Speichert Warnungen zum Befehl in der angegebenen Variablen.

Alle generierten Warnungen werden in der Variablen gespeichert, auch wenn die Warnungen nicht für den Benutzer angezeigt werden.

Wenn Sie die Warnungen an den Variableninhalt anfügen möchten, geben Sie vor dem Variablennamen ein Pluszeichen (+) ein, anstatt alle Warnungen zu ersetzen, die dort möglicherweise bereits gespeichert sind.

Der folgende Befehl erstellt z. B. die $a Variable und speichert dann alle darin enthaltenen Warnungen:

Get-Process -Id 6 -WarningVariable a

Mit dem folgenden Befehl werden der variablen $a Warnungen hinzugefügt:

Get-Process -Id 2 -WarningVariable +a

Der folgende Befehl zeigt den Inhalt von $aan:

$a

Mit diesem Parameter können Sie eine Variable erstellen, die nur Warnungen aus bestimmten Befehlen enthält. Sie können arraynotation verwenden, z. B. $a[0] oder $warning[1,2], um auf bestimmte Warnungen zu verweisen, die in der Variablen gespeichert sind.

Beschreibungen des Risikomanagementparameters

Waswärewenn?

Der Alias für WhatIf ist wi.

Zeigt eine Meldung an, die den Effekt 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, erfolgt das WhatIf-Verhalten nicht ohne den WhatIf-Parameter . Geben Sie den folgenden Befehl ein, um weitere Informationen zu erhalten:

Get-Help about_Preference_Variables

-WhatIf:$true hat die gleiche Wirkung wie -WhatIf.

-WhatIf:$false unterdrückt das automatische WhatIf-Verhalten, das beim Wert der variablen $WhatIfPreference 1 resultiert.

Der folgende Befehl verwendet z. B. den -WhatIf-Parameter in einem Remove-Item Befehl:

Remove-Item Date.csv -WhatIf

Statt das Element zu entfernen, listet PowerShell die Vorgänge auf, die es tun 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".

Bestätigen

Der Alias für Confirm lautet cf.

Fordert Sie zur Bestätigung auf, bevor Sie den Befehl ausführen.

Der Parameter Confirm überschreibt den Wert der $ConfirmPreference Variablen für den aktuellen Befehl. Der Standardwert ist true. Geben Sie den folgenden Befehl ein, um weitere Informationen zu erhalten:

Get-Help 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.

Im folgenden Befehl wird z. B. der Parameter Confirm mit einem Remove-Item Befehl verwendet. Bevor Sie das Element entfernen, listet PowerShell die Vorgänge auf, die dies tun würde, und die Elemente, die betroffen wären, und fordert die Genehmigung an.

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 zum Bestätigen lauten wie folgt:

Die Option Anhalten setzt den Befehl in die Warteschleife und erstellt eine temporäre geschachtelte Sitzung, in der Sie arbeiten können, bis Sie bereit sind , eine Bestätigungsoption auszuwählen. 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 ist. Sie können Befehle und Skripts in der geschachtelten Sitzung ausführen. Um die verschachtelte Sitzung zu beenden und zu den Bestätigungsoptionen 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 für einen Befehlsparameter überprüft. Nachdem er die erforderlichen Informationen erhalten hat, gibt der Benutzer "exit" ein, um die geschachtelte Eingabeaufforderung zu beenden, und wählt dann die Antwort Ja (y) auf die Bestätigungsabfrage 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

SIEHE AUCH

about_Preference_Variables

Schreiben-Debuggen

Schreib-Warnung

Schreibfehler-

Schreiben-Ausführlich