Using WinSCP .NET Assembly from PowerShell

About PowerShell

PowerShell is Microsoft’s task automation framework, consisting of a command-line shell and associated scripting language built on .NET Framework.


PowerShell is built into Windows 7 and newer; and is optionally available for Windows 98 SP2 and newer.1)

PowerShell scripts can be directly executed, they do not need to be compiled first.

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.

The powershell.exe is located in %WINDIR%\System32\WindowsPowershell\v1.0.2) Typically you run powershell.exe with -File argument followed by path to your PowerShell script. The script file needs to have .ps1 extension:

powershell.exe -File upload.ps1

Note that by default, executing PowerShell scripts is disabled. To override that, you can either lift the restriction by typing using Set-ExecutionPolicy cmdlet on PowerShell administrator console3):

Set-ExecutionPolicy Unrestricted

or use -ExecutionPolicy argument for every script run:

powershell.exe -ExecutionPolicy Unrestricted -File upload.ps1 

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 package and extract it along with your PowerShell script.

For specific cases, read full instructions to installing the WinSCP .NET assembly.

Using from PowerShell

You use WinSCP .NET assembly from PowerShell as any other .NET assembly.

Though there are some less known techniques and peculiarities that you may need to use, which are described in following sections.

Loading Assembly

PowerShell script needs to load the assembly before it can use classes the assembly exposes. To load assembly use Add-Type cmdlet.4)

Add-Type -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 $PSScriptRoot automatic variable:5)

Add-Type -Path (Join-Path $PSScriptRoot "WinSCPnet.dll")

If you are writing a script that you plan to use as a WinSCP extension (a custom command), you can use the copy of the assembly installed with WinSCP. In that case you can use the WINSCP_PATH environment variable to resolve the path to the assembly. To allow the script run even outside of WinSCP, you should fall back to the $PSScriptRoot approach (as above), if the variable is not defined:

$assemblyPath = if ($env:WINSCP_PATH) { $env:WINSCP_PATH } else { $PSScriptRoot }
Add-Type -Path (Join-Path $assemblyPath "WinSCPnet.dll")

Accessing Enumeration Values

Enumeration values are accessed using static field syntax [Namespace.Type]::Member, for example [WinSCP.Protocol]::Sftp.

Event Handlers

The Session class exposes several events.

If you need to make use of these events:

  • Define event handling function;
  • Associate the event handling function with an instance of Session class using .add_Event method, where Event is a name of the event.6)

See following code snippet:

# Event handling function
function FileTransferred
    if ($e.Error -eq $Null)
        Write-Host ("Transfer of {0} succeeded" -f $e.FileName)
        Write-Host ("Transfer of {0} failed: {1}" -f $e.FileName, $e.Error)
# Subscribe to the event
$session.add_FileTransferred( { FileTransferred($_) } )

PowerShell Module

There is a third-party PowerShell module, WinSCP PowerShell Wrapper, that provides a cmdlet interface on top of the .NET assembly.


# Set credentials to a PSCredential Object.
$credential = Get-Credential
# Create a WinSCP Session.
$session = New-WinSCPSession -Hostname "" -Credential $credential -SshHostKeyFingerprint "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
# 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\"
# Remove the WinSCPSession after completion.
Remove-WinSCPSession -WinSCPSession $session

Accomplish the same task with one line of code:

# Piping the WinSCPSession into the Receive-WinSCPItem auto disposes the WinSCP.Session object after completion.
New-WinSCPSession -Hostname "" -Credential (Get-Credential) -SshHostKeyFingerprint "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx") | 
     Receive-WinSCPItem -Path "/home/user/file.txt" -Destination "C:\download\"


This example is functionally equivalent to overall C# example for WinSCP .NET assembly.

There are also other PowerShell examples.

    # Load WinSCP .NET assembly
    Add-Type -Path "WinSCPnet.dll"
    # Setup session options
    $sessionOptions = New-Object WinSCP.SessionOptions -Property @{
        Protocol = [WinSCP.Protocol]::Sftp
        HostName = ""
        UserName = "user"
        Password = "mypassword"
        SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
    $session = New-Object WinSCP.Session
        # Connect
        # Upload files
        $transferOptions = New-Object WinSCP.TransferOptions
        $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary
        $transferResult = $session.PutFiles("d:\toupload\*", "/home/user/", $False, $transferOptions)
        # Throw on any error
        # Print results
        foreach ($transfer in $transferResult.Transfers)
            Write-Host ("Upload of {0} succeeded" -f $transfer.FileName)
        # Disconnect, clean up
    exit 0
catch [Exception]
    Write-Host ("Error: {0}" -f $_.Exception.Message)
    exit 1

Converting Script to PowerShell Code

When you are considering converting your script to code that uses WinSCP .NET assembly, PowerShell, thanks to its ubiquity, can be a good choice, particularly, when you do not have your own preferred language that supports .NET.

1) The text is partially copied from Wikipedia article on PowerShell. The text is licensed under GNU Free Documentation License.
2) It’s v1.0, disregarding what version you actually use.
3) Run powershell.exe as Administrator to get PowerShell console.
4) In PowerShell 1.0, use System.Reflection.Assembly.LoadFrom method.
5) In PowerShell 2.0, use Add-Type -Path (Join-Path (Split-Path $script:MyInvocation.MyCommand.Path) "WinSCPnet.dll")
6) Avoid using Register-ObjectEvent cmdlet, as it introduces threading problems and possible crashes.
  library_powershell.txt · Last modified: by martin

Search Documentation

This page


About donations

$9   $19   $49   $99

About donations



Site design by Black Gate