dbatools: Instructions file for Claude Code

dbatools PowerShell Style Guide

This is the single source for repository-wide PowerShell style and workflow conventions. It applies to every PowerShell file under public/, private/, tests/, and the repository scripts, regardless of which agent or contributor makes the change.

CRITICAL COMMAND SYNTAX RULES

NO BACKTICKS - ALWAYS USE SPLATS

ABSOLUTE RULE: NEVER suggest or use backticks (`) for line continuation. Backticks are an anti-pattern in modern PowerShell development.

PARAMETER ATTRIBUTES - NO = $true SYNTAX

MODERN RULE: Do NOT use Mandatory = $true or similar boolean attribute assignments.

# CORRECT - Modern attribute syntax (no = $true)
param(
    [Parameter(Mandatory)]
    [string]$SqlInstance,
    [Parameter(ValueFromPipeline)]
    [object[]]$InputObject,
    [switch]$EnableException
)

# WRONG - Outdated PSv2 syntax
param(
    [Parameter(Mandatory = $true)]
    [string]$SqlInstance
)

Guidelines:

• Use [Parameter(Mandatory)] not [Parameter(Mandatory = $true)]
• Use [switch] for boolean flags, not [bool] parameters
• Avoid ParameterSets - use Test-Bound instead with useful error messages
• No extra line breaks between parameter declarations

POWERSHELL v3 COMPATIBILITY

CRITICAL RULE: dbatools must support PowerShell v3. NEVER use ::new() or other PowerShell v5+ syntax.

# CORRECT - PowerShell v3 compatible
$object = New-Object -TypeName System.Collections.Hashtable

# WRONG - PowerShell v5+ only
$object = [System.Collections.Hashtable]::new()

SPLAT USAGE REQUIREMENT

• 1-2 parameters: Use direct parameter syntax
• 3+ parameters: Use splatted hashtables with $splat<Purpose> naming

# CORRECT - 2 parameters, direct syntax
$database = Get-DbaDatabase -SqlInstance $instance -Name "master"

# CORRECT - 5 parameters, must use splat
$splatConnection = @{
    SqlInstance     = $instance
    SqlCredential   = $credential
    Database        = $dbName
    EnableException = $true
    Confirm         = $false
}
$result = New-DbaDatabase @splatConnection