From 3e011c5e388ed0a5c3dd0bd9a5a3cd0b07a6a335 Mon Sep 17 00:00:00 2001 From: Matt McElreath Date: Wed, 13 May 2026 22:48:44 -0400 Subject: [PATCH 1/2] Added comment based help --- .../func_GetDefaultExcludeVariables.ps1 | 24 +++++++ .../public/Invoke-AZParallelProxy.ps1 | 37 ++++++++++ .../public/Invoke-ForEachParallelProxy.ps1 | 70 +++++++++++++++++++ .../public/Invoke-MultiSessionCommand.ps1 | 65 ++++++++++++++++- .../public/Invoke-PSSessionProxy.ps1 | 64 +++++++++++++++-- 5 files changed, 254 insertions(+), 6 deletions(-) diff --git a/PSMultiPass/functions/private/func_GetDefaultExcludeVariables.ps1 b/PSMultiPass/functions/private/func_GetDefaultExcludeVariables.ps1 index b921270..9db79cb 100644 --- a/PSMultiPass/functions/private/func_GetDefaultExcludeVariables.ps1 +++ b/PSMultiPass/functions/private/func_GetDefaultExcludeVariables.ps1 @@ -1,3 +1,27 @@ +<# +.SYNOPSIS + Gets a list of default variables to exclude from parallel execution. + +.DESCRIPTION + This private function returns a collection of variable names that should be excluded + when importing variables into parallel script blocks. It combines: + - Default cmdlet binding parameters (like Verbose, Debug, etc.) + - Current bound parameters + - Standard user environment variables + +.EXAMPLE + PS> $excludeVars = func_GetDefaultExcludeVariables + PS> $excludeVars | Select-Object -First 5 + + Returns a list of variable names to exclude from parallel import. + +.NOTES + This is a private helper function used internally by Invoke-ForEachParallelProxy. + It helps prevent conflicts and unnecessary variable passing in parallel execution contexts. + +.LINK + Invoke-ForEachParallelProxy +#> function func_GetDefaultExcludeVariables { Function _temp { [cmdletbinding(SupportsShouldProcess=$True)] param() diff --git a/PSMultiPass/functions/public/Invoke-AZParallelProxy.ps1 b/PSMultiPass/functions/public/Invoke-AZParallelProxy.ps1 index e58a0de..f1fc396 100644 --- a/PSMultiPass/functions/public/Invoke-AZParallelProxy.ps1 +++ b/PSMultiPass/functions/public/Invoke-AZParallelProxy.ps1 @@ -1,3 +1,40 @@ +<# +.SYNOPSIS + Executes a script block in parallel across multiple Azure subscriptions. + +.DESCRIPTION + This function iterates through multiple Azure subscriptions in parallel, setting the + Azure context for each subscription before executing the provided script block. + It uses Invoke-ForEachParallelProxy internally to manage parallel execution. + +.PARAMETER Subscriptions + An array of subscription IDs or names to execute the script block against. + The function will set the Azure context for each subscription before execution. + +.PARAMETER ScriptBlock + The script block to execute in each subscription context. + The subscription name/ID is available as $_ within the script block. + +.PARAMETER ThrottleLimit + The maximum number of subscription contexts to process in parallel. + Default value is 5. Increase to process more subscriptions simultaneously. + +.EXAMPLE + PS> $subs = @("prod-sub-1", "prod-sub-2", "dev-sub-1") + PS> Invoke-AZParallelProxy -Subscriptions $subs -ScriptBlock { + PS> Get-AzVirtualMachine | Select-Object Name, ResourceGroupName + PS> } -ThrottleLimit 3 + + Lists all virtual machines across three subscriptions in parallel. + +.NOTES + Requires Azure PowerShell module (Az.Accounts) to be installed and authenticated. + User variables are automatically imported into the parallel execution context. + +.LINK + Invoke-ForEachParallelProxy + Set-AzContext +#> function Invoke-AZParallelProxy { [CmdletBinding()] param ( diff --git a/PSMultiPass/functions/public/Invoke-ForEachParallelProxy.ps1 b/PSMultiPass/functions/public/Invoke-ForEachParallelProxy.ps1 index 0d0749b..368d5ff 100644 --- a/PSMultiPass/functions/public/Invoke-ForEachParallelProxy.ps1 +++ b/PSMultiPass/functions/public/Invoke-ForEachParallelProxy.ps1 @@ -1,3 +1,73 @@ +<# +.SYNOPSIS + Executes a script block in parallel across multiple input objects with variable management. + +.DESCRIPTION + This function wraps ForEach-Object -Parallel to provide enhanced variable importing capabilities + and easier parallel execution management. It allows selective importing of user variables into + the parallel context while excluding system and cmdlet-binding variables. + + The input object is available as $_ within the script block, and parallel execution is + controlled via ThrottleLimit, TimeoutSeconds, and optional job execution. + +.PARAMETER InputObject + The object(s) to iterate through in parallel. Accepts arrays or pipeline input. + +.PARAMETER ScriptBlock + The script block to execute for each input object. The current object is available as $_. + +.PARAMETER ThrottleLimit + The maximum number of parallel threads to execute simultaneously. + Default value is 5. Increase for more parallelism on systems with more cores. + +.PARAMETER ImportUserVariables + Switch to enable importing current session variables into the parallel execution context. + By default, only necessary variables are imported to minimize context overhead. + +.PARAMETER IncludeUserVariableName + Specify an array of variable names to include when ImportUserVariables is enabled. + If specified, only these variables will be imported (whitelist mode). + +.PARAMETER ExcludeUserVariableName + Specify an array of variable names to exclude from import when ImportUserVariables is enabled. + Works in conjunction with default exclusions (blacklist mode). + +.PARAMETER TimeoutSeconds + The timeout in seconds for each parallel operation. Default 0 (no timeout). + Ignored if AsJob is specified. + +.PARAMETER AsJob + Switch to return the operation as a background job instead of waiting for completion. + +.PARAMETER UseNewRunspace + Switch to use a new runspace for each parallel iteration. + +.PARAMETER Confirm + Switch to prompt for confirmation before executing the parallel operation. + +.EXAMPLE + PS> 1..10 | Invoke-ForEachParallelProxy -ScriptBlock { $_ * 2 } -ThrottleLimit 5 + + Multiplies numbers 1-10 by 2 in parallel with 5 concurrent threads. + +.EXAMPLE + PS> $data = @("file1.txt", "file2.txt", "file3.txt") + PS> $data | Invoke-ForEachParallelProxy -ScriptBlock { + PS> Get-Content $_ | Measure-Object -Line + PS> } -ImportUserVariables + + Processes multiple files in parallel with access to current session variables. + +.NOTES + Variables are imported intelligently, excluding system variables and cmdlet-binding parameters + to reduce context overhead. Use IncludeUserVariableName or ExcludeUserVariableName to fine-tune + which variables are passed to parallel contexts. + +.LINK + ForEach-Object + Invoke-AZParallelProxy + func_GetDefaultExcludeVariables +#> function Invoke-ForEachParallelProxy { [CmdletBinding()] param ( diff --git a/PSMultiPass/functions/public/Invoke-MultiSessionCommand.ps1 b/PSMultiPass/functions/public/Invoke-MultiSessionCommand.ps1 index 6ac8a32..1d141c6 100644 --- a/PSMultiPass/functions/public/Invoke-MultiSessionCommand.ps1 +++ b/PSMultiPass/functions/public/Invoke-MultiSessionCommand.ps1 @@ -1,8 +1,69 @@ -### Possibly change functionality to include just creating sessions using error checking on -### failed sessions and returning sessions as an output. +<# +.SYNOPSIS + Executes a script block on multiple remote computers using PSSession. + +.DESCRIPTION + This function creates PSSession connections to multiple computers and executes a script block + in parallel across all sessions. It handles session creation with error checking, command + execution with throttling, and automatic session cleanup. + + Returns an object containing command output and connection error information for failed connections. + +.PARAMETER ComputerName + An array of computer names or IP addresses to connect to for command execution. + +.PARAMETER Credential + PSCredential object containing the username and password for remote authentication. + +.PARAMETER ScriptBlock + The script block to execute on each remote computer. + +.PARAMETER CommandThrottleLimit + The maximum number of commands to execute in parallel across sessions. + Default value is 10. +.PARAMETER SessionOption + Optional PSSessionOption object to customize session connection behavior. + If not specified, default session options are used. +.PARAMETER SessionThrottleLimit + The maximum number of PSSession connections to establish in parallel during creation. + Default value is 32. + +.PARAMETER CleanUpSessions + Switch to automatically remove all PSSession connections after command execution. + Default is $true. Set to $false to keep sessions open for reuse. + +.EXAMPLE + PS> $cred = Get-Credential + PS> $computers = @("Server1", "Server2", "Server3") + PS> $result = Invoke-MultiSessionCommand -ComputerName $computers ` + PS> -Credential $cred -ScriptBlock { Get-Process -Name svchost } -CommandThrottleLimit 5 + PS> $result.CommandOutput + + Retrieves svchost processes from three servers in parallel. + +.EXAMPLE + PS> $computers = @("Server1", "Server2") + PS> $result = Invoke-MultiSessionCommand -ComputerName $computers ` + PS> -Credential $cred -ScriptBlock { whoami } -CleanUpSessions $false + PS> $result.ConnectionErrorInfo + + Executes whoami command and keeps sessions open for reuse. Check ConnectionErrorInfo for connection failures. + +.NOTES + - Failed connections are tracked in the ConnectionErrorInfo property of the output + - Sessions are cleaned up by default unless CleanUpSessions is set to $false + - Use SessionOption to customize connection behavior (e.g., SkipCertificateCheck) + - CommandThrottleLimit controls parallelism during command execution, not session creation + +.LINK + Invoke-PSSessionProxy + New-PSSession + Invoke-Command + Remove-PSSession +#> function Invoke-MultiSessionCommand { [CmdletBinding()] Param ( diff --git a/PSMultiPass/functions/public/Invoke-PSSessionProxy.ps1 b/PSMultiPass/functions/public/Invoke-PSSessionProxy.ps1 index b158c04..ca1664f 100644 --- a/PSMultiPass/functions/public/Invoke-PSSessionProxy.ps1 +++ b/PSMultiPass/functions/public/Invoke-PSSessionProxy.ps1 @@ -1,8 +1,64 @@ -### Possibly change functionality to include just creating sessions using error checking on -### failed sessions and returning sessions as an output. - - +<# +.SYNOPSIS + Creates PSSession connections to multiple remote computers with error handling. + +.DESCRIPTION + This function establishes PSSession connections to multiple computers in parallel with + throttled connection attempts. It handles connection errors gracefully and returns both + successful sessions and connection error information. + + Useful as a foundation for remote command execution or as a prerequisite for other + remote administration tasks. + +.PARAMETER ComputerName + An array of computer names or IP addresses to establish PSSession connections with. + +.PARAMETER Credential + PSCredential object containing the username and password for remote authentication. + +.PARAMETER SessionOption + Optional PSSessionOption object to customize session connection behavior. + Examples: SkipCertificateCheck, SkipCACheck, SkipRevocationCheck for remote connections. + If not specified, default session options are used. + +.PARAMETER SessionThrottleLimit + The maximum number of concurrent PSSession connection attempts. + Default value is 32. Higher values allow faster bulk session creation on capable systems. + +.EXAMPLE + PS> $cred = Get-Credential + PS> $computers = @("Server1", "Server2", "Server3", "Server4") + PS> $result = Invoke-PSSessionProxy -ComputerName $computers -Credential $cred -SessionThrottleLimit 10 + PS> $result.Sessions + + Creates PSSession connections to four servers with a maximum of 10 concurrent connections. + +.EXAMPLE + PS> $computers = @("RemoteHost1", "RemoteHost2") + PS> $opts = New-PSSessionOption -SkipCertificateCheck + PS> $result = Invoke-PSSessionProxy -ComputerName $computers -Credential $cred -SessionOption $opts + PS> $result.ConnectionErrorInfo + + Creates sessions with custom options and displays any connection errors. + +.OUTPUTS + PSCustomObject with the following properties: + - Sessions: Array of successfully created PSSession objects + - ConnectionErrorInfo: Array of connection failures with error details + +.NOTES + - Connection errors are captured but do not stop the function from attempting other connections + - Sessions are returned as PSSession objects ready for use with Invoke-Command + - Use SessionThrottleLimit to balance speed vs. system resource usage + - Sessions must be cleaned up manually using Remove-PSSession when finished + +.LINK + New-PSSession + Invoke-Command + Remove-PSSession + New-PSSessionOption +#> function Invoke-PSSessionProxy { [CmdletBinding()] Param ( From 44f940a3141c8f2ec5acb0ede564e928ee74caed Mon Sep 17 00:00:00 2001 From: Matt McElreath Date: Wed, 13 May 2026 22:54:19 -0400 Subject: [PATCH 2/2] version 0.0.7 --- PSMultiPass/PSMultiPass.psd1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PSMultiPass/PSMultiPass.psd1 b/PSMultiPass/PSMultiPass.psd1 index b7c5fc1..b41be63 100644 --- a/PSMultiPass/PSMultiPass.psd1 +++ b/PSMultiPass/PSMultiPass.psd1 @@ -12,7 +12,7 @@ RootModule = 'PSMultiPass.psm1' # Version number of this module. -ModuleVersion = '0.0.6' +ModuleVersion = '0.0.7' # Supported PSEditions # CompatiblePSEditions = @()