First add of PowerShell instructions (#55)

* First add of PowerShell instructions * Update instructions/powershell.instructions.md * Update instructions/powershell.instructions.md --------- Co-authored-by: Aaron Powell <me@aaron-powell.com>
2025-07-07 02:04:43 +02:00 · 2025-07-07 02:04:43 +02:00 · c3869d8c7b
commit c3869d8c7b
parent 475de69066
2 changed files with 334 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -40,6 +40,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
 | [Memory Bank](instructions/memory-bank.instructions.md) | Bank specific coding standards and best practices | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmemory-bank.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmemory-bank.instructions.md) |
 | [Next.js + Tailwind Development Instructions](instructions/nextjs-tailwind.instructions.md) | Next.js + Tailwind development standards and instructions | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fnextjs-tailwind.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fnextjs-tailwind.instructions.md) |
 | [Performance Optimization Best Practices](instructions/performance-optimization.instructions.md) | The most comprehensive, practical, and engineer-authored performance optimization instructions for all languages, frameworks, and stacks. Covers frontend, backend, and database best practices with actionable guidance, scenario-based checklists, troubleshooting, and pro tips. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md) |
+| [PowerShell Cmdlet Development Guidelines](instructions/powershell.instructions.md) | PowerShell cmdlet and scripting best practices based on Microsoft guidelines | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell.instructions.md) |
 | [Python Coding Conventions](instructions/python.instructions.md) | Python coding conventions and guidelines | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython.instructions.md) |
 | [Secure Coding and OWASP Guidelines](instructions/security-and-owasp.instructions.md) | Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fsecurity-and-owasp.instructions.md) |
 | [TanStack Start with Shadcn/ui Development Guide](instructions/tanstack-start-shadcn-tailwind.md) | Guidelines for building TanStack Start applications | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftanstack-start-shadcn-tailwind.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftanstack-start-shadcn-tailwind.md) |
--- a/instructions/powershell.instructions.md
+++ b/instructions/powershell.instructions.md
@ -0,0 +1,333 @@
+---
+applyTo: '**/*.ps1,**/*.psm1'
+description: 'PowerShell cmdlet and scripting best practices based on Microsoft guidelines'
+---  
+
+# 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
+
+```powershell
+function Get-UserProfile {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Username,
+
+        [Parameter()]
+        [ValidateSet('Basic', 'Detailed')]
+        [string]$ProfileType = 'Basic'
+    )
+
+    process {
+        # 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:**
+  - Use [switch] for boolean flags
+  - Avoid $true/$false parameters
+  - Default to $false when omitted
+  - Use clear action names
+
+### Example
+
+```powershell
+function Set-ResourceConfiguration {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Name,
+        
+        [Parameter()]
+        [ValidateSet('Dev', 'Test', 'Prod')]
+        [string]$Environment = 'Dev',
+        
+        [Parameter()]
+        [switch]$Force,
+        
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [string[]]$Tags
+    )
+    
+    process {
+        # Logic here
+    }
+}
+```
+
+## 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
+
+```powershell
+function Update-ResourceStatus {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [string]$Name,
+
+        [Parameter(Mandatory)]
+        [ValidateSet('Active', 'Inactive', 'Maintenance')]
+        [string]$Status,
+
+        [Parameter()]
+        [switch]$PassThru
+    )
+
+    begin {
+        Write-Verbose "Starting resource status update process"
+        $timestamp = Get-Date
+    }
+
+    process {
+        # Process each resource individually
+        Write-Verbose "Processing resource: $Name"
+        
+        $resource = [PSCustomObject]@{
+            Name = $Name
+            Status = $Status
+            LastUpdated = $timestamp
+            UpdatedBy = $env:USERNAME
+        }
+
+        # Only output if PassThru is specified
+        if ($PassThru) {
+            Write-Output $resource
+        }
+    }
+
+    end {
+        Write-Verbose "Resource status update process completed"
+    }
+}
+ ```
+
+## Error Handling and Safety
+
+- **ShouldProcess Implementation:**
+  - Use `[CmdletBinding(SupportsShouldProcess = $true)]`
+  - Set appropriate `ConfirmImpact` level
+  - Call `$PSCmdlet.ShouldProcess()` for system changes
+  - Use `ShouldContinue()` for additional confirmations
+
+- **Message Streams:**
+  - `Write-Verbose` for operational details with `-Verbose`
+  - `Write-Warning` for warning conditions
+  - `Write-Error` for non-terminating errors
+  - `throw` for terminating errors
+  - Avoid `Write-Host` except for user interface text
+
+- **Error Handling Pattern:**
+  - Use try/catch blocks for error management
+  - Set appropriate ErrorAction preferences
+  - Return meaningful error messages
+  - Use ErrorVariable when needed
+  - Include proper terminating vs non-terminating error handling
+
+- **Non-Interactive Design:**
+  - Accept input via parameters
+  - Avoid `Read-Host` in scripts
+  - Support automation scenarios
+  - Document all required inputs
+
+### Example
+
+```powershell
+function Remove-UserAccount {
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline)]
+        [ValidateNotNullOrEmpty()]
+        [string]$Username,
+
+        [Parameter()]
+        [switch]$Force
+    )
+
+    begin {
+        Write-Verbose "Starting user account removal process"
+        $ErrorActionPreference = 'Stop'
+    }
+
+    process {
+        try {
+            # Validation
+            if (-not (Test-UserExists -Username $Username)) {
+                Write-Error "User account '$Username' not found"
+                return
+            }
+
+            # Confirmation
+            $shouldProcessMessage = "Remove user account '$Username'"
+            if ($Force -or $PSCmdlet.ShouldProcess($Username, $shouldProcessMessage)) {
+                Write-Verbose "Removing user account: $Username"
+                
+                # Main operation
+                Remove-ADUser -Identity $Username -ErrorAction Stop
+                Write-Warning "User account '$Username' has been removed"
+            }
+        }
+        catch [Microsoft.ActiveDirectory.Management.ADException] {
+            Write-Error "Active Directory error: $_"
+            throw
+        }
+        catch {
+            Write-Error "Unexpected error removing user account: $_"
+            throw
+        }
+    }
+
+    end {
+        Write-Verbose "User account removal process completed"
+    }
+}
+```
+
+## Documentation and Style
+
+- **Comment-Based Help:** Include comment-based help for any public-facing function or cmdlet. Inside the function, add a `<# ... #>` help comment with at least:
+  - `.SYNOPSIS` Brief description
+  - `.DESCRIPTION` Detailed explanation
+  - `.EXAMPLE` sections with practical usage
+  - `.PARAMETER` descriptions
+  - `.OUTPUTS` Type of output returned
+  - `.NOTES` Additional information
+
+- **Consistent Formatting:**
+  - Follow consistent PowerShell style
+  - Use proper indentation (4 spaces recommended)
+  - Opening braces on same line as statement
+  - Closing braces on new line
+  - Use line breaks after pipeline operators
+  - PascalCase for function and parameter names
+  - Avoid unnecessary whitespace
+
+- **Pipeline Support:**
+  - Implement Begin/Process/End blocks for pipeline functions
+  - Use ValueFromPipeline where appropriate
+  - Support pipeline input by property name
+  - Return proper objects, not formatted text
+
+- **Avoid Aliases:** Use full cmdlet names and parameters
+  - Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci); aliases are acceptable for interactive shell use.
+  - Use `Where-Object` instead of `?` or `where`
+  - Use `ForEach-Object` instead of `%`
+  - Use `Get-ChildItem` instead of `ls` or `dir`
+
+## Full Example: End-to-End Cmdlet Pattern
+
+```powershell
+function New-Resource {
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
+    param(
+        [Parameter(Mandatory = $true,
+                   ValueFromPipeline = $true,
+                   ValueFromPipelineByPropertyName = $true)]
+        [ValidateNotNullOrEmpty()]
+        [string]$Name,
+
+        [Parameter()]
+        [ValidateSet('Development', 'Production')]
+        [string]$Environment = 'Development'
+    )
+    
+    begin {
+        Write-Verbose "Starting resource creation process"
+    }
+    
+    process {
+        try {
+            if ($PSCmdlet.ShouldProcess($Name, "Create new resource")) {
+                # Resource creation logic here
+                Write-Output ([PSCustomObject]@{
+                    Name = $Name
+                    Environment = $Environment
+                    Created = Get-Date
+                })
+            }
+        }
+        catch {
+            Write-Error "Failed to create resource: $_"
+        }
+    }
+    
+    end {
+        Write-Verbose "Completed resource creation process"
+    }
+}
+```