Differences

This shows you the differences between the selected revisions of the page.

library_powershell 2017-10-04 library_powershell 2023-10-30 (current)
Line 1: Line 1:
====== Using WinSCP .NET Assembly from PowerShell ====== ====== Using WinSCP .NET Assembly from PowerShell ======
-===== About PowerShell ===== +===== [[powershell]] About PowerShell ===== 
-[[wp>PowerShell|PowerShell]] is Microsoft's task automation framework, consisting of a command-line shell and associated scripting language built on .NET Framework.+[[wp>PowerShell|PowerShell]] is Microsoft's task automation framework, consisting of a command-line shell and associated scripting language built on .NET.
-PowerShell is built into Windows 7 and newer; and is optionally available for Windows 98 SP2 and newer.((&wikipedia_ref(PowerShell|PowerShell))) &win9x+Windows PowerShell (''powershell.exe'') is built into Windows 7 and newer; and is optionally available for Windows 98 SP2 and newer.((&wikipedia_ref(PowerShell|PowerShell))) &win9x It uses .NET Framework. Its successor, PowerShell (''pwsh.exe''), previously known as PowerShell Core, aka PowerShell 6/7, is cross-platform and can be optionally installed in Windows. It uses .NET (previously known as .NET Core).
PowerShell scripts can be directly executed, they do not need to be compiled first. PowerShell scripts can be directly executed, they do not need to be compiled first.
-===== PowerShell Scripting =====+===== [[scripting]] PowerShell Scripting =====
-From WinSCP scripting perspective, important aspect of PowerShell (''powershell.exe'') is its ability to run simple, yet powerful, scripts that can make use functionality exposed by WinSCP .NET assembly.+From WinSCP scripting perspective, an important aspect of PowerShell is its ability to run simple, yet powerful, scripts that can make use of functionality exposed by WinSCP .NET assembly.
-The ''powershell.exe'' is located in ''%WINDIR%\System32\WindowsPowershell\v1.0''.((It's ''v1.0'', disregarding what version you actually use.)) Typically you run ''powershell.exe'' with ''-File'' argument followed by path to your PowerShell script. The script file needs to have ''.ps1'' extension:+Windows PowerShell's ''powershell.exe'' is located in ''%WINDIR%\System32\WindowsPowershell\v1.0''.((It's ''v1.0'', disregarding what version you actually use.)) Typically you run ''powershell.exe'' with ''-File'' argument followed by path to your PowerShell script. The script file needs to have ''.ps1'' extension:
<code> <code>
powershell.exe -File upload.ps1 powershell.exe -File upload.ps1
</code> </code>
 +
 +PowerShell (Core)'s ''pwsh.exe'' installs into ''C:\Program Files\PowerShell\<version>''.
Note that by default, executing PowerShell scripts is disabled. To override that, you can either lift the restriction by typing using ''[[ps>microsoft.powershell.security/set-executionpolicy|Set-ExecutionPolicy]]'' cmdlet on PowerShell administrator console:((Run ''powershell.exe'' as Administrator to get PowerShell console.)) Note that by default, executing PowerShell scripts is disabled. To override that, you can either lift the restriction by typing using ''[[ps>microsoft.powershell.security/set-executionpolicy|Set-ExecutionPolicy]]'' cmdlet on PowerShell administrator console:((Run ''powershell.exe'' as Administrator to get PowerShell console.))
Line 30: Line 32:
</code> </code>
-===== Installing the Assembly ===== +===== [[install]] Installing the Assembly ===== 
-First, you need to install the WinSCP .NET assembly. In most cases, all you need to do is [[library_install#downloading|download]] the ''WinSCP-X.X.X-Automation.zip'' package and extract it along with your PowerShell script.+First, you need to install the WinSCP .NET assembly. In most cases, all you need to do is [[library_install#downloading|download]] the ''WinSCP-X.X.X-Automation.zip'' package((In some cases, the downloaded [[message_net_operation_not_supported|executables need to be unblocked]].)) and extract it along with your PowerShell script.((Generally you only need ''WinSCPnet.dll'' and ''WinSCP.exe''.)) 
 + 
 +The version of ''WinSCPnet.dll'' in the root of the package is the .NET Framework build of the assembly. It can be used with Windows PowerShell only. With PowerShell (Core) 6/7, you have to use the .NET Standard build of the assembly, which is located in the ''netstandard2.0'' subfolder.
For specific cases, read full instructions to [[library_install|installing the WinSCP .NET assembly]]. For specific cases, read full instructions to [[library_install|installing the WinSCP .NET assembly]].
Line 41: Line 45:
==== [[loading]] Loading Assembly ==== ==== [[loading]] Loading Assembly ====
-PowerShell script needs to load the assembly before it can use classes the assembly exposes. To load assembly use ''[[ps>microsoft.powershell.utility/add-type|Add-Type]]'' cmdlet.((In PowerShell 1.0, use ''[[msdn>System.Reflection.Assembly.LoadFrom]]'' method.))+PowerShell script needs to load the assembly before it can use classes the assembly exposes. To load assembly use ''[[ps>microsoft.powershell.utility/add-type|Add-Type]]'' cmdlet.((In PowerShell 1.0, use ''[[dotnet>System.Reflection.Assembly.LoadFrom]]'' method.))
<code powershell> <code powershell>
Line 47: Line 51:
</code> </code>
-Had you need to run the script from other directory, you need to specify a full path to the assembly. You can derive the path from the script file path using ''[[ps>microsoft.powershell.core/about_automatic_variables|$PSScriptRoot]]'' automatic variable:((In PowerShell 2.0, use ''%%Add-Type -Path (Join-Path (Split-Path $script:MyInvocation.MyCommand.Path) "WinSCPnet.dll")%%''))+Had you need to run the script from other directory, you need to specify a full path to the assembly. You can derive the path from the script file path using [[ps>microsoft.powershell.core/about/about_automatic_variables#psscriptroot|''$PSScriptRoot'' automatic variable]]:((In PowerShell 2.0, use ''%%Add-Type -Path (Join-Path (Split-Path $script:MyInvocation.MyCommand.Path) "WinSCPnet.dll")%%''))
<code powershell> <code powershell>
Line 97: Line 101:
==== [[module]] PowerShell Module ==== ==== [[module]] PowerShell Module ====
-There is a third-party PowerShell module, [[https://dotps1.github.io/WinSCP/|WinSCP PowerShell Wrapper]], that provides a cmdlet interface on top of the .NET assembly.+There is a third-party PowerShell module, [[https://github.com/tomohulk/WinSCP|WinSCP PowerShell Wrapper]], that provides a cmdlet interface on top of the .NET assembly.
Example: Example:
Line 105: Line 109:
$credential = Get-Credential $credential = Get-Credential
# Create a WinSCP Session. # Create a WinSCP Session.
-$session = New-WinSCPSession -Hostname "example.com" -Credential $credential -SshHostKeyFingerprint "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"+$session = New-WinSCPSession -Hostname "example.com" -Credential $credential -SshHostKeyFingerprint "ssh-rsa 2048 xxxxxxxxxxx..."
# Using the WinSCPSession, download the file from the remote host to the local host. # Using the WinSCPSession, download the file from the remote host to the local host.
Receive-WinSCPItem -WinSCPSession $session -Path "/home/user/file.txt" -Destination "C:\download\" Receive-WinSCPItem -WinSCPSession $session -Path "/home/user/file.txt" -Destination "C:\download\"
Line 116: Line 120:
<code powershell> <code powershell>
# Piping the WinSCPSession into the Receive-WinSCPItem auto disposes the WinSCP.Session object after completion. # Piping the WinSCPSession into the Receive-WinSCPItem auto disposes the WinSCP.Session object after completion.
-New-WinSCPSession -Hostname "example.com" -Credential (Get-Credential) -SshHostKeyFingerprint "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx") | +New-WinSCPSession -Hostname "example.com" -Credential (Get-Credential) -SshHostKeyFingerprint "ssh-rsa 2048 xxxxxxxxxxx...") |
    Receive-WinSCPItem -Path "/home/user/file.txt" -Destination "C:\download\"     Receive-WinSCPItem -Path "/home/user/file.txt" -Destination "C:\download\"
</code> </code>
Line 137: Line 141:
        UserName = "user"         UserName = "user"
        Password = "mypassword"         Password = "mypassword"
-        SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"+        SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
    }     }
Line 151: Line 155:
        $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary         $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary
-        $transferResult = $session.PutFiles("d:\toupload\*", "/home/user/", $False, $transferOptions)+        $transferResult = 
 + ···········$session.PutFiles("d:\toupload\*", "/home/user/", $False, $transferOptions)
        # Throw on any error         # Throw on any error
Line 170: Line 175:
    exit 0     exit 0
} }
-catch [Exception]+catch
{ {
    Write-Host "Error: $($_.Exception.Message)"     Write-Host "Error: $($_.Exception.Message)"

Last modified: by martin