about_Parameters_Default_Values

Kurzbeschreibung

Beschreibt, wie benutzerdefinierte Standardwerte für Cmdlet-Parameter, erweiterte Funktionen und Skripts festgelegt werden.

Lange Beschreibung

Mit der einstellungsvariablen $PSDefaultParameterValues können Sie benutzerdefinierte Standardparameterwerte für jedes Cmdlet, eine erweiterte Funktion oder ein Skript angeben, das das attribut CmdletBinding verwendet. Die definierten Werte werden verwendet, es sei denn, Sie geben andere Werte in der Befehlszeile an.

Dieses Feature ist in den folgenden Szenarien nützlich:

• Angeben desselben Parameterwerts bei jeder Verwendung des Befehls
• Angeben eines bestimmten Parameterwerts, der schwer zu merken ist, z. B. einen E-Mail-Servernamen oder eine Projekt-GUID

Die variable $PSDefaultParameterValues hat keinen Standardwert. Um die Einstellungen für die Verwendung in zukünftigen Sitzungen zu speichern, fügen Sie die variable Zuweisung zu Ihrem PowerShell-Profil hinzu.

$PSDefaultParameterValues wurde in PowerShell 3.0 eingeführt.

Syntax

Die $PSDefaultParameterValues-Variable ist ein Objekttyp von System.Management.Automation.DefaultParameterDictionary. Der DefaultParameterDictionary-Typ ist eine Hashtable mit einer zusätzlichen Überprüfung für das Format der Schlüssel. Die Hashtabelle enthält Schlüssel-Wert-Paare, wobei:

• der Schlüssel hat das Format CommandName:ParameterName
• der Wert ist der Standardwert für den Parameter oder ein ScriptBlock, der den Standardwert zurückgibt

Für den Schlüssel muss CommandName der Name eines Cmdlets, einer erweiterten Funktion oder einer Skriptdatei sein, das oder die das Attribut CmdletBinding verwendet. Der Skriptname muss dem von (Get-Command -Name .\script.ps1).Namegemeldeten Namen entsprechen.

Der Wert kann ein Objekt eines Typs sein, der mit dem Parameter kompatibel ist, oder ein ScriptBlock, das einen solchen Wert zurückgibt. Wenn der Wert ein Skriptblock ist, wertet PowerShell den Skriptblock aus und verwendet das Ergebnis für den Parameterwert. Wenn der angegebene Parameter den Typ ScriptBlock erwartet, müssen Sie den Wert in eine andere Gruppe von geschweiften Klammern einschließen. Wenn PowerShell den äußeren ScriptBlockauswertet, ist das Ergebnis der innere ScriptBlock. Das innere ScriptBlock- wird zum neuen Standardparameterwert.

Zum Beispiel:

$PSDefaultParameterValues = @{
    'Invoke-Command:ScriptBlock' = { {Get-Process} }
}

Examples

Verwenden Sie die methoden Add() und Remove(), um ein bestimmtes Schlüssel-Wert-Paar aus $PSDefaultParameterValues hinzuzufügen oder zu entfernen, ohne andere vorhandene Schlüsselwertpaare zu überschreiben.

$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue')
$PSDefaultParameterValues.Remove('CmdletName:ParameterName')

Verwenden Sie den Indizierungs- oder Memberzugriff, um den Wert eines vorhandenen Schlüsselwertpaars zu ändern. Zum Beispiel:

$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2'
$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1'

Zuweisen von Werten zu $PSDefaultParameterValues

Um Standardwerte für Cmdlet-Parameter zu definieren, weisen Sie der variablen $PSDefaultParameterValues eine Hashtable zu, die die entsprechenden Schlüsselwertpaare enthält. Die Hashtabelle kann mehrere Schlüsselwertpaare enthalten. In diesem Beispiel werden Standardwerte für die tasten Send-MailMessage:SmtpServer und Get-WinEvent:LogName festgelegt.

$PSDefaultParameterValues = @{
  'Send-MailMessage:SmtpServer'='Server123'
  'Get-WinEvent:LogName'='Microsoft-Windows-PrintService/Operational'
}

Die Cmdlet- und Parameternamen können Wildcardzeichen enthalten. Verwenden Und $true festlegen Sie $false Werte für Switchparameter, z. B. "Verbose". In diesem Beispiel wird der allgemeine Parameter Verbose für alle Befehle auf $true gesetzt.

$PSDefaultParameterValues = @{'*:Verbose'=$true}

Wenn ein Parameter mehrere Werte akzeptiert, können Sie mehrere Standardwerte mithilfe eines Arrays bereitstellen. In diesem Beispiel wird der Standardwert des Schlüssels Invoke-Command:ComputerName auf ein Array festgelegt, das die Zeichenfolgen Server01 und Server02enthält.

$PSDefaultParameterValues = @{
  'Invoke-Command:ComputerName' = 'Server01', 'Server02'
}

Definierte Werte anzeigen

Betrachten Sie die folgende Definition von $PSDefaultParameterValues:

$PSDefaultParameterValues = @{
  'Send-MailMessage:SmtpServer' = 'Server123'
  'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational'
  'Get-*:Verbose' = $true
}

Sie können die definierten Werte anzeigen, indem Sie in der Befehlszeile $PSDefaultParameterValues eingeben.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Sie können den Index- oder Memberzugriff verwenden, um einen bestimmten Wert zu erhalten.

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation
Server123
PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation
True

Verwenden Sie einen Skriptblock für den Standardwert.

Sie können einen Skriptblock verwenden, um unterschiedliche Standardwerte für einen Parameter unter unterschiedlichen Bedingungen anzugeben. PowerShell wertet den Skriptblock aus und verwendet das Ergebnis als Standardwert.

Die Format-Table:AutoSize-Taste setzt diesen Schalterparameter auf einen Standardwert von $true. Die if-Anweisung enthält eine Bedingung, dass der $Host.NameConsoleHostsein muss.

$PSDefaultParameterValues = @{
  'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} }
}

Wenn ein Parameter einen ScriptBlock-Wert akzeptiert, schließen Sie den ScriptBlock in eine andere Gruppe von geschweiften Klammern ein. Wenn PowerShell den äußeren ScriptBlockauswertet, ist das Ergebnis der innere ScriptBlock. Das innere ScriptBlock- wird zum neuen Standardparameterwert.

$PSDefaultParameterValues = @{
  'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} }
}

Hinzufügen von Werten zu einer vorhandenen $PSDefaultParameterValues Variablen

Verwenden Sie zum Hinzufügen eines Werts zu $PSDefaultParameterValuesdie Add()-Methode. Das Hinzufügen eines Werts wirkt sich nicht auf die vorhandenen Werte der Hashtabelle aus. Verwenden Sie ein Komma (,), um den Schlüssel vom Wertzu trennen.

$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell')

Die im vorherigen Beispiel erstellte Hashtabelle wird mit einem neuen Schlüsselwertpaar aktualisiert.

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-Process:Name               PowerShell
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Entfernen Sie einen Wert aus $PSDefaultParameterValues

Um einen Wert aus $PSDefaultParameterValueszu entfernen, verwenden Sie die Remove()-Methode. Das Entfernen eines Werts wirkt sich nicht auf die vorhandenen Werte der Hashtabelle aus.

In diesem Beispiel wird das Schlüssel-Wert-Paar entfernt, das im vorherigen Beispiel hinzugefügt wurde.

PS> $PSDefaultParameterValues.Remove('Get-Process:Name')
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

Wert in $PSDefaultParameterValues ändern

Verwenden Sie die Indizierung oder den Memberzugriff, um den Standardwert eines vorhandenen Schlüsselwertpaars zu ändern. In diesem Beispiel wird der Standardwert für den schlüssel Send-MailMessage:SmtpServer in einen neuen Wert von ServerXYZgeändert.

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ'
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

Aktivieren oder Deaktivieren von $PSDefaultParameterValues

Sie können vorübergehend deaktivieren und dann erneut aktivieren $PSDefaultParameterValues. Das Deaktivieren $PSDefaultParameterValues ist nützlich, wenn Sie Skripts ausführen, die unterschiedliche Standardwerte für Parameter benötigen.

Um $PSDefaultParameterValues zu deaktivieren, fügen Sie einen Schlüssel von Disabled mit dem Wert $true hinzu. Die Werte in $PSDefaultParameterValues bleiben erhalten, werden jedoch nicht verwendet.

PS> $PSDefaultParameterValues.Add('Disabled', $true)
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Disabled                       True
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

Um $PSDefaultParameterValueserneut zu aktivieren, entfernen Sie den Disabled Schlüssel, oder ändern Sie den Wert des Disabled-Schlüssels in $false.

PS> $PSDefaultParameterValues.Disabled = $false
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Disabled                       False
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

Siehe auch

• about_CommonParameters
• about_Functions_Advanced
• about_Functions_CmdletBindingAttribute
• about_Hash_Tables
• about_Preference_Variables
• about_Profiles
• about_Script_Blocks