@mytechtoday/augment-extensions 0.1.2 → 0.4.0

package/augment-extensions/coding-standards/powershell/rules/dsc-configurations.md

@@ -0,0 +1,296 @@
+# PowerShell DSC Configurations
+
+Best practices for Desired State Configuration, configuration data separation, and LCM setup.
+
+## Configuration Structure
+
+### Basic DSC Configuration
+
+```powershell
+#Requires -Version 7.4
+
+Configuration WebServerConfig
+{
+    param(
+        [Parameter(Mandatory)]
+        [string[]]$ComputerName,
+        
+        [Parameter()]
+        [string]$WebsiteName = 'Default Web Site'
+    )
+    
+    Import-DscResource -ModuleName PSDesiredStateConfiguration
+    Import-DscResource -ModuleName xWebAdministration
+    
+    Node $ComputerName
+    {
+        WindowsFeature IIS
+        {
+            Ensure = 'Present'
+            Name = 'Web-Server'
+        }
+        
+        WindowsFeature AspNet45
+        {
+            Ensure = 'Present'
+            Name = 'Web-Asp-Net45'
+            DependsOn = '[WindowsFeature]IIS'
+        }
+        
+        xWebsite DefaultSite
+        {
+            Ensure = 'Present'
+            Name = $WebsiteName
+            State = 'Started'
+            PhysicalPath = 'C:\inetpub\wwwroot'
+            DependsOn = '[WindowsFeature]IIS'
+        }
+    }
+}
+```
+
+## Configuration Data Separation
+
+### Configuration Data File
+
+```powershell
+# ConfigData.psd1
+@{
+    AllNodes = @(
+        @{
+            NodeName = 'WebServer01'
+            Role = 'WebServer'
+            Environment = 'Production'
+            CertificateFile = 'C:\Certs\WebServer01.cer'
+        },
+        @{
+            NodeName = 'WebServer02'
+            Role = 'WebServer'
+            Environment = 'Production'
+            CertificateFile = 'C:\Certs\WebServer02.cer'
+        },
+        @{
+            NodeName = '*'
+            PSDscAllowPlainTextPassword = $false
+            PSDscAllowDomainUser = $true
+        }
+    )
+    
+    NonNodeData = @{
+        WebsiteName = 'Corporate Portal'
+        DatabaseServer = 'SQL01.contoso.com'
+    }
+}
+```
+
+### Using Configuration Data
+
+```powershell
+Configuration WebServerWithData
+{
+    Import-DscResource -ModuleName PSDesiredStateConfiguration
+    
+    Node $AllNodes.Where{$_.Role -eq 'WebServer'}.NodeName
+    {
+        $websiteName = $ConfigurationData.NonNodeData.WebsiteName
+        
+        WindowsFeature IIS
+        {
+            Ensure = 'Present'
+            Name = 'Web-Server'
+        }
+        
+        File WebContent
+        {
+            Ensure = 'Present'
+            DestinationPath = 'C:\inetpub\wwwroot\index.html'
+            Contents = "Welcome to $websiteName on $($Node.NodeName)"
+            Type = 'File'
+        }
+    }
+}
+
+# Compile configuration
+$configData = Import-PowerShellDataFile -Path '.\ConfigData.psd1'
+WebServerWithData -ConfigurationData $configData -OutputPath 'C:\DSC\Configs'
+```
+
+## Idempotency
+
+### Ensure Idempotent Resources
+
+```powershell
+Configuration IdempotentConfig
+{
+    param([string]$ComputerName)
+    
+    Import-DscResource -ModuleName PSDesiredStateConfiguration
+    
+    Node $ComputerName
+    {
+        # ✅ GOOD: Idempotent - can run multiple times safely
+        File LogDirectory
+        {
+            Ensure = 'Present'
+            Type = 'Directory'
+            DestinationPath = 'C:\Logs'
+        }
+        
+        Registry DisableIPv6
+        {
+            Ensure = 'Present'
+            Key = 'HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters'
+            ValueName = 'DisabledComponents'
+            ValueData = '0xFF'
+            ValueType = 'Dword'
+        }
+        
+        Service W32Time
+        {
+            Name = 'W32Time'
+            State = 'Running'
+            StartupType = 'Automatic'
+        }
+    }
+}
+```
+
+### Test Idempotency
+
+```powershell
+# Test configuration multiple times
+$config = IdempotentConfig -ComputerName 'localhost' -OutputPath 'C:\DSC\Test'
+
+# First run - should make changes
+Start-DscConfiguration -Path 'C:\DSC\Test' -Wait -Verbose
+
+# Second run - should report no changes needed
+Start-DscConfiguration -Path 'C:\DSC\Test' -Wait -Verbose
+
+# Verify state
+Test-DscConfiguration -Path 'C:\DSC\Test' -Verbose
+```
+
+## Local Configuration Manager (LCM)
+
+### Configure LCM
+
+```powershell
+[DSCLocalConfigurationManager()]
+Configuration LCMConfig
+{
+    param([string[]]$ComputerName)
+
+    Node $ComputerName
+    {
+        Settings
+        {
+            RefreshMode = 'Push'
+            ConfigurationMode = 'ApplyAndAutoCorrect'
+            RebootNodeIfNeeded = $true
+            ActionAfterReboot = 'ContinueConfiguration'
+            ConfigurationModeFrequencyMins = 15
+            RefreshFrequencyMins = 30
+            AllowModuleOverwrite = $true
+        }
+    }
+}
+
+# Apply LCM configuration
+LCMConfig -ComputerName 'WebServer01' -OutputPath 'C:\DSC\LCM'
+Set-DscLocalConfigurationManager -Path 'C:\DSC\LCM' -Verbose
+```
+
+### Pull Server Configuration
+
+```powershell
+[DSCLocalConfigurationManager()]
+Configuration PullClientConfig
+{
+    param(
+        [string]$NodeName,
+        [string]$RegistrationKey,
+        [string]$ServerURL
+    )
+
+    Node $NodeName
+    {
+        Settings
+        {
+            RefreshMode = 'Pull'
+            ConfigurationMode = 'ApplyAndAutoCorrect'
+            RebootNodeIfNeeded = $true
+        }
+
+        ConfigurationRepositoryWeb PullServer
+        {
+            ServerURL = $ServerURL
+            RegistrationKey = $RegistrationKey
+            ConfigurationNames = @('WebServerConfig')
+        }
+
+        ReportServerWeb PullServerReports
+        {
+            ServerURL = $ServerURL
+            RegistrationKey = $RegistrationKey
+        }
+    }
+}
+```
+
+## Credentials and Secrets
+
+### Encrypted Credentials
+
+```powershell
+Configuration SecureConfig
+{
+    param(
+        [Parameter(Mandatory)]
+        [PSCredential]$Credential
+    )
+
+    Import-DscResource -ModuleName PSDesiredStateConfiguration
+
+    Node 'WebServer01'
+    {
+        User LocalAdmin
+        {
+            Ensure = 'Present'
+            UserName = 'AppAdmin'
+            Password = $Credential
+            PasswordNeverExpires = $true
+            PasswordChangeNotAllowed = $false
+        }
+    }
+}
+
+# Use certificate for encryption
+$configData = @{
+    AllNodes = @(
+        @{
+            NodeName = 'WebServer01'
+            CertificateFile = 'C:\Certs\WebServer01.cer'
+            Thumbprint = '1234567890ABCDEF1234567890ABCDEF12345678'
+        }
+    )
+}
+
+$cred = Get-Credential -UserName 'AppAdmin' -Message 'Enter password'
+SecureConfig -Credential $cred -ConfigurationData $configData -OutputPath 'C:\DSC\Secure'
+```
+
+## Best Practices
+
+1. **Separate configuration from data** - Use ConfigurationData parameter
+2. **Use certificates for encryption** - Never use plain text passwords
+3. **Test idempotency** - Run configurations multiple times
+4. **Version control configurations** - Track changes in Git
+5. **Use dependencies** - DependsOn for resource ordering
+6. **Configure LCM appropriately** - Match environment needs
+7. **Use composite resources** - For reusable patterns
+8. **Implement proper error handling** - Validate before applying
+9. **Document node requirements** - Prerequisites and dependencies
+10. **Test in non-production first** - Validate before production deployment
+
+

package/augment-extensions/coding-standards/powershell/rules/error-handling.md

@@ -0,0 +1,314 @@
+# PowerShell Error Handling
+
+Comprehensive error handling patterns and best practices for robust PowerShell code.
+
+## Error Action Preference
+
+### Set Global Preference
+
+```powershell
+# Stop on all errors (recommended for scripts)
+$ErrorActionPreference = 'Stop'
+
+# Continue on errors (default, not recommended for scripts)
+$ErrorActionPreference = 'Continue'
+
+# Silently continue (use sparingly)
+$ErrorActionPreference = 'SilentlyContinue'
+```
+
+### Per-Command Error Action
+
+```powershell
+# Override global preference for specific command
+Get-Item -Path 'C:\NonExistent.txt' -ErrorAction SilentlyContinue
+
+# Use common parameter
+Test-Path -Path $filePath -ErrorAction Stop
+```
+
+## Try-Catch-Finally
+
+### Basic Pattern
+
+```powershell
+try
+{
+    # Code that might throw errors
+    $content = Get-Content -Path $filePath -ErrorAction Stop
+    $data = $content | ConvertFrom-Json
+}
+catch
+{
+    # Handle all errors
+    Write-Error "Failed to process file: $_"
+}
+finally
+{
+    # Always executes (cleanup)
+    if ($fileStream)
+    {
+        $fileStream.Close()
+    }
+}
+```
+
+### Specific Exception Handling
+
+```powershell
+try
+{
+    $result = Invoke-RestMethod -Uri $apiUrl -Method Get
+}
+catch [System.Net.WebException]
+{
+    Write-Error "Network error: $($_.Exception.Message)"
+}
+catch [System.UnauthorizedAccessException]
+{
+    Write-Error "Access denied: $($_.Exception.Message)"
+}
+catch
+{
+    Write-Error "Unexpected error: $($_.Exception.Message)"
+    throw  # Re-throw if you can't handle it
+}
+```
+
+### Nested Try-Catch
+
+```powershell
+try
+{
+    # Outer operation
+    $connection = Connect-Database -Server $server
+    
+    try
+    {
+        # Inner operation
+        $data = Get-DatabaseData -Connection $connection
+    }
+    catch
+    {
+        Write-Warning "Data retrieval failed: $_"
+        # Handle inner error
+    }
+}
+catch
+{
+    Write-Error "Connection failed: $_"
+}
+finally
+{
+    if ($connection)
+    {
+        Disconnect-Database -Connection $connection
+    }
+}
+```
+
+## Error Objects
+
+### Accessing Error Information
+
+```powershell
+try
+{
+    Get-Item -Path 'C:\NonExistent.txt' -ErrorAction Stop
+}
+catch
+{
+    # Current error
+    Write-Output "Error: $($_.Exception.Message)"
+    Write-Output "Type: $($_.Exception.GetType().FullName)"
+    Write-Output "Stack: $($_.ScriptStackTrace)"
+    
+    # Error record properties
+    Write-Output "Category: $($_.CategoryInfo.Category)"
+    Write-Output "Target: $($_.TargetObject)"
+}
+```
+
+### $Error Automatic Variable
+
+```powershell
+# Most recent error
+$Error[0]
+
+# All errors in session
+$Error
+
+# Clear error history
+$Error.Clear()
+```
+
+## Custom Errors
+
+### Throw Custom Errors
+
+```powershell
+function Get-UserAge
+{
+    param([int]$Age)
+    
+    if ($Age -lt 0)
+    {
+        throw "Age cannot be negative: $Age"
+    }
+    
+    if ($Age -gt 150)
+    {
+        throw [System.ArgumentOutOfRangeException]::new(
+            'Age',
+            $Age,
+            'Age must be between 0 and 150'
+        )
+    }
+    
+    return $Age
+}
+```
+
+### Write-Error vs Throw
+
+```powershell
+# Write-Error: Non-terminating (continues execution)
+function Test-WriteError
+{
+    Write-Error "This is a non-terminating error"
+    Write-Output "This still executes"
+}
+
+# Throw: Terminating (stops execution)
+function Test-Throw
+{
+    throw "This is a terminating error"
+    Write-Output "This never executes"
+}
+```
+
+## Validation and Guards
+
+### Parameter Validation
+
+```powershell
+function Get-FileContent
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [ValidateScript({ Test-Path $_ })]
+        [string]$Path,
+        
+        [Parameter()]
+        [ValidateSet('UTF8', 'ASCII', 'Unicode')]
+        [string]$Encoding = 'UTF8'
+    )
+    
+    Get-Content -Path $Path -Encoding $Encoding
+}
+```
+
+### Guard Clauses
+
+```powershell
+function Process-Data
+{
+    param([string]$Data)
+    
+    # Guard clauses at the start
+    if ([string]::IsNullOrWhiteSpace($Data))
+    {
+        throw "Data cannot be null or empty"
+    }
+    
+    if ($Data.Length -gt 1000)
+    {
+        throw "Data exceeds maximum length of 1000 characters"
+    }
+    
+    # Main logic
+    return $Data.ToUpper()
+}
+```
+
+## Best Practices
+
+### 1. Always Use Try-Catch for External Operations
+
+```powershell
+# ✅ Correct
+try
+{
+    $response = Invoke-RestMethod -Uri $apiUrl
+}
+catch
+{
+    Write-Error "API call failed: $_"
+}
+
+# ❌ Incorrect (no error handling)
+$response = Invoke-RestMethod -Uri $apiUrl
+```
+
+### 2. Provide Context in Error Messages
+
+```powershell
+# ✅ Descriptive
+catch
+{
+    Write-Error "Failed to process user '$userName' from file '$filePath': $($_.Exception.Message)"
+}
+
+# ❌ Generic
+catch
+{
+    Write-Error "Error: $_"
+}
+```
+
+### 3. Clean Up Resources
+
+```powershell
+$stream = $null
+try
+{
+    $stream = [System.IO.File]::OpenRead($path)
+    # Process stream
+}
+finally
+{
+    if ($stream)
+    {
+        $stream.Dispose()
+    }
+}
+```
+
+### 4. Don't Swallow Errors
+
+```powershell
+# ❌ Bad: Silent failure
+try
+{
+    Remove-Item $path
+}
+catch
+{
+    # Empty catch - error is lost
+}
+
+# ✅ Good: Log or re-throw
+try
+{
+    Remove-Item $path
+}
+catch
+{
+    Write-Warning "Could not remove $path: $_"
+    # Or re-throw if critical
+    throw
+}
+```
+