Powershell

# 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

Example - Parameter Design

function Set-ResourceConfiguration {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Name,

        [Parameter()]
        [ValidateSet('Dev', 'Test', 'Prod')]
        [string]$Environment = 'Dev',

        # ✔️ CORRECT: Use `[switch]` with no default value
        [Parameter()]
        [switch]$Force,

         # ❌ WRONG: Shows incorrect default assignment, however this is correct syntax (requires `[switch]` cast).
        [Parameter()]
        [switch]$Quiet = [switch]$true,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [string[]]$Tags
    )

    process {
        # Use .IsPresent to check switch state
        if ($Quiet.IsPresent) {
            Write-Verbose "Quiet mode enabled"
        }
    }
}

Pipeline and Output

- **Pipeline Input:**

- Use `ValueFromPipeline` for direct object input

- Use `ValueFromPipelineByPropertyName` for property mapping

- Implement Begin/Process/End blocks for pipeline handling

- Document pipeline input requirements

- **Output Objects:**

- Return rich objects, not formatted text

- Use PSCustomObject for structured data

- Avoid Write-Host for data output

- Enable downstream cmdlet processing

- **Pipeline Streaming:**

- Output one object at a time

- Use process block for streaming

- Avoid collecting large arrays

- Enable immediate processing

- **PassThru Pattern:**

- Default to no output for action cmdlets

- Implement `-PassThru` switch for object return

- Return modified/created object with `-PassThru`

- Use verbose/warning for status updates

Example