Converting Script to Code Based on .NET Assembly

Start by choosing a language. WinSCP .NET assembly can be used from any .NET language or any language that supports COM.

If you do not have your own preferred language, use Windows PowerShell.

Most script commands can be directly mapped to their equivalent .NET assembly method calls. The mapping is described in respective scripting command documentation page.

There are some conceptual differences though. These are discussed in following sections.

Scripts run in an interactive mode by default (option batch off). There’s no equivalent for this in .NET assembly, which always runs in batch mode. It is near equivalent to option batch abort in scripting mode, what is a recommended setting, as used in most scripting examples. Read more about capturing errors in .NET assembly. Documentation for converting of individual scripting commands (such as get command mapping) details mode mapping specifics for the respective operations.

Scripting mode by default shares configuration with graphical mode. On the contrary the .NET assembly is by default isolated from graphical mode configuration (equivalent to using /ini=nul command-line parameter in scripting mode).

It means that you cannot use sites/stored sessions, when opening session with .NET assembly. You need to configure all your site settings directly in your code (using SessionOptions class).

It also means that with .NET assembly, you always start with default transfer settings, default resume/endurance settings, etc.

Alternatively, you can force the .NET assembly to share configuration with graphical/scripting mode, by setting Session.DefaultConfiguration to false ($False in PowerShell). Though this is not recommended practise.

Scripting mode (similarly to graphical mode) has concept of current working directory (both on local and remote side). On the contrary, the .NET assembly does not; there are no equivalents to cd and lcd commands.

In the scripting you can use paths relative to current working directory in parameters to script commands. In the .NET assembly, you need to always use absolute paths.

For example following script snippet:

cd /home/martinp
lcd d:\
get test.txt

needs to be converted to following call in PowerShell:

$session.GetFiles("/home/martinp/test.txt", "d:\")

Following script:

# Automatically abort script on errors
option batch abort
# Disable overwrite confirmations that conflict with the previous
option confirm off
# Connect
open sftp://user:password@example.com -hostkey="ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
# Change remote directory
cd /home/user
# Force binary mode transfer
option transfer binary
# Download file to the local directory d:\
get examplefile.txt d:\
# Disconnect
close
# Exit WinSCP
exit

maps to following PowerShell code:

try
{
    # Load WinSCP .NET assembly
    # Use "winscp.dll" for the releases before the latest beta version.
    [Reflection.Assembly]::LoadFrom("WinSCPnet.dll") | Out-Null
 
    # Setup session options
    $sessionOptions = New-Object WinSCP.SessionOptions
    $sessionOptions.Protocol = [WinSCP.Protocol]::Sftp
    $sessionOptions.HostName = "example.com"
    $sessionOptions.UserName = "user"
    $sessionOptions.Password = "password"
    $sessionOptions.SshHostKeyFingerprint = "ssh-rsa 1024 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)
 
        # Force binary mode transfer
        $transferOptions = New-Object WinSCP.TransferOptions
        $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary
 
        # Download file to the local directory d:\
        # Note use of absolute path
        $transferResult = $session.GetFiles("/home/user/examplefile.txt", "d:\", $False, $transferOptions)
 
        # Throw on any error to emulate "option batch abort"
        $transferResult.Check()
    }
    finally
    {
        # Disconnect, clean up
        $session.Dispose()
    }
 
    exit 0
}
catch [Exception]
{
    Write-Host $_.Exception.Message
    exit 1
}