about_Parameters_Default_Values
Letzte Aktualisierung: Mai 2014
Betrifft: Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
THEMA
about_Parameters_Default_Values
KURZE BESCHREIBUNG
Beschreibt, wie benutzerdefinierte Standardwerte für die Parameter von Cmdlets und erweiterten Funktionen festgelegt werden.
LANGE BESCHREIBUNG
Mit der $PSDefaultParameterValues-Voreinstellungsvariablen können benutzerdefinierte Standardwerte für alle Cmdlets oder erweiterten Funktionen festlegen. Cmdlets und Funktionen verwenden die benutzerdefinierten Standardwerte, es sei denn, Sie geben einen anderen Wert im Befehl an.
Die Autoren von Cmdlets und erweiterten Funktionen legen die Standardwerte für ihre Parameter fest. In der Regel sind die vorgegebenen Standardwerte praktisch, doch sie sind möglicherweise nicht für alle Umgebungen geeignet.
Dieses Feature ist besonders nützlich, wenn Sie denselben alternativen Parameterwert fast bei jeder Verwendung des Befehls angeben müssen oder wenn ein bestimmter Parameterwert sich schwer merken lässt, z. B. der Name eines E-Mail-Servers oder die GUID des Projekts.
Wenn der gewünschte Standardwert vorhersehbar abweicht, können Sie einen Skriptblock festlegen, der unter verschiedenen Bedingungen unterschiedliche Standardwerte für einen Parameter bereitstellt.
$PSDefaultParameterValues wurde mit Windows PowerShell 3.0 eingeführt.
SYNTAX
Die Syntax der $PSDefaultParameterValues-Voreinstellungsvariablen lautet wie folgt:
$PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"="<DefaultValue>"}
$PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"={<ScriptBlock>}}
$PSDefaultParameterValues["Disabled"]=$true | $false
Platzhalterzeichen sind in den CmdletName- und ParameterName-Werten zulässig.
Der Wert von $PSDefaultParameterValues ist ein System.Management.Automation.DefaultParameterDictionary, eine Art Hash-Tabelle, die das Format von Schlüsseln überprüft. Geben Sie eine Hash-Tabelle an, in der der Schlüssel aus dem durch einen Doppelpunkt (:) voneinander getrennten Cmdlet-Namen und dem Parameternamen besteht, und der Wert ist der benutzerdefinierte Standardwert.
Um Einträgen aus $PSDefaultParameterValues festzulegen, zu ändern, hinzufügen oder zu entfernen, verwenden Sie die Methoden, die Sie verwenden würden, um eine standardmäßige Hash-Tabelle zu bearbeiten.
Der <CmdletName> muss der Name eines Cmdlets oder der Namen einer erweiterten Funktion sein, das bzw. die das CmdletBinding-Attribut verwendet. Sie können $PSDefaultParameterValues nicht verwenden, um Standardwerte für Skripts oder einfache Funktionen festzulegen.
Der Standardwert kann ein Objekt oder einen Skriptblock sein. Wenn der Wert einen Skriptblock ist, wertet Windows PowerShell den Skriptblock aus und verwendet das Ergebnis als den Parameterwert. Wenn der angegebene Parameter einen Skriptblock-Wert akzeptiert, müssen Sie den Skriptblock-Wert in einen zweiten Satz von geschweiften Klammern einschließen, z. B.: $PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }
Informationen zu Hash-Tabellen finden Sie unter „about_Hash_Tables“. Informationen zu Skriptblöcken finden Sie unter „about_Script_Blocks“. Informationen zu Voreinstellungsvariablen finden Sie unter „about_Preference_Variables“.
BEISPIELE
Der folgende Befehl legt einen benutzerdefinierten Standardwert für den SmtpServer-Parameter des Send-MailMessage-Cmdlets fest.
$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"}
Verwenden Sie zum Festlegen von Standardwerten für mehrere Parameter ein Semikolon (;), um jedes Paar vom Typ Name-Wert voneinander zu trennen. Der folgende Befehl fügt einen benutzerdefinierten Standardwert für den LogName-Parameter des Get-WinEvent-Cmdlets hinzu.
$PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
"Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"}
Sie können Platzhalterzeichen im Namen des Cmdlets und im Parameter verwenden. Der folgende Befehl legt den allgemeinen Verbose-Parameter in allen Befehlen auf „$true“ fest. Verwenden Sie zum Festlegen von Werten für Switch-Parameter, wie z. B. Verbose, „$true“ und „$false“.
$PSDefaultParameterValues = @{"*:Verbose"=$true}
Wenn ein Parameter mehrere Werte (ein Array) akzeptiert, können Sie mehrere Werte als Standardwert festlegen. Der folgende Befehl legt den Standardwert des ComputerName-Parameters des Invoke-Command-Cmdlets auf „Server01“ und „Server02“ fest.
$PSDefaultParameterValues = @{"Invoke-Command:ComputerName"="Server01","Server02"}
Mithilfe eines Skriptblocks können Sie unterschiedliche Standardwerte für einen Parameter unter verschiedenen Bedingungen festlegen. Windows PowerShell wertet den Skriptblock aus und verwendet das Ergebnis als den Standardparameterwert.
Der folgende Befehl legt den Standardwert des Autosize-Parameters des Format-Table-Cmdlets auf „$true“ fest, wenn das Host-Programm die Windows PowerShell-Konsole ist.
$PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name –eq "ConsoleHost"){$true}}}
Wenn ein Parameter einen Skriptblock-Wert akzeptiert, müssen Sie den Skriptblock in einem zusätzlichen Satz von geschweiften Klammern einschließen. Wenn Windows PowerShell den äußeren Skriptblock auswertet, ist das Ergebnis der innere Skriptblock, der als Standardparameterwert festgelegt ist.
Der folgende Befehl legt den Standardwert des SkriptBlock-Parameters von Invoke-Command fest. Da der Skriptblock in einen zweiten Satz von geschweiften Klammern eingeschlossen ist, wird der eingeschlossene Skriptblock an das Invoke-Command-Cmdlet übergeben.
$PSDefaultParameterValues=@{"Invoke-Command:ScriptBlock"={{Get-EventLog –Log System}}}
FESTLEGEN VON $PSDefaultParameterValues
$PSDefaultParameterValues ist eine Voreinstellungsvariable; sie ist also nur in der Sitzung vorhanden, in der sie festgelegt wurde. Sie verfügt über keinen Standardwert.
Um $PSDefaultParameterValues festzulegen, geben Sie den Variablennamen und ein oder mehrere Schlüssel-Wert-Paare in die Befehlszeile ein.
Wenn Sie einen anderen $PSDefaultParameterValues-Befehl eingeben, ersetzt dessen Wert den ursprünglichen Wert. Das Original wird nicht beibehalten.
Um $PSDefaultParameterValues für zukünftige Sitzungen zu speichern, fügen Sie einen $PSDefaultParameterValues-Befehl zu Ihrem Windows PowerShell-Profil hinzu. Weitere Informationen finden Sie unter „about_Profiles“.
ABRUFEN VON $PSDefaultParameterValues
Um den Wert von $PSDefaultParameterValues abzurufen, geben Sie an der Eingabeaufforderung Folgendes ein: $PSDefaultParameterValues
Mit dem erste Befehl wird beispielsweise der Wert von $PSDefaultParameterValues festgelegt. Der zweite Befehl ruft den Wert von $PSDefaultParameterValues ab.
PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
"Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational";
"Get-*:Verbose"=$true}
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
Um den Wert eines <CmdletName:ParameterName>-Schlüssels abzurufen, verwenden Sie die folgende Befehlssyntax:
$PSDefaultParameterValues["<CmdletName:ParameterName>"]
Beispiel:
PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
Server01AB234x5
HINZUFÜGEN VON WERTEN ZU $PSDefaultParameterValues
Verwenden Sie zum Hinzufügen oder Entfernen von Werten zu bzw. aus $PSDefaultParameterValues die Methoden, die Sie für eine standardmäßige Hash-Tabelle verwenden würden.
Verwenden Sie z. B. zum Hinzufügen eines Werts zu $PSDefaultParameterValues, ohne die vorhandenen Werte zu beeinträchtigen, die Add-Methode für Hash-Tabellen.
Die Syntax der Add-Methode lautet wie folgt:
<HashTable>.Add(Key, Value)
wobei der Schlüssel „<CmdletName>:<ParameterName>“ ist und der Wert der Wert des Parameters ist.
Verwenden Sie das folgende Befehlsformat, um die Add-Methode für $PSDefaultParameterValues aufzurufen. Achten Sie darauf, dass Sie ein Komma (,) verwenden, um den Schlüssel von dem Wert zu trennen, anstatt einem Gleichheitszeichen (=).
$PSDefaultParameterValues.Add("<CmdletName>:<ParameterName>", "<ParameterValue>")
Beispielsweise fügt der folgende Befehl „PowerShell“ als Standardwert des Name-Parameters des Get-Process-Cmdlets hinzu.
$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")
Das folgende Beispiel zeigt die Auswirkungen dieses Befehls.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Get-Process:Name PowerShell
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
ENTFERNEN VON WERTEN AUS $PSDefaultParameterValues
Um einen Wert aus $PSDefaultParameterValues zu entfernen, verwenden Sie die Remove-Methode für Hash-Tabellen.
Die Syntax der Remove-Methode lautet wie folgt:
<HashTable>.Remove(Key)
Verwenden Sie das folgende Befehlsformat, um die Remove-Methode für $PSDefaultParameterValues aufzurufen.
$PSDefaultParameterValues.Remove("<CmdletName>:<ParameterName>")
Der folgende Befehl entfernt z. B. den Name-Parameter des Get-Process-Cmdlets und seine Werte.
$PSDefaultParameterValues.Remove("Get-Process:Name")
Das folgende Beispiel zeigt die Auswirkungen dieses Befehls.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Get-Process:Name PowerShell
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name")
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
ÄNDERN VON WERTEN IN $PSDefaultParameterValues
Um einen Wert in $PSDefaultParameterValues zu ändern, verwenden Sie das folgende Befehlsformat.
$PSDefaultParameterValues["CmdletName:ParameterName"]="<NewValue>"
Das folgende Beispiel zeigt die Auswirkungen dieses Befehls.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server01AB234x5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5"
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Send-MailMessage:SmtpServer Server0000cabx5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
DEAKTIVIEREN UND REAKTIVIEREN VON $PSDefaultParameterValues
Sie können $PSDefaultParameterValues vorübergehend deaktivieren und dann wieder reaktivieren. Dies ist sehr nützlich, wenn Sie Skripts ausführen, die verschiedene Standardparameterwerte annehmen können.
Um $PSDefaultParameterValues zu deaktivieren, fügen Sie einen Schlüssel „Disabled“ mit einem Wert „$True“ hinzu.
Beispiel:
$PSDefaultParameterValues.Add("Disabled", $true)
- or -
$PSDefaultParameterValues[Disabled]=$true
Die anderen Werte in $PSDefaultParameterValues werden beibehalten, sind aber nicht mehr wirksam.
PS C:\> $PSDefaultParameterValues
Name Value
---- -----
Disabled True
Send-MailMessage:SmtpServer Server0000cabx5
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get*:Verbose True
Um $PSDefaultParameterValues zu reaktivieren, entfernen Sie den Schlüssel „Disabled“ oder ändern den Wert des Schlüssels „Disabled“ zu „$False“.
$PSDefaultParameterValues.Remove("Disabled")
- or -
$PSDefaultParameterValues[Disabled]=$false
Der vorherige Wert von $PSDefaultParameterValues ist damit wieder wirksam.
SCHLÜSSELWÖRTER
about_PSDefaultParameterValues
about_Parameters_DefaultValues
about_DefaultValues
SIEHE AUCH
about_Hash_Tables
about_Preference_Variables
about_Profiles
about_Script_Blocks