Merge remote-tracking branch 'origin/development' into claude/issue-10033-20251202-1615

Author: andreasjordan

.github/CONTRIBUTING-TESTING.md

@@ -23,8 +23,8 @@
    - Install: `Install-Module PSScriptAnalyzer -RequiredVersion 1.18.2`
    - Used by: `Invoke-DbatoolsFormatter` command and CI builds
 
-3. **Pester v5.6.1** - Required for running tests
-   - Install: `Install-Module Pester -RequiredVersion 5.6.1`
+3. **Pester v5.7.1** - Required for running tests
+   - Install: `Install-Module Pester -RequiredVersion 5.7.1`
    - Tests MUST use Pester v5 syntax (no `-ForEach` parameter, strict scoping)
 
 ## PR Summary Guidelines
@@ -151,7 +151,7 @@ When generating PR summaries:
 Install-Module PSScriptAnalyzer -RequiredVersion 1.18.2 -Force
 
 # 3. Install Pester (for testing)
-Install-Module Pester -RequiredVersion 5.6.1 -Force
+Install-Module Pester -RequiredVersion 5.7.1 -Force
 
 # 4. Import the module to verify setup
 Import-Module .\dbatools.psd1
@@ -431,9 +431,9 @@ Context "Parameter validation" {
 ## Environment Variables & Test Config
 
 **AppVeyor test instances:**
-- `$script:instance1` = SQL Server 2008 R2
-- `$script:instance2` = SQL Server 2016
-- `$script:instance3` = SQL Server 2017
+- `$TestConfig.InstanceSingle` = SQL Server 2022
+- `$TestConfig.InstanceMulti1` = SQL Server 2022
+- `$TestConfig.InstanceMulti2` = SQL Server 2017
 
 **GitHub Actions:**
 - Linux: `localhost`, `localhost:14333` (Docker containers)

.github/copilot-instructions.md

@@ -1,4 +1,4 @@
 {
-  "version": "2025.11.29-preview-new-20251129132142",
-  "notes": "Version of dbatools.library to use for CI/CD and development."
+  "version": "2025.12.28",
+  "notes": "Version of dbatools.library to use for CI/CD and development"
 }

.github/dbatools-library-version.json

@@ -0,0 +1,145 @@
+# Pester v4 to v5 Migration Guide
+
+## CORE PESTER v5 REQUIREMENTS
+
+### Mandatory Header Structure
+Every test file must include this header:
+
+```powershell
+#Requires -Module @{ ModuleName="Pester"; ModuleVersion="5.0" }
+param(
+    $ModuleName  = "YourModuleName",
+    $CommandName = "StaticCommandName",  # Always use static command name
+    $PSDefaultParameterValues = $TestConfig.Defaults
+)
+```
+
+**Critical Requirements:**
+- Replace "StaticCommandName" with the actual command name being tested as a static string
+- **Remove all dynamic command name derivation** from file paths or directory structures
+- Strip out all `knownParameters` validation code (old Pester v4 pattern)
+
+### Critical Structural Changes
+
+#### Test Block Organization
+- **All setup code** must be in `BeforeAll` or `BeforeEach` blocks
+- **All cleanup code** must be in `AfterAll` or `AfterEach` blocks
+- **All test assertions** must be in `It` blocks
+- **No loose code** allowed in `Describe` or `Context` blocks
+- **Never use `-ForEach` parameter** on any test blocks
+
+```powershell
+# Pester v5 Structure
+Describe $CommandName {
+    BeforeAll {
+        # All setup code here
+    }
+
+    AfterAll {
+        # All cleanup code here
+    }
+
+    Context "Specific scenario" {
+        BeforeAll {
+            # Context-specific setup
+        }
+
+        It "Should do something" {
+            # Test assertions only
+        }
+    }
+}
+```
+
+### Variable Scoping Changes
+- Replace all `$script:` with `$global:` for variables that need to persist across Pester blocks
+- Pester v5 has stricter scoping - variables in `BeforeAll` may not be available in `It` blocks without proper scoping
+- Add explicit scope declarations when variables cross Pester block boundaries
+
+### PowerShell Syntax Updates Required for Pester v5
+
+#### Variable References
+- Replace `$_` with `$PSItem` (recommended for clarity, except where `$_` is required for compatibility)
+
+#### Skip Conditions
+- Use boolean values for skip conditions (`$true`/`$false`), not strings
+
+#### Array Operations
+- Replace `$results.Count` with `$results.Status.Count` for accurate counting
+- Add explicit array initialization: `$array = @()`
+- Wrap result collection in array subexpression operator: `$results = @(Get-Something)`
+
+#### Parameter Quoting
+Remove unnecessary quotes from parameter values:
+```powershell
+# Convert this:
+"$CommandName" -Tag "IntegrationTests"
+# To this:
+$CommandName -Tag IntegrationTests
+```
+
+#### String Formatting
+- Replace multi-line concatenated strings with here-strings when appropriate
+
+### Resource Management
+- Always include cleanup code in `AfterAll`/`AfterEach` blocks
+- Use `-ErrorAction SilentlyContinue` on cleanup operations
+- Create unique temporary resources using `Get-Random`
+
+```powershell
+BeforeAll {
+    $tempPath = "$env:TEMP\TestRun-$(Get-Random)"
+    $resourcesToCleanup = @()
+}
+
+AfterAll {
+    Remove-Item -Path $tempPath -Recurse -ErrorAction SilentlyContinue
+    Remove-Item -Path $resourcesToCleanup -ErrorAction SilentlyContinue
+}
+```
+
+### Where-Object Conversion Rules
+Transform Where-Object script blocks to direct property comparisons when possible:
+
+```powershell
+# Pester v5 Preferred - direct property comparison
+$master = $databases | Where-Object Name -eq "master"
+$systemDbs = $databases | Where-Object Name -in "master", "model", "msdb", "tempdb"
+
+# Required - script block for complex filtering only
+$hasParameters = (Get-Command $CommandName).Parameters.Values.Name | Where-Object { $PSItem -notin ("WhatIf", "Confirm") }
+```
+
+Only use script blocks when direct property comparison is not possible.
+
+## MIGRATION CHECKLIST
+
+**Header and Structure:**
+- [ ] Added mandatory `#Requires` header
+- [ ] Replaced dynamic command name derivation with static command name
+- [ ] Stripped out old `knownParameters` validation code
+- [ ] Moved all loose code into appropriate `BeforeAll`/`AfterAll` blocks
+- [ ] Removed any `-ForEach` parameters from test blocks
+- [ ] All test assertions properly placed in `It` blocks
+
+**Variable Scoping:**
+- [ ] Changed `$script:` to `$global:` where needed
+- [ ] Added explicit scope declarations for cross-block variables
+- [ ] Verified variable scoping works across Pester blocks
+
+**Syntax Transformations:**
+- [ ] Replaced `$_` with `$PSItem` (except where compatibility requires `$_`)
+- [ ] Replaced string-based skip conditions with boolean values
+- [ ] Updated array operations (`$results.Count` → `$results.Status.Count`)
+- [ ] Added explicit array initialization where needed
+- [ ] Removed unnecessary parameter quotes
+- [ ] Applied Where-Object conversions where possible
+- [ ] Replaced concatenated strings with here-strings where appropriate
+
+**Resource Management:**
+- [ ] Added proper cleanup code with error suppression
+- [ ] Created unique temporary resources using `Get-Random`
+- [ ] Ensured all created resources have corresponding cleanup
+
+**Migration Policy:**
+- [ ] Do not invent new integration tests - if they don't exist, there's a reason

.github/prompts/migration.md

@@ -0,0 +1,126 @@
+# Pipeline Output Patterns
+
+**CRITICAL RULE**: NEVER collect objects in an ArrayList or array and output them at the end. Output objects to the pipeline immediately as they are created.
+
+## Why Immediate Output
+
+- **Memory Efficiency**: Objects are released to the pipeline immediately, not held in memory
+- **User Experience**: Users see results streaming in real-time, not waiting until the end
+- **Pipeline Compatibility**: Enables proper pipeline chaining and early termination (Ctrl+C)
+- **Error Resilience**: Partial results are available even if the command fails partway through
+
+## Correct Pattern - Output Immediately
+
+```powershell
+foreach ($instance in $SqlInstance) {
+    $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
+
+    foreach ($db in $server.Databases) {
+        # Output each object immediately to the pipeline
+        [PSCustomObject]@{
+            ComputerName = $server.ComputerName
+            InstanceName = $server.ServiceName
+            SqlInstance  = $server.DomainInstanceName
+            Database     = $db.Name
+            Size         = $db.Size
+        }
+    }
+}
+```
+
+## Wrong Patterns - DO NOT USE
+
+### ArrayList Collection (OLD PATTERN)
+
+```powershell
+# WRONG - This is an outdated anti-pattern
+$results = New-Object System.Collections.ArrayList
+
+foreach ($instance in $SqlInstance) {
+    $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
+
+    foreach ($db in $server.Databases) {
+        $null = $results.Add([PSCustomObject]@{
+            ComputerName = $server.ComputerName
+            Database     = $db.Name
+        })
+    }
+}
+
+# WRONG - Holding everything until the end
+$results
+```
+
+### Array Concatenation (Worst Performance)
+
+```powershell
+# WRONG - Array concatenation is extremely slow
+$results = @()
+
+foreach ($db in $databases) {
+    $results += [PSCustomObject]@{
+        Name = $db.Name
+    }
+}
+
+$results
+```
+
+## No -Detailed or -Simple Parameters
+
+Do NOT create `-Detailed` or `-Simple` switch parameters that change the output object structure. This is an outdated pattern that creates confusion and breaks pipeline expectations.
+
+```powershell
+# WRONG - Do not create output mode switches
+param(
+    [switch]$Detailed,
+    [switch]$Simple
+)
+
+if ($Detailed) {
+    # Return more properties
+} elseif ($Simple) {
+    # Return fewer properties
+}
+```
+
+Instead, return a consistent object with all relevant properties. Users can select the properties they want with `Select-Object`.
+
+## Process Block Pattern
+
+When using `ValueFromPipeline`, output in the `process` block, not `end`:
+
+```powershell
+function Get-DbaExample {
+    [CmdletBinding()]
+    param (
+        [Parameter(ValueFromPipeline)]
+        [DbaInstanceParameter[]]$SqlInstance,
+        [PSCredential]$SqlCredential
+    )
+
+    process {
+        foreach ($instance in $SqlInstance) {
+            $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
+
+            foreach ($item in $server.SomeCollection) {
+                # Output immediately in process block
+                [PSCustomObject]@{
+                    ComputerName = $server.ComputerName
+                    InstanceName = $server.ServiceName
+                    SqlInstance  = $server.DomainInstanceName
+                    Name         = $item.Name
+                }
+            }
+        }
+    }
+}
+```
+
+## Summary
+
+- Output objects immediately as they are created
+- Never use ArrayList, Generic.List, or array += to collect results
+- Never use `-Detailed`/`-Simple` output mode switches
+- Process pipeline input in the `process` block, not `end`
+- Let PowerShell's pipeline handle the collection if the user needs it

.github/prompts/pipeline-output.md

@@ -0,0 +1,13 @@
+Pester v4 to v5 Migration
+
+**MIGRATE** the Pester test file `--FILEPATH--` from version 4 to version 5. **APPLY ALL CHANGES DIRECTLY TO THE FILE AND SAVE IT.**
+
+Follow the migration guidelines in style.md. This is a PowerShell module test file.
+
+Command name:
+--CMDNAME--
+
+Parameters for this command:
+--PARMZ--
+
+**IMPORTANT**: Write all changes directly to the file. Do not just describe the changes - implement them and save the updated file. Verify your changes adhere to the coding and migration guidelines before saving.