Informacje o wartościach domyślnych parametrówAbout Parameters Default Values

Krótki opisShort description

Opisuje sposób ustawiania niestandardowych wartości domyślnych dla parametrów poleceń cmdlet i zaawansowanych funkcji.Describes how to set custom default values for cmdlet parameters and advanced functions.

Długi opisLong description

$PSDefaultParameterValuesZmienna preferencji pozwala określić niestandardowe wartości domyślne dla każdego polecenia cmdlet lub funkcji zaawansowanej.The $PSDefaultParameterValues preference variable lets you specify custom default values for any cmdlet or advanced function. Polecenia cmdlet i funkcje zaawansowane używają niestandardowej wartości domyślnej, o ile nie zostanie określona inna wartość w poleceniu.Cmdlets and advanced functions use the custom default value unless you specify another value in the command.

Autorzy poleceń cmdlet i funkcji zaawansowanych ustawiają standardowe wartości domyślne dla ich parametrów.The authors of cmdlets and advanced functions set standard default values for their parameters. Zazwyczaj standardowe wartości domyślne są przydatne, ale mogą nie być odpowiednie dla wszystkich środowisk.Typically, the standard default values are useful, but they might not be appropriate for all environments.

Ta funkcja jest szczególnie przydatna, gdy należy określić tę samą alternatywną wartość parametru niemal za każdym razem, gdy używasz polecenia lub gdy określona wartość parametru jest trudna do zapamiętania, taka jak nazwa serwera poczty e-mail lub identyfikator GUID projektu.This feature is especially useful when you must specify the same alternate parameter value nearly every time you use the command or when a particular parameter value is difficult to remember, such as an email server name or project GUID.

Jeśli żądana wartość domyślna zmienia się w sposób predykcyjny, można określić blok skryptu, który zawiera różne wartości domyślne dla parametru w różnych warunkach.If the desired default value varies predictably, you can specify a script block that provides different default values for a parameter under different conditions.

$PSDefaultParameterValues wprowadzono w programie PowerShell 3,0.$PSDefaultParameterValues was introduced in PowerShell 3.0.

SkładniaSyntax

$PSDefaultParameterValuesZmienna jest tabelą skrótów, która weryfikuje format kluczy jako typ obiektu System. Management. Automation. DefaultParameterDictionary.The $PSDefaultParameterValues variable is a hash table that validates the format of keys as an object type of System.Management.Automation.DefaultParameterDictionary. Tablica skrótów zawiera pary klucz/wartość .The hash table contains Key/Value pairs. Klucz ma format CmdletName:ParameterName .A Key is in the format CmdletName:ParameterName. Wartość jest wartością DefaultValue lub ScriptBlock przypisaną do klucza.A Value is the DefaultValue or ScriptBlock assigned to the key.

Składnia $PSDefaultParameterValues zmiennej preferencji jest następująca:The syntax of the $PSDefaultParameterValues preference variable is as follows:

$PSDefaultParameterValues=@{"CmdletName:ParameterName"="DefaultValue"}

$PSDefaultParameterValues=@{ "CmdletName:ParameterName"={{ScriptBlock}} }

$PSDefaultParameterValues["Disabled"]=$True | $False

W wartościach CmdletName i ParameterName są dozwolone symbole wieloznaczne.Wildcard characters are permitted in the CmdletName and ParameterName values.

Aby ustawić, zmienić, dodać lub usunąć określoną parę klucz/wartość z $PSDefaultParameterValues , użyj metod do edycji standardowej tabeli skrótów.To set, change, add, or remove a specific Key/Value pair from $PSDefaultParameterValues, use the methods to edit a standard hash table. Na przykład metody dodawania i usuwania .For example, the Add and Remove methods. Te metody nie zastępują innych wartości w tabeli skrótów.These methods don't overwrite other values in the hash table.

Istnieje inna składnia, która nie zastępuje istniejącej $PSDefaultParameterValues tabeli skrótów.There's another syntax that doesn't overwrite an existing $PSDefaultParameterValues hash table. Aby dodać lub zmienić konkretną parę klucz/wartość , należy użyć następującej składni:To add or change a specific Key/Value pair, use the following syntax:

$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"

Polecenie CmdletName musi być nazwą polecenia cmdlet lub nazwą funkcji zaawansowanej, która używa atrybutu CmdletBinding .The CmdletName must be the name of a cmdlet or the name of an advanced function that uses the CmdletBinding attribute. Nie można użyć, $PSDefaultParameterValues Aby określić wartości domyślne dla skryptów lub prostych funkcji.You can't use $PSDefaultParameterValues to specify default values for scripts or simple functions.

Właściwość DefaultValue może być obiektem lub blokiem skryptu.The DefaultValue can be an object or a script block. Jeśli wartość jest blok skryptu, program PowerShell oblicza blok skryptu i używa wyniku jako wartości parametru.If the value is a script block, PowerShell evaluates the script block and uses the result as the parameter value. Gdy określony parametr akceptuje wartość bloku skryptu, należy ująć wartość bloku skryptu w drugim zestawie nawiasów klamrowych, na przykład:When the specified parameter accepts a script block value, enclose the script block value in a second set of braces, such as:

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

Więcej informacji można znaleźć w następujących dokumentach:For more information, see the following documents:

PrzykładyExamples

Jak ustawić $ PSDefaultParameterValuesHow to set $PSDefaultParameterValues

$PSDefaultParameterValues jest zmienną preferencji, dlatego istnieje tylko w sesji, w której jest ustawiona.$PSDefaultParameterValues is a preference variable, so it exists only in the session in which it's set. Nie ma wartości domyślnej.It has no default value.

Aby ustawić $PSDefaultParameterValues , wpisz nazwę zmiennej i jeden lub więcej par klucz/wartość .To set $PSDefaultParameterValues, type the variable name and one or more Key/Value pairs. Po uruchomieniu kolejne $PSDefaultParameterValues polecenie zastępuje istniejącą tabelę skrótów.If you run another $PSDefaultParameterValues command, it overwrites the existing hash table.

Aby zapoznać się z przykładami dotyczącymi sposobu zmiany par klucz-wartość bez zastępowania istniejących wartości w tabeli skrótów, zobacz jak dodać wartości do $ PSDefaultParameterValues lub zmienić wartości w $ PSDefaultParameterValues.For examples about how to change Key/Value pairs without overwriting existing hash table values, see How to add values to $PSDefaultParameterValues or How to change values in $PSDefaultParameterValues.

Aby zapisać $PSDefaultParameterValues w przyszłych sesjach, Dodaj $PSDefaultParameterValues polecenie do profilu programu PowerShell.To save $PSDefaultParameterValues for future sessions, add a $PSDefaultParameterValues command to your PowerShell profile. Aby uzyskać więcej informacji, zobacz about_Profiles.For more information, see about_Profiles.

Ustawianie niestandardowej wartości domyślnejSet a custom default value

Para klucz/wartość ustawia Send-MailMessage:SmtpServer klucz na niestandardową wartość domyślną Server123.The Key/Value pair sets the Send-MailMessage:SmtpServer key to a custom default value of Server123.

$PSDefaultParameterValues = @{
  "Send-MailMessage:SmtpServer"="Server123"
}

Ustaw wartości domyślne dla wielu parametrówSet default values for multiple parameters

Aby ustawić wartości domyślne dla wielu parametrów, rozdziel każdą parę klucz/wartość średnikiem ( ; ).To set default values for multiple parameters, separate each Key/Value pair with a semicolon (;). Send-MailMessage:SmtpServerKlucze i Get-WinEvent:LogName są ustawione na niestandardowe wartości domyślne.The Send-MailMessage:SmtpServer and Get-WinEvent:LogName keys are set to custom default values.

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

Użyj symboli wieloznacznych i parametrów przełącznikaUse wildcards and switch parameters

Nazwy poleceń cmdlet i parametrów mogą zawierać symbole wieloznaczne.The cmdlet and parameter names can contain wildcard characters. Użyj $True i, $False Aby ustawić wartości parametrów przełącznika, takich jak verbose.Use $True and $False to set values for switch parameters, such as Verbose. Parametr verbose wspólnego parametru ma ustawioną wartość $True dla wszystkich poleceń.The common parameter's Verbose parameter is set to $True for all commands.

$PSDefaultParameterValues = @{"*:Verbose"=$True}

Użyj tablicy dla wartości domyślnejUse an array for the default value

Jeśli parametr może akceptować wiele wartości, tablica, można ustawić wiele wartości jako wartości domyślne.If a parameter can accept multiple values, an array, you can set multiple values as the default values. Wartość domyślna Invoke-Command:ComputerName klucza jest ustawiona na wartość tablicy Serwer01 i Server02.The default value of the Invoke-Command:ComputerName key is set to an array value of Server01 and Server02.

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

Korzystanie z bloku skryptuUse a script block

Możesz użyć bloku skryptu, aby określić różne wartości domyślne dla parametru w różnych warunkach.You can use a script block to specify different default values for a parameter under different conditions. Program PowerShell oblicza blok skryptu i używa wyniku jako domyślnej wartości parametru.PowerShell evaluates the script block and uses the result as the default parameter value.

Format-Table:AutoSizeKlucz ustawia wartość domyślną true dla parametru Switch.The Format-Table:AutoSize key sets that switch parameter to a default value of True. IfInstrukcja zawiera warunek, który $host.Name musi być konsolą programu PowerShell, ConsoleHost.The If statement contains a condition that the $host.Name must be the PowerShell console, ConsoleHost.

$PSDefaultParameterValues=@{
  "Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$True}}
}

Jeśli parametr akceptuje wartość bloku skryptu, umieść blok skryptu w dodatkowym zestawie nawiasów klamrowych.If a parameter accepts a script block value, enclose the script block in an extra set of braces. Gdy program PowerShell oblicza zewnętrzny blok skryptu, wynikiem jest wewnętrzny blok skryptu i ustawiony jako wartość domyślna parametru.When PowerShell evaluates the outer script block, the result is the inner script block, and that is set as the default parameter value.

Invoke-Command:ScriptBlockKlucz ustawiony na wartość domyślną dziennika zdarzeń systemu , ponieważ blok skryptu jest ujęty w drugi zestaw nawiasów klamrowych.The Invoke-Command:ScriptBlock key set to a default value of the System event log because the script block is enclosed in a second set of braces. Wynik bloku skryptu jest przesyłany do Invoke-Command polecenia cmdlet.The result of the script block is passed to the Invoke-Command cmdlet.

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

Jak uzyskać $ PSDefaultParameterValuesHow to get $PSDefaultParameterValues

Wartości tabeli skrótów są wyświetlane, wprowadzając $PSDefaultParameterValues w wierszu polecenia programu PowerShell.The hash table values are displayed by entering $PSDefaultParameterValues at the PowerShell prompt.

$PSDefaultParameterValuesTabela skrótów jest ustawiana z trzema parami klucz/wartość .A $PSDefaultParameterValues hash table is set with three Key/Value pairs. Ta tabela skrótów jest używana w poniższych przykładach opisujących sposób dodawania, zmieniania i usuwania wartości z $PSDefaultParameterValues .This hash table is used in the following examples that describe how to add, change, and remove values from $PSDefaultParameterValues.

PS> $PSDefaultParameterValues = @{
  "Send-MailMessage:SmtpServer"="Server123"
  "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"
  "Get-*:Verbose"=$True
}

PS> $PSDefaultParameterValues

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

Aby uzyskać wartość określonego CmdletName:ParameterName klucza, należy użyć następującej składni:To get the value of a specific CmdletName:ParameterName key, use the following syntax:

$PSDefaultParameterValues["CmdletName:ParameterName"]

Na przykład, aby uzyskać wartość Send-MailMessage:SmtpServer klucza.For example, to get the value for the Send-MailMessage:SmtpServer key.

PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
Server123

Jak dodać wartości do $ PSDefaultParameterValuesHow to add values to $PSDefaultParameterValues

Aby dodać wartość do $PSDefaultParameterValues , użyj metody Add .To add a value to $PSDefaultParameterValues, use the Add method. Dodanie wartości nie ma wpływu na istniejące wartości w tabeli skrótów.Adding a value doesn't affect the hash table's existing values.

Użyj przecinka ( , ), aby oddzielić klucz od wartości.Use a comma (,) to separate the Key from the Value. Poniższa składnia pokazuje, jak używać metody Add dla $PSDefaultParameterValues .The following syntax shows how to use the Add method for $PSDefaultParameterValues.

PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue")

Tabela skrótów utworzona w poprzednim przykładzie jest aktualizowana przy użyciu nowej pary klucz/wartość .The hash table created in the prior example is updated with a new Key/Value pair. Metoda Add ustawia Get-Process:Name klucz na wartość PowerShell.The Add method sets the Get-Process:Name key to the value PowerShell.

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

Poniższa składnia wykonuje ten sam wynik.The following syntax accomplishes the same result.

$PSDefaultParameterValues["Get-Process:Name"]="PowerShell"

$PSDefaultParameterValuesZmienna wyświetla zaktualizowaną tabelę skrótów.The $PSDefaultParameterValues variable displays the updated hash table. Get-Process:NameDodano klucz.The Get-Process:Name key was added.

PS> $PSDefaultParameterValues

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

Jak usunąć wartości z $ PSDefaultParameterValuesHow to remove values from $PSDefaultParameterValues

Aby usunąć wartość z $PSDefaultParameterValues , należy użyć metody Remove tabel skrótów.To remove a value from $PSDefaultParameterValues, use the Remove method of hash tables. Usunięcie wartości nie ma wpływu na istniejące wartości w tabeli skrótów.Removing a value doesn't affect the hash table's existing values.

Poniższa składnia pokazuje, jak używać metody Remove w systemie $PSDefaultParameterValues .The following syntax shows how to use the Remove method on $PSDefaultParameterValues.

PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName")

W tym przykładzie tabela skrótów utworzona w poprzednim przykładzie została zaktualizowana w celu usunięcia pary klucz/wartość .In this example, the hash table created in the prior example is updated to remove a Key/Value pair. Metoda Remove usuwa Get-Process:Name klucz.The Remove method removes the Get-Process:Name key.

$PSDefaultParameterValues.Remove("Get-Process:Name")

$PSDefaultParameterValuesZmienna wyświetla zaktualizowaną tabelę skrótów.The $PSDefaultParameterValues variable displays the updated hash table. Get-Process:NameKlucz został usunięty.The Get-Process:Name key was removed.

PS> $PSDefaultParameterValues

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

Jak zmienić wartości w $ PSDefaultParameterValuesHow to change values in $PSDefaultParameterValues

Zmiany określonej wartości nie wpływają na istniejące wartości tabeli skrótów.Changes to a specific value don't affect existing hash table values. Aby zmienić określoną parę klucz/wartość w programie $PSDefaultParameterValues , należy użyć następującej składni:To change a specific Key/Value pair in $PSDefaultParameterValues, use the following syntax:

PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"

W tym przykładzie tabela skrótów utworzona w poprzednim przykładzie została zaktualizowana w celu zmiany pary klucz/wartość .In this example, the hash table created in the prior example is updated to change a Key/Value pair. Następujące polecenie zmienia Send-MailMessage:SmtpServer klucz na nową wartość ServerXYZ.The following command changes the Send-MailMessage:SmtpServer key to a new value of ServerXYZ.

$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ"

$PSDefaultParameterValuesZmienna wyświetla zaktualizowaną tabelę skrótów.The $PSDefaultParameterValues variable displays the updated hash table. Send-MailMessage:SmtpServerKlucz został zmieniony na nową wartość.The Send-MailMessage:SmtpServer key was changed to a new value.

PS> $PSDefaultParameterValues

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

Jak wyłączyć i ponownie włączyć $ PSDefaultParameterValuesHow to disable and re-enable $PSDefaultParameterValues

Można tymczasowo wyłączyć i ponownie włączyć $PSDefaultParameterValues .You can temporarily disable and then re-enable $PSDefaultParameterValues. Wyłączenie $PSDefaultParameterValues jest przydatne, jeśli używasz skryptów, które wymagają różnych domyślnych wartości parametrów.Disabling $PSDefaultParameterValues is useful if you're running scripts that need different default parameter values.

Aby wyłączyć $PSDefaultParameterValues , Dodaj klucz o Disabled wartości true.To disable $PSDefaultParameterValues, add a key of Disabled with a value of True. Wartości w $PSDefaultParameterValues są zachowywane, ale nie są skuteczne.The values in $PSDefaultParameterValues are preserved, but aren't effective.

PS> $PSDefaultParameterValues.Add("Disabled", $True)

Poniższa składnia wykonuje ten sam wynik.The following syntax accomplishes the same result.

PS> $PSDefaultParameterValues["Disabled"]=$True

$PSDefaultParameterValuesZmienna wyświetla zaktualizowaną tabelę skrótów z wartością Disabled klucza.The $PSDefaultParameterValues variable displays the updated hash table with the value for the Disabled key.

PS> $PSDefaultParameterValues

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

Aby ponownie włączyć $PSDefaultParameterValues , Usuń wyłączony klucz lub zmień wartość wyłączonego klucza na $False .To re-enable $PSDefaultParameterValues, remove the Disabled key or change the value of the Disabled key to $False. Poprzednia wartość $PSDefaultParameterValues jest skuteczna.The previous value of $PSDefaultParameterValues is effective again.

PS> $PSDefaultParameterValues.Remove("Disabled")

Poniższa składnia wykonuje ten sam wynik.The following syntax accomplishes the same result.

PS> $PSDefaultParameterValues["Disabled"]=$False

$PSDefaultParameterValuesZmienna wyświetla zaktualizowaną tabelę skrótów.The $PSDefaultParameterValues variable displays the updated hash table. Gdy zostanie użyta metoda Remove , Disabled klucz zostanie usunięty z danych wyjściowych.When the Remove method is used, the Disabled key is removed from the output. Jeśli Alternatywna składnia została użyta do ponownego włączenia $PSDefaultParameterValues , Disabled klucz jest wyświetlany jako Fałsz.If the alternate syntax was used to re-enable $PSDefaultParameterValues, the Disabled key is displayed as False.

PS> $PSDefaultParameterValues

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

Zobacz teżSee also

about_CommonParametersabout_CommonParameters

about_Functions_Advancedabout_Functions_Advanced

about_Functions_CmdletBindingAttributeabout_Functions_CmdletBindingAttribute

about_Hash_Tablesabout_Hash_Tables

about_Preference_Variablesabout_Preference_Variables

about_Profilesabout_Profiles

about_Script_Blocksabout_Script_Blocks