copilot-dev: Instructions file for GitHub Copilot

PowerShell Cmdlet Development Guidelines

This guide provides PowerShell-specific instructions to help GitHub Copilot generate idiomatic, safe, and maintainable scripts. It aligns with Microsoft’s PowerShell cmdlet development guidelines.

Naming Conventions

• Verb-Noun Format:

  • Use approved PowerShell verbs (Get-Verb)
  • Use singular nouns
  • PascalCase for both verb and noun
  • Avoid special characters and spaces

• Parameter Names:

  • Use PascalCase
  • Choose clear, descriptive names
  • Use singular form unless always multiple
  • Follow PowerShell standard names

• Variable Names:

  • Use PascalCase for public variables
  • Use camelCase for private variables
  • Avoid abbreviations
  • Use meaningful names

• Alias Avoidance:

  • Use full cmdlet names
  • Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci)
  • Document any custom aliases
  • Use full parameter names

Example - Naming Conventions

function Get-UserProfile {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Username,

        [Parameter()]
        [ValidateSet('Basic', 'Detailed')]
        [string]$ProfileType = 'Basic'
    )

    process {
        $outputString = "Searching for: '$($Username)'"
        Write-Verbose -Message $outputString
        Write-Verbose -Message "Profile type: $ProfileType"
        # Logic here
    }
}

Parameter Design

• Standard Parameters:

  • Use common parameter names (Path, Name, Force)
  • Follow built-in cmdlet conventions
  • Use aliases for specialized terms
  • Document parameter purpose

• Parameter Names:

  • Use singular form unless always multiple
  • Choose clear, descriptive names
  • Follow PowerShell conventions
  • Use PascalCase formatting

• Type Selection:

  • Use common .NET types
  • Implement proper validation
  • Consider ValidateSet for limited options
  • Enable tab completion where possible

• Switch Parameters:

  • ALWAYS use [switch] for boolean flags, never [bool]
  • NEVER use [bool]$Parameter or assign default values
  • Switch parameters default to $false when omitted
  • Use clear, action-oriented names
  • Test presence with .IsPresent
  • Using $true/$false in parameter attributes (e.g., Mandatory = $true) is acceptable