@mytechtoday/augment-extensions 0.1.2 → 0.4.0

package/augment-extensions/coding-standards/powershell/rules/legacy-migrations.md

@@ -0,0 +1,466 @@
+# PowerShell Legacy Migrations
+
+Best practices for migrating from Windows PowerShell to PowerShell Core, handling deprecated features, and compatibility testing.
+
+## Migration Strategy
+
+### Assessment Phase
+
+```powershell
+# Check PowerShell version
+function Get-PowerShellVersion
+{
+    [CmdletBinding()]
+    param()
+    
+    $version = $PSVersionTable.PSVersion
+    $edition = $PSVersionTable.PSEdition
+    
+    [PSCustomObject]@{
+        Version = $version
+        Edition = $edition
+        IsCore = $edition -eq 'Core'
+        IsDesktop = $edition -eq 'Desktop'
+        Platform = if ($IsWindows) { 'Windows' } 
+                   elseif ($IsLinux) { 'Linux' } 
+                   elseif ($IsMacOS) { 'macOS' } 
+                   else { 'Unknown' }
+    }
+}
+
+# Scan for compatibility issues
+function Test-ScriptCompatibility
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateScript({ Test-Path $_ })]
+        [string]$ScriptPath
+    )
+    
+    $issues = @()
+    $content = Get-Content -Path $ScriptPath -Raw
+    
+    # Check for deprecated cmdlets
+    $deprecatedCmdlets = @(
+        'ConvertTo-SecureString -AsPlainText',
+        'New-WebServiceProxy',
+        'Register-PSSessionConfiguration',
+        'Get-WmiObject',
+        'Set-WmiInstance'
+    )
+    
+    foreach ($deprecated in $deprecatedCmdlets)
+    {
+        if ($content -match [regex]::Escape($deprecated))
+        {
+            $issues += "Found deprecated: $deprecated"
+        }
+    }
+    
+    # Check for Windows-only cmdlets
+    $windowsOnlyCmdlets = @(
+        'Get-EventLog',
+        'Get-Counter',
+        'Get-WinEvent'
+    )
+    
+    foreach ($cmdlet in $windowsOnlyCmdlets)
+    {
+        if ($content -match "\b$cmdlet\b")
+        {
+            $issues += "Windows-only cmdlet: $cmdlet"
+        }
+    }
+    
+    return $issues
+}
+```
+
+## Deprecated Feature Handling
+
+### WMI to CIM Migration
+
+```powershell
+# ❌ OLD: Windows PowerShell (WMI)
+# Get-WmiObject -Class Win32_OperatingSystem
+
+# ✅ NEW: PowerShell Core (CIM)
+function Get-OperatingSystemInfo
+{
+    [CmdletBinding()]
+    param()
+    
+    try
+    {
+        $os = Get-CimInstance -ClassName Win32_OperatingSystem -ErrorAction Stop
+        
+        [PSCustomObject]@{
+            Caption = $os.Caption
+            Version = $os.Version
+            BuildNumber = $os.BuildNumber
+            OSArchitecture = $os.OSArchitecture
+            LastBootUpTime = $os.LastBootUpTime
+            FreePhysicalMemory = $os.FreePhysicalMemory
+        }
+    }
+    catch
+    {
+        Write-Error "Failed to get OS info: $_"
+        throw
+    }
+}
+```
+
+### Event Log Migration
+
+```powershell
+# ❌ OLD: Get-EventLog (not available in PowerShell Core)
+# Get-EventLog -LogName Application -Newest 100
+
+# ✅ NEW: Get-WinEvent (cross-platform where available)
+function Get-ApplicationEvents
+{
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [int]$MaxEvents = 100,
+        
+        [Parameter()]
+        [string]$LogName = 'Application'
+    )
+    
+    if (-not $IsWindows)
+    {
+        Write-Warning "Event logs are only available on Windows"
+        return
+    }
+    
+    try
+    {
+        $filterHash = @{
+            LogName = $LogName
+            MaxEvents = $MaxEvents
+        }
+        
+        Get-WinEvent -FilterHashtable $filterHash -ErrorAction Stop
+    }
+    catch
+    {
+        Write-Error "Failed to get events: $_"
+        throw
+    }
+}
+```
+
+### Secure String Handling
+
+```powershell
+# ❌ OLD: ConvertTo-SecureString with -AsPlainText (deprecated)
+# $securePassword = ConvertTo-SecureString 'P@ssw0rd' -AsPlainText -Force
+
+# ✅ NEW: Use Read-Host or certificate-based encryption
+function New-SecureCredential
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$UserName
+    )
+    
+    # Prompt for password securely
+    $securePassword = Read-Host -Prompt "Enter password for $UserName" -AsSecureString
+    
+    $credential = [PSCredential]::new($UserName, $securePassword)
+    
+    return $credential
+}
+```
+
+## Compatibility Testing
+
+### Multi-Version Testing
+
+```powershell
+function Test-ScriptOnMultipleVersions
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ScriptPath,
+
+        [Parameter()]
+        [string[]]$PowerShellVersions = @('5.1', '7.4')
+    )
+
+    $results = @()
+
+    foreach ($version in $PowerShellVersions)
+    {
+        Write-Verbose "Testing on PowerShell $version"
+
+        $pwshPath = if ($version -like '5.*')
+        {
+            'powershell.exe'
+        }
+        else
+        {
+            'pwsh.exe'
+        }
+
+        try
+        {
+            $output = & $pwshPath -File $ScriptPath -ErrorAction Stop
+
+            $results += [PSCustomObject]@{
+                Version = $version
+                Success = $true
+                Output = $output
+                Error = $null
+            }
+        }
+        catch
+        {
+            $results += [PSCustomObject]@{
+                Version = $version
+                Success = $false
+                Output = $null
+                Error = $_.Exception.Message
+            }
+        }
+    }
+
+    return $results
+}
+```
+
+### Compatibility Wrapper Functions
+
+```powershell
+function Get-ComputerInfoCompat
+{
+    [CmdletBinding()]
+    param()
+
+    if ($PSVersionTable.PSVersion.Major -ge 7)
+    {
+        # PowerShell Core
+        if ($IsWindows)
+        {
+            Get-ComputerInfo
+        }
+        else
+        {
+            Write-Warning "Get-ComputerInfo is Windows-only"
+            return $null
+        }
+    }
+    else
+    {
+        # Windows PowerShell
+        Get-ComputerInfo
+    }
+}
+```
+
+## Module Compatibility
+
+### Conditional Module Loading
+
+```powershell
+function Import-ModuleCompat
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ModuleName,
+
+        [Parameter()]
+        [string]$AlternativeModule
+    )
+
+    try
+    {
+        Import-Module $ModuleName -ErrorAction Stop
+        Write-Verbose "Loaded module: $ModuleName"
+    }
+    catch
+    {
+        if ($AlternativeModule)
+        {
+            Write-Warning "Failed to load $ModuleName, trying $AlternativeModule"
+            Import-Module $AlternativeModule -ErrorAction Stop
+        }
+        else
+        {
+            throw
+        }
+    }
+}
+
+# Usage
+Import-ModuleCompat -ModuleName 'ActiveDirectory' -AlternativeModule 'Microsoft.Graph.Identity.DirectoryManagement'
+```
+
+### Windows Compatibility Module
+
+```powershell
+# For PowerShell Core on Windows, use Windows Compatibility
+if ($PSVersionTable.PSVersion.Major -ge 7 -and $IsWindows)
+{
+    # Import Windows PowerShell modules via compatibility layer
+    Import-Module -Name ActiveDirectory -UseWindowsPowerShell -ErrorAction SilentlyContinue
+}
+```
+
+## Migration Patterns
+
+### Gradual Migration Approach
+
+```powershell
+# Step 1: Add version detection
+#Requires -Version 5.1
+
+$isPowerShellCore = $PSVersionTable.PSEdition -eq 'Core'
+
+# Step 2: Use conditional logic for version-specific code
+if ($isPowerShellCore)
+{
+    # PowerShell Core implementation
+    $os = Get-CimInstance -ClassName Win32_OperatingSystem
+}
+else
+{
+    # Windows PowerShell implementation
+    $os = Get-WmiObject -Class Win32_OperatingSystem
+}
+
+# Step 3: Gradually replace with Core-compatible code
+# Eventually remove conditional logic once fully migrated
+```
+
+### Feature Detection Over Version Detection
+
+```powershell
+# ✅ GOOD: Feature detection
+function Invoke-CommandWithFeatureDetection
+{
+    [CmdletBinding()]
+    param()
+
+    # Check if cmdlet exists
+    if (Get-Command -Name Get-CimInstance -ErrorAction SilentlyContinue)
+    {
+        Get-CimInstance -ClassName Win32_OperatingSystem
+    }
+    elseif (Get-Command -Name Get-WmiObject -ErrorAction SilentlyContinue)
+    {
+        Get-WmiObject -Class Win32_OperatingSystem
+    }
+    else
+    {
+        throw "No compatible cmdlet found"
+    }
+}
+
+# ❌ BAD: Hard version checks
+# if ($PSVersionTable.PSVersion.Major -eq 5) { ... }
+```
+
+## Common Migration Issues
+
+### Issue 1: .NET Framework vs .NET Core
+
+```powershell
+# Windows PowerShell uses .NET Framework
+# PowerShell Core uses .NET Core/.NET 5+
+
+# Check .NET runtime
+$runtime = [System.Runtime.InteropServices.RuntimeInformation]::FrameworkDescription
+Write-Output "Running on: $runtime"
+
+# Some .NET Framework APIs are not available in .NET Core
+# Use cross-platform alternatives
+```
+
+### Issue 2: Default Encoding Changes
+
+```powershell
+# Windows PowerShell: Default encoding varies
+# PowerShell Core: Default encoding is UTF-8 (no BOM)
+
+# ✅ GOOD: Explicitly specify encoding
+function Write-FileWithEncoding
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Path,
+
+        [Parameter(Mandatory)]
+        [string]$Content
+    )
+
+    # Use UTF-8 without BOM for cross-platform compatibility
+    $utf8NoBom = [System.Text.UTF8Encoding]::new($false)
+    [System.IO.File]::WriteAllText($Path, $Content, $utf8NoBom)
+}
+```
+
+### Issue 3: Remoting Differences
+
+```powershell
+# Windows PowerShell: Uses WSMan by default
+# PowerShell Core: Supports WSMan and SSH
+
+function New-RemoteSessionCompat
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ComputerName,
+
+        [Parameter()]
+        [PSCredential]$Credential,
+
+        [Parameter()]
+        [ValidateSet('WSMan', 'SSH')]
+        [string]$Protocol = 'WSMan'
+    )
+
+    $sessionParams = @{
+        ComputerName = $ComputerName
+    }
+
+    if ($Credential)
+    {
+        $sessionParams['Credential'] = $Credential
+    }
+
+    if ($Protocol -eq 'SSH' -and $PSVersionTable.PSVersion.Major -ge 7)
+    {
+        $sessionParams['HostName'] = $ComputerName
+        $sessionParams.Remove('ComputerName')
+        New-PSSession @sessionParams -SSHTransport
+    }
+    else
+    {
+        New-PSSession @sessionParams
+    }
+}
+```
+
+## Best Practices
+
+1. **Test on both versions** - Validate scripts on Windows PowerShell 5.1 and PowerShell Core 7.4+
+2. **Use CIM instead of WMI** - CIM cmdlets are cross-platform
+3. **Avoid deprecated cmdlets** - Replace with modern equivalents
+4. **Feature detection over version detection** - Check for cmdlet availability
+5. **Explicit encoding** - Always specify UTF-8 encoding
+6. **Use compatibility modules** - Leverage Windows Compatibility when needed
+7. **Gradual migration** - Migrate incrementally, not all at once
+8. **Document compatibility** - Note minimum PowerShell version requirements
+9. **Use #Requires statements** - Specify minimum version and modules
+10. **Automated testing** - Test on multiple PowerShell versions in CI/CD
+
+

package/augment-extensions/coding-standards/powershell/rules/modules-functions.md

@@ -0,0 +1,244 @@
+# PowerShell Modules and Advanced Functions
+
+Best practices for PowerShell module development and advanced function patterns.
+
+## Advanced Functions
+
+### CmdletBinding Attribute
+
+**ALWAYS** use `[CmdletBinding()]` for advanced functions:
+
+```powershell
+function Get-UserData
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline)]
+        [string]$UserName
+    )
+    
+    begin
+    {
+        Write-Verbose "Starting Get-UserData"
+    }
+    
+    process
+    {
+        Write-Verbose "Processing user: $UserName"
+        # Function logic
+    }
+    
+    end
+    {
+        Write-Verbose "Completed Get-UserData"
+    }
+}
+```
+
+### Parameter Attributes
+
+```powershell
+function Set-Configuration
+{
+    [CmdletBinding()]
+    param(
+        # Mandatory parameter
+        [Parameter(Mandatory)]
+        [string]$ConfigPath,
+        
+        # Pipeline input by value
+        [Parameter(ValueFromPipeline)]
+        [string]$Value,
+        
+        # Pipeline input by property name
+        [Parameter(ValueFromPipelineByPropertyName)]
+        [string]$Name,
+        
+        # Parameter validation
+        [Parameter()]
+        [ValidateSet('Development', 'Staging', 'Production')]
+        [string]$Environment = 'Development',
+        
+        # Range validation
+        [Parameter()]
+        [ValidateRange(1, 100)]
+        [int]$RetryCount = 3,
+        
+        # Script validation
+        [Parameter()]
+        [ValidateScript({ Test-Path $_ })]
+        [string]$LogPath
+    )
+}
+```
+
+## Parameter Sets
+
+### Multiple Parameter Sets
+
+```powershell
+function Get-Data
+{
+    [CmdletBinding(DefaultParameterSetName = 'ByName')]
+    param(
+        [Parameter(Mandatory, ParameterSetName = 'ByName')]
+        [string]$Name,
+        
+        [Parameter(Mandatory, ParameterSetName = 'ById')]
+        [int]$Id,
+        
+        [Parameter(ParameterSetName = 'ByName')]
+        [Parameter(ParameterSetName = 'ById')]
+        [switch]$IncludeDetails
+    )
+    
+    switch ($PSCmdlet.ParameterSetName)
+    {
+        'ByName' { Write-Output "Getting data by name: $Name" }
+        'ById'   { Write-Output "Getting data by ID: $Id" }
+    }
+}
+
+# Usage
+Get-Data -Name 'User1'
+Get-Data -Id 123
+```
+
+## SupportsShouldProcess
+
+### WhatIf and Confirm Support
+
+```powershell
+function Remove-UserData
+{
+    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]
+    param(
+        [Parameter(Mandatory)]
+        [string]$UserName
+    )
+    
+    if ($PSCmdlet.ShouldProcess($UserName, 'Remove user data'))
+    {
+        # Perform deletion
+        Write-Output "Removing data for $UserName"
+    }
+}
+
+# Usage
+Remove-UserData -UserName 'TestUser' -WhatIf
+Remove-UserData -UserName 'TestUser' -Confirm:$false
+```
+
+## Module Structure
+
+### Module Directory Layout
+
+```
+MyModule/
+├── MyModule.psd1           # Module manifest
+├── MyModule.psm1           # Module script
+├── Public/                 # Exported functions
+│   ├── Get-Something.ps1
+│   └── Set-Something.ps1
+├── Private/                # Internal functions
+│   └── Helper.ps1
+├── Classes/                # PowerShell classes
+│   └── MyClass.ps1
+├── Data/                   # Data files
+│   └── config.json
+└── Tests/                  # Pester tests
+    └── MyModule.Tests.ps1
+```
+
+### Module Manifest (.psd1)
+
+```powershell
+@{
+    RootModule = 'MyModule.psm1'
+    ModuleVersion = '1.0.0'
+    GUID = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
+    Author = 'Your Name'
+    CompanyName = 'Your Company'
+    Copyright = '(c) 2024. All rights reserved.'
+    Description = 'Module description'
+    
+    PowerShellVersion = '7.4'
+    
+    FunctionsToExport = @('Get-Something', 'Set-Something')
+    CmdletsToExport = @()
+    VariablesToExport = @()
+    AliasesToExport = @()
+    
+    PrivateData = @{
+        PSData = @{
+            Tags = @('Tag1', 'Tag2')
+            LicenseUri = 'https://github.com/user/repo/blob/main/LICENSE'
+            ProjectUri = 'https://github.com/user/repo'
+        }
+    }
+}
+```
+
+### Module Script (.psm1)
+
+```powershell
+#Requires -Version 7.4
+
+# Import public functions
+$publicFunctions = @(Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue)
+
+# Import private functions
+$privateFunctions = @(Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue)
+
+# Dot source the files
+foreach ($import in @($publicFunctions + $privateFunctions))
+{
+    try
+    {
+        . $import.FullName
+    }
+    catch
+    {
+        Write-Error "Failed to import function $($import.FullName): $_"
+    }
+}
+
+# Export public functions
+Export-ModuleMember -Function $publicFunctions.BaseName
+```
+
+## Output Types
+
+### Specify Output Type
+
+```powershell
+function Get-UserInfo
+{
+    [CmdletBinding()]
+    [OutputType([PSCustomObject])]
+    param(
+        [Parameter(Mandatory)]
+        [string]$UserName
+    )
+    
+    [PSCustomObject]@{
+        UserName = $UserName
+        Email = "$UserName@example.com"
+        Created = Get-Date
+    }
+}
+```
+
+## Best Practices
+
+1. **Use CmdletBinding** - Enable advanced function features
+2. **Validate parameters** - Use validation attributes
+3. **Support pipeline** - Use ValueFromPipeline
+4. **Use parameter sets** - For mutually exclusive parameters
+5. **Implement ShouldProcess** - For destructive operations
+6. **Specify output types** - Use [OutputType()] attribute
+7. **Export selectively** - Only export public functions
+8. **Use begin/process/end** - For pipeline processing
+9. **Write verbose output** - Use Write-Verbose
+10. **Follow naming conventions** - Verb-Noun format
+