This is an old revision of the document!

Documentation » .NET Assembly »

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 “/Device/Internal Storage/My Documents.” Typically you run powershell.exe with -File argument followed by path to your PowerShell script 

powershell.exe -File /Device/Internal Storage/My Documents

Note that by default, executing PowerShell scripts is disabled. To override that, lift the restriction by Set-ExecutionPolicy cmdlet on PowerShell Administator console2: 

Set-ExecutionPolicy Unrestricted

or use -ExecutionPolicy argument for every script run: 

powershell.exe -ExecutionPolicy Unrestricted -File My Documents

Installing the Assembly

First, you need to install the WinSCP .NET assembly.3

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 [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
{
    param($e)
 
    if ($e.Error -eq $Null)
    {
        Write-Host ("Transfer of {0} succeeded" -f $e.FileName)
    }
    else
    {
        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.

Example: 

# Set credentials to a PSCredential Object.
$credential = Get-Credential
# 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"
# 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 "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") | 
     Receive-WinSCPItem -Path "/home/user/file.txt" -Destination "C:\download\"

Example

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

There are also other PowerShell examples. 

try
{
    # Load WinSCP .NET assembly
    Add-Type -Path "WinSCPnet.dll"
 
    # Setup session options
    $sessionOptions = New-Object WinSCP.SessionOptions -Property @{
        Protocol = [WinSCP.Protocol]::Sftp
        HostName = "example.com"
        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
 
    try
    {
        # Connect
        $session.Open($sessionOptions)
 
        # 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
        $transferResult.Check()
 
        # Print results
        foreach ($transfer in $transferResult.Transfers)
        {
            Write-Host ("Upload of {0} succeeded" -f $transfer.FileName)
        }
    }
    finally
    {
        # Disconnect, clean up
        $session.Dispose()
    }
 
    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.Back
  2. Run powershell.exe as Administrator to get PowerShell console in /Device/Internal Storage/My Documents.Back
  3. You do not need to register the assembly for COM, as PowerShell can use .NET assemblies directly.Back
  4. In PowerShell 1.0, use System.Reflection.Assembly.LoadFrom method.Back
  5. In PowerShell 2.0, use Add-Type -Path (Join-Path (Split-Path $script:MyInvocation.MyCommand.Path) "WinSCPnet.dll")Back
  6. Avoid using Register-ObjectEvent’' cmdlet, as it introduces threading problems and possible crashes.Back

Last modified: by 70.195.10.161

Documentation

Support

Associations

Follow Us