about_Parameters_Default_Values
Krótki opis
Opisuje sposób ustawiania niestandardowych wartości domyślnych dla parametrów polecenia cmdlet i funkcji zaawansowanych.
Długi opis
Zmienna $PSDefaultParameterValues preferencji umożliwia określenie niestandardowych wartości domyślnych dla dowolnego polecenia cmdlet lub funkcji zaawansowanej. Polecenia cmdlet i funkcje zaawansowane używają niestandardowej wartości domyślnej, chyba że określisz inną wartość w poleceniu.
Autorzy poleceń cmdlet i zaawansowanych funkcji ustawiają standardowe wartości domyślne dla swoich parametrów. Zazwyczaj standardowe wartości domyślne są przydatne, ale mogą nie być odpowiednie dla wszystkich środowisk.
Ta funkcja jest szczególnie przydatna, gdy musisz określić tę samą wartość parametru alternatywnego prawie za każdym razem, gdy używasz polecenia lub gdy określona wartość parametru jest trudna do zapamiętania, na przykład nazwa serwera poczty e-mail lub identyfikator GUID projektu.
Jeśli żądana wartość domyślna różni się przewidywalnie, możesz określić blok skryptu, który udostępnia różne wartości domyślne parametru w różnych warunkach.
$PSDefaultParameterValues wprowadzono w programie PowerShell 3.0.
Składnia
Zmienna $PSDefaultParameterValues jest tabelą skrótów, która weryfikuje format kluczy jako typ obiektu System.Management.Automation.DefaultParameterDictionary. Tabela skrótów zawiera pary Klucz/Wartość . Klucz ma format CmdletName:ParameterName. Wartość jest wartością DefaultValue lub ScriptBlock przypisaną do klucza.
Składnia zmiennej $PSDefaultParameterValues preferencji jest następująca:
$PSDefaultParameterValues=@{"CmdletName:ParameterName"="DefaultValue"}
$PSDefaultParameterValues=@{ "CmdletName:ParameterName"={{ScriptBlock}} }
$PSDefaultParameterValues["Disabled"]=$True | $False
Symbole wieloznaczne są dozwolone w wartościach CmdletName i ParameterName .
Aby ustawić, zmienić, dodać lub usunąć określoną parę klucz/wartość z $PSDefaultParameterValuesprogramu , użyj metod do edytowania standardowej tabeli skrótów. Na przykład metody Dodaj i Usuń . Te metody nie zastępują innych wartości w tabeli skrótów.
Istnieje inna składnia, która nie zastępuje istniejącej $PSDefaultParameterValues tabeli skrótów. Aby dodać lub zmienić określoną parę klucz/wartość , użyj następującej składni:
$PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"
Nazwa _ polecenia cmdlet musi być nazwą polecenia cmdlet lub nazwą funkcji zaawansowanej, która używa atrybutu CmdletBinding . Nie można użyć $PSDefaultParameterValues polecenia , aby określić wartości domyślne dla skryptów lub prostych funkcji.
Wartość DefaultValue może być obiektem lub blokiem skryptu. Jeśli wartość jest blokiem skryptu, program PowerShell oblicza blok skryptu i używa wyniku jako wartości parametru. Gdy określony parametr akceptuje wartość bloku skryptu, należy ująć wartość bloku skryptu w drugim zestawie nawiasów klamrowych, takich jak:
$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }
Więcej informacji można znaleźć w następujących dokumentach:
Przykłady
Jak ustawić $PSDefaultParameterValues
$PSDefaultParameterValues jest zmienną preferencji, więc istnieje tylko w sesji, w której jest ustawiona. Nie ma wartości domyślnej.
Aby ustawić $PSDefaultParameterValues, wpisz nazwę zmiennej i co najmniej jedną parę Klucz/Wartość . Jeśli uruchomisz inne $PSDefaultParameterValues polecenie, zastąpi istniejącą tabelę skrótów.
Aby zapoznać się z przykładami dotyczącymi zmieniania par klucz/wartość bez zastępowania istniejących wartości tabeli skrótów, zobacz How to add values to $PSDefaultParameterValues or How to change values in $PSDefaultParameterValues (Jak dodawać wartości do $PSDefaultParameterValues) lub How to change values in $PSDefaultParameterValues (Jak zmienić wartości w $PSDefaultParameterValues).
Aby zapisać $PSDefaultParameterValues na potrzeby przyszłych sesji, dodaj $PSDefaultParameterValues polecenie do profilu programu PowerShell. Aby uzyskać więcej informacji, zobacz about_Profiles.
Ustawianie niestandardowej wartości domyślnej
Para Klucz/Wartość ustawia Send-MailMessage:SmtpServer klucz na niestandardową wartość domyślną Server123.
$PSDefaultParameterValues = @{
"Send-MailMessage:SmtpServer"="Server123"
}
Ustawianie wartości domyślnych dla wielu parametrów
Aby ustawić wartości domyślne dla wielu parametrów, należy oddzielić każdą parę Klucz/Wartość średnikiem (;). Klucze Send-MailMessage:SmtpServer i Get-WinEvent:LogName są ustawione na niestandardowe wartości domyślne.
$PSDefaultParameterValues = @{
"Send-MailMessage:SmtpServer"="Server123";
"Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"
}
Używanie symboli wieloznacznych i parametrów przełącznika
Nazwy poleceń cmdlet i parametrów mogą zawierać symbole wieloznaczne. Użyj $True i $False , aby ustawić wartości parametrów przełącznika, takich jak Pełne. Parametr verbose wspólnego parametru jest ustawiony na $True dla wszystkich poleceń.
$PSDefaultParameterValues = @{"*:Verbose"=$True}
Użyj tablicy dla wartości domyślnej
Jeśli parametr może akceptować wiele wartości, tablica, można ustawić wiele wartości jako wartości domyślne. Wartość Invoke-Command:ComputerName domyślna klucza jest ustawiona na wartość tablicy Server01 i Server02.
$PSDefaultParameterValues = @{
"Invoke-Command:ComputerName"="Server01","Server02"
}
Używanie bloku skryptu
Blok skryptu umożliwia określenie różnych wartości domyślnych parametru w różnych warunkach. Program PowerShell ocenia blok skryptu i używa wyniku jako wartości domyślnego parametru.
Klucz Format-Table:AutoSize ustawia, który przełącza parametr na wartość domyślną True. Instrukcja If zawiera warunek, który $host.Name musi być konsolą programu PowerShell, ConsoleHost.
$PSDefaultParameterValues=@{
"Format-Table:AutoSize"={if ($host.Name -eq "ConsoleHost"){$True}}
}
Jeśli parametr akceptuje wartość bloku skryptu, należy ująć blok skryptu w dodatkowy zestaw nawiasów klamrowych. Gdy program PowerShell ocenia zewnętrzny blok skryptu, wynik jest blokiem skryptu wewnętrznego i jest ustawiony jako domyślna wartość parametru.
Klucz Invoke-Command:ScriptBlock ustawiony na wartość domyślną dziennika zdarzeń systemu, ponieważ blok skryptu jest ujęty w drugi zestaw nawiasów klamrowych. Wynik bloku skryptu jest przekazywany do Invoke-Command polecenia cmdlet .
$PSDefaultParameterValues=@{
"Invoke-Command:ScriptBlock"={{Get-EventLog -Log System}}
}
Jak uzyskać $PSDefaultParameterValues
Wartości tabeli skrótów są wyświetlane przez wprowadzenie $PSDefaultParameterValues w wierszu polecenia programu PowerShell.
$PSDefaultParameterValues Tabela skrótów jest ustawiana z trzema parami Klucz/Wartość.
Ta tabela skrótów jest używana w poniższych przykładach, które opisują sposób dodawania, zmieniania i usuwania wartości z programu $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, użyj następującej składni:
$PSDefaultParameterValues["CmdletName:ParameterName"]
Aby na przykład uzyskać wartość Send-MailMessage:SmtpServer klucza.
PS> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
Server123
Jak dodać wartości do $PSDefaultParameterValues
Aby dodać wartość do $PSDefaultParameterValuesmetody , użyj metody Add . Dodanie wartości nie wpływa na istniejące wartości tabeli skrótów.
Użyj przecinka (,), aby oddzielić klucz od wartości. Poniższa składnia pokazuje, jak używać metody Add dla $PSDefaultParameterValueselementu .
PS> $PSDefaultParameterValues.Add("CmdletName:ParameterName", "DefaultValue")
Tabela skrótów utworzona w poprzednim przykładzie jest aktualizowana przy użyciu nowej pary Klucz/Wartość . Metoda Add ustawia Get-Process:Name klucz na wartość programu PowerShell.
$PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")
Poniższa składnia osiąga ten sam wynik.
$PSDefaultParameterValues["Get-Process:Name"]="PowerShell"
Zmienna $PSDefaultParameterValues wyświetla zaktualizowaną tabelę skrótów. Klucz Get-Process:Name został dodany.
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 $PSDefaultParameterValues
Aby usunąć wartość z $PSDefaultParameterValuesklasy , użyj metody Remove tabel skrótu. Usunięcie wartości nie wpływa na istniejące wartości tabeli skrótów.
Poniższa składnia pokazuje, jak używać metody Remove w pliku $PSDefaultParameterValues.
PS> $PSDefaultParameterValues.Remove("CmdletName:ParameterName")
W tym przykładzie tabela skrótów utworzona w poprzednim przykładzie zostanie zaktualizowana w celu usunięcia pary Klucz/Wartość . Metoda Remove usuwa Get-Process:Name klucz.
$PSDefaultParameterValues.Remove("Get-Process:Name")
Zmienna $PSDefaultParameterValues wyświetla zaktualizowaną tabelę skrótów. Klucz Get-Process:Name został usunięty.
PS> $PSDefaultParameterValues
Name Value
---- -----
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer Server123
Jak zmienić wartości w $PSDefaultParameterValues
Zmiany określonej wartości nie mają wpływu na istniejące wartości tabeli skrótów. Aby zmienić określoną parę klucz/wartość w programie $PSDefaultParameterValues, użyj następującej składni:
PS> $PSDefaultParameterValues["CmdletName:ParameterName"]="DefaultValue"
W tym przykładzie tabela skrótów utworzona w poprzednim przykładzie zostanie zaktualizowana w celu zmiany pary Klucz/Wartość . Następujące polecenie zmienia Send-MailMessage:SmtpServer klucz na nową wartość ServerXYZ.
$PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="ServerXYZ"
Zmienna $PSDefaultParameterValues wyświetla zaktualizowaną tabelę skrótów. Klucz Send-MailMessage:SmtpServer został zmieniony na nową wartość.
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ć $PSDefaultParameterValues
Możesz tymczasowo wyłączyć, a następnie ponownie włączyć polecenie $PSDefaultParameterValues.
$PSDefaultParameterValues Wyłączenie jest przydatne, jeśli uruchamiasz skrypty, które wymagają różnych wartości parametrów domyślnych.
Aby wyłączyć $PSDefaultParameterValues, dodaj klucz Disabled o wartości True. Wartości w pliku $PSDefaultParameterValues są zachowywane, ale nie są skuteczne.
PS> $PSDefaultParameterValues.Add("Disabled", $True)
Poniższa składnia osiąga ten sam wynik.
PS> $PSDefaultParameterValues["Disabled"]=$True
Zmienna $PSDefaultParameterValues wyświetla zaktualizowaną tabelę skrótów z wartością Disabled klucza.
PS> $PSDefaultParameterValues
Name Value
---- -----
Disabled True
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
Aby ponownie włączyć , usuń klucz Wyłączony lub zmień wartość wyłączonego klucza na $False.$PSDefaultParameterValues Poprzednia $PSDefaultParameterValues wartość elementu jest ponownie skuteczna.
PS> $PSDefaultParameterValues.Remove("Disabled")
Poniższa składnia osiąga ten sam wynik.
PS> $PSDefaultParameterValues["Disabled"]=$False
Zmienna $PSDefaultParameterValues wyświetla zaktualizowaną tabelę skrótów. Gdy zostanie użyta metoda Remove , Disabled klucz zostanie usunięty z danych wyjściowych.
Jeśli użyto alternatywnej składni do ponownego włączenia $PSDefaultParameterValues, Disabled klucz jest wyświetlany jako Fałsz.
PS> $PSDefaultParameterValues
Name Value
---- -----
Disabled False
Get-WinEvent:LogName Microsoft-Windows-PrintService/Operational
Get-*:Verbose True
Send-MailMessage:SmtpServer ServerXYZ
