default parameter values

When connecting to a SQL Server instance with alternative credentials, it can be tedious to repeat the SQL credential over and over.

The great news is that this repetition is not required, as it can be handled instead by $PSDefaultParameterValues

Intro to $PSDefaultParameterValues

$PSDefaultParameterValues is a hashtable available in PowerShell that can set defaults for any command that you run. In it’s simplest form, setting a default parameter value can look like this:

$PSDefaultParameterValues['Get-DbaDatabase:Verbose'] = $true

According to Microsoft, $PSDefaultParameterValues:

Let you specify custom default values for any command
Commands use the custom default value unless you specify another value
Useful when you must specify the same value nearly every time

After running the above code, Get-DbaDatabase will show verbose output every time it’s executed, without me having to specify -Verbose. If I need to override that verbose flag for some reason, I can simply add -Verbose:$false to my Get-DbaDatabase command.

Usage

Here’s what I’ve used $PSDefaultParameterValues for:

• SqlCredential for SQL Authentication in docker
• ErrorAction Stop in Agent Jobs to ensure failures fail
• Confirm:$false in Agent Jobs to avoid prompting
• Verbose in Agent Jobs to see command output in the logs
• EnableException in dbachecks to ensure Pester tests fail
• SqlCredential for any alternative credential needs, actually
• Invoke-WebRequest Proxy and ProxyUseDefaultCredentials

You could even set a default SQL Server and get results from Get-DbaDatabase.

If you have configured a good amount of default parameters and want to see all of your default parameter values, you just need to run $PSDefaultParameterValues .

Oh, and it’s no big deal if a command does not support the parameter, the parameter and its value just won’t be passed. And also, like most things that support defaults, you can override the defaults, as mentioned previously.

Syntax & real-world examples

Michael Sorens awesome article on simple-talk goes in-depth about syntax, but here are some basics.

# EnableException for all dbatools commands using wildcards, overwrite previous $PSDefaultParameterValues 
$PSDefaultParameterValues = @{ '*-Dba*:EnableException' = $true }

# Turn off confirmation prompts for all commands (useful in automation/scheduled jobs), add to existing $PSDefaultParameterValues
$PSDefaultParameterValues['*:Confirm'] = $false

# Use a saved credential for all commands, add to existing PSDefaultParameterValues
$sqlcredential = Import-CliXml -Path "$home\Documents\sqlcred.xml"
$wincredential = Import-CliXml -Path "$home\Documents\wincred.xml"

$PSDefaultParameterValues += @{
    '*-Dba*:SqlCredential' = $sqlcredential
    '*:Credential' = $wincredential 
}

# Conditional default params, thanks Boe!
$PSDefaultParameterValues = @{
    "Format-Table:AutoSize" = {
        if ($host.Name -eq "ConsoleHost") { $true }
    }
}

In the real-world, I primarily use Default Parameter Values when running Scheduled Tasks/Agent Jobs. I like to see verbose output in my logs, so I enable that. I also make sure there are no confirmation prompts; that got me once as I waited over 24 hours for a job to complete (“daaang this code is slow”) 😅

Disabling $PSDefaultParameterValues

Your default parameter values can be temporarily disabled by adding the following key:

$PSDefaultParameterValues["Disabled"] = $true

And you can reenable it by setting Disabled to $false or by removing the Disabled key.

$PSDefaultParameterValues.Remove('Disabled')

Persistence

Setting $PSDefaultParameterValues at the command-line only lasts during that session, meaning if you close your console, it will be reset. So, if you want it the default values to persist, you’ll have to add it to your profile (basically: notepad $profile, paste, save).

Scopes are dope

In dbachecks, we set $PSDefaultParameterValues to EnableException across the board. This allows our Pester tests to fail when a failure occurs.

What’s interesting is that setting the value within the module does not impact the end-user, so even after you import dbachecks, your $PSDefaultParameterValues will not be modified.

Resources

There are some great resources that go more in-depth about Parameters Default Values. Here are just a few:

- Chrissy