diff --git a/README.md b/README.md index 9ee247b..2b53d9b 100644 --- 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) | diff --git a/instructions/powershell.instructions.md b/instructions/powershell.instructions.md new file mode 100644 index 0000000..3b7cb4d --- /dev/null +++ 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" + } +} +```