ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__py3-none-any.whl

ansible/executor/powershell/module_wrapper.ps1

@@ -1,229 +1,238 @@
-# (c) 2018 Ansible Project
+# (c) 2025 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-<#
-.SYNOPSIS
-Invokes an Ansible module in a new Runspace. This cmdlet will output the
-module's output and write any errors to the error stream of the current
-host.
-
-.PARAMETER Scripts
-[Object[]] String or ScriptBlocks to execute.
-
-.PARAMETER Variables
-[System.Collections.ArrayList] The variables to set in the new Pipeline.
-Each value is a hashtable that contains the parameters to use with
-Set-Variable;
-    Name: the name of the variable to set
-    Value: the value of the variable to set
-    Scope: the scope of the variable
-
-.PARAMETER Environment
-[System.Collections.IDictionary] A Dictionary of environment key/values to
-set in the new Pipeline.
-
-.PARAMETER Modules
-[System.Collections.IDictionary] A Dictionary of PowerShell modules to
-import into the new Pipeline. The key is the name of the module and the
-value is a base64 string of the module util code.
-
-.PARAMETER ModuleName
-[String] The name of the module that is being executed.
-
-.PARAMETER Breakpoints
-A list of line breakpoints to add to the runspace debugger. This is used to
-track module and module_utils coverage.
-#>
+using namespace System.Collections
+using namespace System.IO
+using namespace System.Management.Automation
+using namespace System.Management.Automation.Language
+using namespace System.Management.Automation.Security
+using namespace System.Text
+
+[CmdletBinding()]
 param(
-    [Object[]]$Scripts,
-    [System.Collections.ArrayList][AllowEmptyCollection()]$Variables,
-    [System.Collections.IDictionary]$Environment,
-    [System.Collections.IDictionary]$Modules,
-    [String]$ModuleName,
-    [System.Management.Automation.LineBreakpoint[]]$Breakpoints = @()
+    [Parameter(Mandatory)]
+    [string]
+    $Script,
+
+    [Parameter()]
+    [IDictionary[]]
+    [AllowEmptyCollection()]
+    $Variables = @(),
+
+    [Parameter()]
+    [IDictionary]
+    $Environment,
+
+    [Parameter()]
+    [AllowEmptyCollection()]
+    [string[]]
+    $CSharpModules,
+
+    [Parameter()]
+    [AllowEmptyCollection()]
+    [string[]]
+    $PowerShellModules,
+
+    [Parameter()]
+    [LineBreakpoint[]]
+    $Breakpoints,
+
+    [Parameter()]
+    [switch]
+    $ForModule
 )
 
-Write-AnsibleLog "INFO - creating new PowerShell pipeline for $ModuleName" "module_wrapper"
+Function Write-AnsibleErrorDetail {
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory)]
+        [System.Management.Automation.ErrorRecord]
+        $ErrorRecord,
+
+        [Parameter()]
+        [switch]
+        $ForModule
+    )
+
+    # Be more defensive when trying to find the InnerException in case it isn't
+    # set. This shouldn't ever be the case but if it is then it makes it more
+    # difficult to track down the problem.
+    if ($ErrorRecord.Exception.InnerException.ErrorRecord) {
+        $ErrorRecord = $ErrorRecord.Exception.InnerException.ErrorRecord
+    }
+
+    $exception = @(
+        "$ErrorRecord"
+
+        # stderr from sub processes have this error id, we don't want to format those errors
+        # like a normal powershell error record.
+        if ($ErrorRecord.FullyQualifiedErrorId -notin @('NativeCommandError', 'NativeCommandErrorMessage')) {
+            "$($ErrorRecord.InvocationInfo.PositionMessage)"
+            "+ CategoryInfo          : $($ErrorRecord.CategoryInfo)"
+            "+ FullyQualifiedErrorId : $($ErrorRecord.FullyQualifiedErrorId)"
+            ""
+            "ScriptStackTrace:"
+            "$($ErrorRecord.ScriptStackTrace)"
+
+            if ($ErrorRecord.Exception.StackTrace) {
+                "$($ErrorRecord.Exception.StackTrace)"
+            }
+        }
+    ) -join ([Environment]::NewLine)
+
+    if ($ForModule) {
+        @{
+            failed = $true
+            msg = "Unhandled exception while executing module: $ErrorRecord"
+            exception = $exception
+        } | ConvertTo-Json -Compress
+    }
+    else {
+        $host.UI.WriteErrorLine($exception)
+    }
+}
+
 $ps = [PowerShell]::Create()
 
-# do not set ErrorActionPreference for script
-if ($ModuleName -ne "script") {
+if ($ForModule) {
     $ps.Runspace.SessionStateProxy.SetVariable("ErrorActionPreference", "Stop")
 }
-
-# force input encoding to preamble-free UTF8 so PS sub-processes (eg,
-# Start-Job) don't blow up. This is only required for WinRM, a PSRP
-# runspace doesn't have a host console and this will bomb out
-if ($host.Name -eq "ConsoleHost") {
-    Write-AnsibleLog "INFO - setting console input encoding to UTF8 for $ModuleName" "module_wrapper"
-    $ps.AddScript('[Console]::InputEncoding = New-Object Text.UTF8Encoding $false').AddStatement() > $null
+else {
+    # For script files we want to ensure we load it as UTF-8. We don't set this
+    # for modules as they are loaded from memory whereas a script is loaded
+    # from disk as part of the script being run than by us.
+    Set-WinPSDefaultFileEncoding
 }
 
-# set the variables
 foreach ($variable in $Variables) {
-    Write-AnsibleLog "INFO - setting variable '$($variable.Name)' for $ModuleName" "module_wrapper"
-    $ps.AddCommand("Set-Variable").AddParameters($variable).AddStatement() > $null
-}
-
-# set the environment vars
-if ($Environment) {
-    # Escaping quotes can be problematic, instead just pass the string to the runspace and set it directly.
-    Write-AnsibleLog "INFO - setting environment vars for $ModuleName" "module_wrapper"
-    $ps.Runspace.SessionStateProxy.SetVariable("_AnsibleEnvironment", $Environment)
-    $ps.AddScript(@'
-foreach ($env_kv in $_AnsibleEnvironment.GetEnumerator()) {
-    [System.Environment]::SetEnvironmentVariable($env_kv.Key, $env_kv.Value)
-}
-'@).AddStatement() > $null
+    $null = $ps.AddCommand("Set-Variable").AddParameters($variable).AddStatement()
 }
 
-# import the PS modules
-if ($Modules) {
-    foreach ($module in $Modules.GetEnumerator()) {
-        Write-AnsibleLog "INFO - create module util '$($module.Key)' for $ModuleName" "module_wrapper"
-        $module_name = $module.Key
-        $module_code = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($module.Value))
-        $ps.AddCommand("New-Module").AddParameters(@{Name = $module_name; ScriptBlock = [ScriptBlock]::Create($module_code) }) > $null
-        $ps.AddCommand("Import-Module").AddParameter("WarningAction", "SilentlyContinue") > $null
-        $ps.AddCommand("Out-Null").AddStatement() > $null
-    }
+# env vars are process side so we can just set them here.
+foreach ($env in $Environment.GetEnumerator()) {
+    [Environment]::SetEnvironmentVariable($env.Key, $env.Value)
 }
 
-# redefine Write-Host to dump to output instead of failing
-# lots of scripts still use it
-$ps.AddScript('Function Write-Host($msg) { Write-Output -InputObject $msg }').AddStatement() > $null
+# Redefine Write-Host to dump to output instead of failing, lots of scripts
+# still use it.
+$null = $ps.AddScript('Function Write-Host($msg) { Write-Output -InputObject $msg }').AddStatement()
 
-# add the scripts and run
-foreach ($script in $Scripts) {
-    $ps.AddScript($script).AddStatement() > $null
-}
+$scriptInfo = Get-AnsibleScript -Name $Script
+if ($scriptInfo.ShouldConstrain) {
+    # Fail if there are any module utils, in the future we may allow unsigned
+    # PowerShell utils in CLM but for now we don't.
+    if ($PowerShellModules -or $CSharpModules) {
+        throw "Cannot run untrusted PowerShell script '$Script' in ConstrainedLanguage mode with module util imports."
+    }
 
-if ($Breakpoints.Count -gt 0) {
-    Write-AnsibleLog "INFO - adding breakpoint to runspace that will run the modules" "module_wrapper"
-    if ($PSVersionTable.PSVersion.Major -eq 3) {
-        # The SetBreakpoints method was only added in PowerShell v4+. We need to rely on a private method to
-        # achieve the same functionality in this older PowerShell version. This should be removed once we drop
-        # support for PowerShell v3.
-        $set_method = $ps.Runspace.Debugger.GetType().GetMethod(
-            'AddLineBreakpoint', [System.Reflection.BindingFlags]'Instance, NonPublic'
-        )
-        foreach ($b in $Breakpoints) {
-            $set_method.Invoke($ps.Runspace.Debugger, [Object[]]@(, $b)) > $null
+    # If the module is marked as needing to be constrained then we set the
+    # language mode to ConstrainedLanguage so that when parsed inside the
+    # Runspace it will run in CLM. We need to run it from a filepath as in
+    # CLM we cannot call the methods needed to create the ScriptBlock and we
+    # need to be in CLM to downgrade the language mode.
+    $null = $ps.AddScript('$ExecutionContext.SessionState.LanguageMode = "ConstrainedLanguage"').AddStatement()
+    $scriptPath = New-TempAnsibleFile -FileName $Script -Content $scriptInfo.Script
+    $null = $ps.AddCommand($scriptPath, $false).AddStatement()
+}
+else {
+    if ($PowerShellModules) {
+        foreach ($utilName in $PowerShellModules) {
+            $utilInfo = Get-AnsibleScript -Name $utilName
+            if ($utilInfo.ShouldConstrain) {
+                throw "PowerShell module util '$utilName' is not trusted and cannot be loaded."
+            }
+
+            $null = $ps.AddScript(@'
+param ($Name, $Script)
+
+$moduleName = [System.IO.Path]::GetFileNameWithoutExtension($Name)
+$sbk = [System.Management.Automation.Language.Parser]::ParseInput(
+    $Script,
+    $Name,
+    [ref]$null,
+    [ref]$null).GetScriptBlock()
+
+New-Module -Name $moduleName -ScriptBlock $sbk |
+    Import-Module -WarningAction SilentlyContinue -Scope Global
+'@, $true)
+            $null = $ps.AddParameters(
+                @{
+                    Name = $utilName
+                    Script = $utilInfo.Script
+                }
+            ).AddStatement()
         }
     }
-    else {
-        $ps.Runspace.Debugger.SetBreakpoints($Breakpoints)
-    }
-}
 
-Write-AnsibleLog "INFO - start module exec with Invoke() - $ModuleName" "module_wrapper"
+    if ($CSharpModules) {
+        # C# utils are process wide so just load them here.
+        Import-CSharpUtil -Name $CSharpModules
+    }
 
-# temporarily override the stdout stream and create our own in a StringBuilder
-# we use this to ensure there's always an Out pipe and that we capture the
-# output for things like async or psrp
-$orig_out = [System.Console]::Out
-$sb = New-Object -TypeName System.Text.StringBuilder
-$new_out = New-Object -TypeName System.IO.StringWriter -ArgumentList $sb
+    # We invoke it through a command with useLocalScope $false to
+    # ensure the code runs with it's own $script: scope. It also
+    # cleans up the StackTrace on errors by not showing the stub
+    # execution line and starts immediately at the module "cmd".
+    $null = $ps.AddScript(@'
+${function:<AnsibleModule>} = [System.Management.Automation.Language.Parser]::ParseInput(
+    $args[0],
+    $args[1],
+    [ref]$null,
+    [ref]$null).GetScriptBlock()
+'@).AddArgument($scriptInfo.Script).AddArgument($Script).AddStatement()
+    $null = $ps.AddCommand('<AnsibleModule>', $false).AddStatement()
+}
+
+if ($Breakpoints) {
+    $ps.Runspace.Debugger.SetBreakpoints($Breakpoints)
+}
+
+# Temporarily override the stdout stream and create our own in a StringBuilder.
+# We use this to ensure there's always an Out pipe and that we capture the
+# output for things like async or psrp.
+$origOut = [Console]::Out
+$sb = [StringBuilder]::new()
 try {
-    [System.Console]::SetOut($new_out)
-    $module_output = $ps.Invoke()
+    $newOut = [StringWriter]::new($sb)
+    [Console]::SetOut($newOut)
+
+    $modOut = @($ps.Invoke())
 }
 catch {
-    # uncaught exception while executing module, present a prettier error for
-    # Ansible to parse
-    $error_params = @{
-        Message = "Unhandled exception while executing module"
-        ErrorRecord = $_
-    }
-
-    # Be more defensive when trying to find the InnerException in case it isn't
-    # set. This shouldn't ever be the case but if it is then it makes it more
-    # difficult to track down the problem.
-    if ($_.Exception.PSObject.Properties.Name -contains "InnerException") {
-        $inner_exception = $_.Exception.InnerException
-        if ($inner_exception.PSObject.Properties.Name -contains "ErrorRecord") {
-            $error_params.ErrorRecord = $inner_exception.ErrorRecord
-        }
+    Write-AnsibleErrorDetail -ErrorRecord $_ -ForModule:$ForModule
+    if ($ForModule) {
+        $host.SetShouldExit(1)
+        return
     }
-
-    Write-AnsibleError @error_params
-    $host.SetShouldExit(1)
-    return
 }
 finally {
-    [System.Console]::SetOut($orig_out)
-    $new_out.Dispose()
-}
-
-# other types of errors may not throw an exception in Invoke but rather just
-# set the pipeline state to failed
-if ($ps.InvocationStateInfo.State -eq "Failed" -and $ModuleName -ne "script") {
-    $reason = $ps.InvocationStateInfo.Reason
-    $error_params = @{
-        Message = "Unhandled exception while executing module"
+    if ($newOut) {
+        [Console]::SetOut($origOut)
+        $newOut.Dispose()
     }
-
-    # The error record should always be set on the reason but this does not
-    # always happen on Server 2008 R2 for some reason (probably memory hotfix).
-    # Be defensive when trying to get the error record and fall back to other
-    # options.
-    if ($null -eq $reason) {
-        $error_params.Message += ": Unknown error"
-    }
-    elseif ($reason.PSObject.Properties.Name -contains "ErrorRecord") {
-        $error_params.ErrorRecord = $reason.ErrorRecord
-    }
-    else {
-        $error_params.Message += ": $($reason.ToString())"
-    }
-
-    Write-AnsibleError @error_params
-    $host.SetShouldExit(1)
-    return
 }
 
-Write-AnsibleLog "INFO - module exec ended $ModuleName" "module_wrapper"
 $stdout = $sb.ToString()
 if ($stdout) {
-    Write-Output -InputObject $stdout
+    $stdout
 }
-if ($module_output.Count -gt 0) {
-    # do not output if empty collection
-    Write-AnsibleLog "INFO - using the output stream for module output - $ModuleName" "module_wrapper"
-    Write-Output -InputObject ($module_output -join "`r`n")
+if ($modOut.Count) {
+    $modOut -join "`r`n"
 }
 
-# we attempt to get the return code from the LASTEXITCODE variable
-# this is set explicitly in newer style variables when calling
-# ExitJson and FailJson. If set we set the current hosts' exit code
-# to that same value
+# Attempt to set the return code from the LASTEXITCODE variable. This is set
+# explicitly in newer style modules when calling ExitJson and FailJson.
 $rc = $ps.Runspace.SessionStateProxy.GetVariable("LASTEXITCODE")
 if ($null -ne $rc) {
-    Write-AnsibleLog "INFO - got an rc of $rc from $ModuleName exec" "module_wrapper"
     $host.SetShouldExit($rc)
 }
 
-# PS3 doesn't properly set HadErrors in many cases, inspect the error stream as a fallback
-# with the trap handler that's now in place, this should only write to the output if
-# $ErrorActionPreference != "Stop", that's ok because this is sent to the stderr output
-# for a user to manually debug if something went horribly wrong
-if (
-    $ps.Streams.Error.Count -and
-    ($ps.HadErrors -or $PSVersionTable.PSVersion.Major -lt 4)
-) {
-    Write-AnsibleLog "WARN - module had errors, outputting error info $ModuleName" "module_wrapper"
-    # if the rc wasn't explicitly set, we return an exit code of 1
-    if ($null -eq $rc) {
-        $host.SetShouldExit(1)
-    }
-
-    # output each error to the error stream of the current pipeline
-    foreach ($err in $ps.Streams.Error) {
-        $error_msg = Format-AnsibleException -ErrorRecord $err
-
-        # need to use the current hosts's UI class as we may not have
-        # a console to write the stderr to, e.g. psrp
-        Write-AnsibleLog "WARN - error msg for for $($ModuleName):`r`n$error_msg" "module_wrapper"
-        $host.UI.WriteErrorLine($error_msg)
+foreach ($err in $ps.Streams.Error) {
+    Write-AnsibleErrorDetail -ErrorRecord $err -ForModule:$ForModule
+    if ($ForModule) {
+        if ($null -eq $rc) {
+            $host.SetShouldExit(1)
+        }
+        return
     }
 }

ansible/executor/powershell/powershell_expand_user.ps1

@@ -0,0 +1,20 @@
+# (c) 2025 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+[CmdletBinding()]
+param (
+    [Parameter(Mandatory)]
+    [string]
+    $Path
+)
+
+$userProfile = [Environment]::GetFolderPath([Environment+SpecialFolder]::UserProfile)
+if ($Path -eq '~') {
+    $userProfile
+}
+elseif ($Path.StartsWith(('~\'))) {
+    Join-Path -Path $userProfile -ChildPath $Path.Substring(2)
+}
+else {
+    $Path
+}

ansible/executor/powershell/powershell_mkdtemp.ps1

@@ -0,0 +1,17 @@
+# (c) 2025 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+[CmdletBinding()]
+param (
+    [Parameter(Mandatory)]
+    [string]
+    $Directory,
+
+    [Parameter(Mandatory)]
+    [string]
+    $Name
+)
+
+$path = [Environment]::ExpandEnvironmentVariables($Directory)
+$tmp = New-Item -Path $path -Name $Name -ItemType Directory
+$tmp.FullName

ansible/executor/powershell/psrp_fetch_file.ps1

@@ -0,0 +1,41 @@
+# (c) 2025 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+using namespace System.IO
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [string]
+    $Path,
+
+    [Parameter(Mandatory)]
+    [int]
+    $BufferSize
+)
+
+if (Test-Path -LiteralPath $Path -PathType Leaf) {
+    "[FILE]"
+
+    $fs = [FileStream]::new(
+        $path,
+        [FileMode]::Open,
+        [FileAccess]::Read,
+        [FileShare]::Read)
+
+    try {
+        $buffer = [byte[]]::new($BufferSize)
+        while ($read = $fs.Read($buffer, 0, $buffer.Length)) {
+            [Convert]::ToBase64String($buffer, 0, $read)
+        }
+    }
+    finally {
+        $fs.Dispose()
+    }
+}
+elseif (Test-Path -LiteralPath $Path -PathType Container) {
+    "[DIR]"
+}
+else {
+    Write-Error -Message "$Path does not exist"
+}

ansible/executor/powershell/psrp_put_file.ps1

@@ -0,0 +1,122 @@
+# (c) 2025 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+using namespace System.IO
+using namespace System.Reflection
+using namespace System.Security.Cryptography
+
+[CmdletBinding()]
+param (
+    [Parameter(Mandatory = $true)]
+    [string]
+    $Path,
+
+    [Parameter(Mandatory, ValueFromPipeline)]
+    [AllowEmptyString()]
+    [string]
+    $InputObject
+)
+
+begin {
+    $fd = [File]::Create($Path)
+    $algo = [SHA1]::Create()
+    $bytes = @()
+
+    $bindingFlags = [BindingFlags]'NonPublic, Instance'
+    Function Get-Property {
+        <#
+        .SYNOPSIS
+        Gets the private/internal property specified of the object passed in.
+        #>
+        Param (
+            [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+            [Object]
+            $Object,
+
+            [Parameter(Mandatory = $true, Position = 1)]
+            [String]
+            $Name
+        )
+
+        process {
+            $Object.GetType().GetProperty($Name, $bindingFlags).GetValue($Object, $null)
+        }
+    }
+
+    Function Set-Property {
+        <#
+        .SYNOPSIS
+        Sets the private/internal property specified on the object passed in.
+        #>
+        Param (
+            [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+            [Object]
+            $Object,
+
+            [Parameter(Mandatory = $true, Position = 1)]
+            [String]
+            $Name,
+
+            [Parameter(Mandatory = $true, Position = 2)]
+            [AllowNull()]
+            [Object]
+            $Value
+        )
+
+        process {
+            $Object.GetType().GetProperty($Name, $bindingFlags).SetValue($Object, $Value, $null)
+        }
+    }
+
+    Function Get-Field {
+        <#
+        .SYNOPSIS
+        Gets the private/internal field specified of the object passed in.
+        #>
+        Param (
+            [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+            [Object]
+            $Object,
+
+            [Parameter(Mandatory = $true, Position = 1)]
+            [String]
+            $Name
+        )
+
+        process {
+            $Object.GetType().GetField($Name, $bindingFlags).GetValue($Object)
+        }
+    }
+
+    # MaximumAllowedMemory is required to be set to so we can send input data that exceeds the limit on a PS
+    # Runspace. We use reflection to access/set this property as it is not accessible publicly. This is not ideal
+    # but works on all PowerShell versions I've tested with. We originally used WinRS to send the raw bytes to the
+    # host but this falls flat if someone is using a custom PS configuration name so this is a workaround. This
+    # isn't required for smaller files so if it fails we ignore the error and hope it wasn't needed.
+    # https://github.com/PowerShell/PowerShell/blob/c8e72d1e664b1ee04a14f226adf655cced24e5f0/src/System.Management.Automation/engine/serialization.cs#L325
+    try {
+        $Host | Get-Property 'ExternalHost' |
+            Get-Field '_transportManager' |
+            Get-Property 'Fragmentor' |
+            Get-Property 'DeserializationContext' |
+            Set-Property 'MaximumAllowedMemory' $null
+    }
+    catch {
+        # Satisfy pslint, we purposefully ignore this error as it is not critical it works.
+        $null = $null
+    }
+}
+process {
+    if ($InputObject) {
+        $bytes = [Convert]::FromBase64String($InputObject)
+        $algo.TransformBlock($bytes, 0, $bytes.Length, $bytes, 0) > $null
+        $fd.Write($bytes, 0, $bytes.Length)
+    }
+}
+end {
+    $fd.Close()
+
+    $algo.TransformFinalBlock($bytes, 0, 0) > $null
+    $hash = [BitConverter]::ToString($algo.Hash).Replace('-', '').ToLowerInvariant()
+    "{`"sha1`":`"$hash`"}"
+}

ansible/executor/powershell/winrm_fetch_file.ps1

@@ -0,0 +1,46 @@
+# (c) 2025 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+using namespace System.IO
+
+[CmdletBinding()]
+param (
+    [Parameter(Mandatory)]
+    [string]
+    $Path,
+
+    [Parameter(Mandatory)]
+    [int]
+    $BufferSize,
+
+    [Parameter(Mandatory)]
+    [long]
+    $Offset
+)
+
+if (Test-Path -LiteralPath $Path -PathType Leaf) {
+    $stream = [FileStream]::new(
+        $Path,
+        [FileMode]::Open,
+        [FileAccess]::Read,
+        [FileShare]::ReadWrite)
+
+    try {
+        $null = $stream.Seek($Offset, [SeekOrigin]::Begin)
+        $buffer = [byte[]]::new($BufferSize)
+        $read = $stream.Read($buffer, 0, $buffer.Length)
+        if ($read) {
+            [Convert]::ToBase64String($buffer, 0, $read)
+        }
+    }
+    finally {
+        $stream.Dispose()
+    }
+}
+elseif (Test-Path -LiteralPath $Path -PathType Container) {
+    "[DIR]"
+}
+else {
+    $host.UI.WriteErrorLine("$Path does not exist")
+    exit 1
+}