about_Parameters_Default_Values

  • Artykuł

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

Zobacz też