Using WinSCP .NET Assembly from WSH-hosted Active Scripting Languages

First, you need to install the WinSCP .NET assembly and register it for COM.

You use WinSCP .NET assembly from WSH as any other COM library.

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

As JScript and VBScript access COM classes via IDispatch, they do not make use of type library, hence they do not have direct access to constants defined there, like Protocol.Sftp for instance. To use these, you have to instruct WSH to import the type library into the script namespace.

You can use Windows Script File (WSF) and its <reference> tag for that. It makes WSH import all enums from the assembly type library into constants in script namespace with name like <type>_<member>, e.g. Protocol.Sftp becomes Protocol_Sftp.

See how <reference object="WinSCP.Session"/> allows use of Protocol_Sftp in below JScript script embedded in WSF:

<job>
<reference object="WinSCP.Session" />
<script language="JScript">
 
var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");
sessionOptions.Protocol = Protocol_Sftp;
sessionOptions.HostName = "example.com";
sessionOptions.UserName = "user";
sessionOptions.Password = "mypassword";
sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx...";
 
var session = WScript.CreateObject("WinSCP.Session");
 
session.Open(sessionOptions);
 
session.PutFiles("d:\\toupload\\*", "/home/user/");
 
</script>
</job>

You run the .wsf file the same way as you run .js or .vbs:

cscript upload.wsf

The Session class exposes several events.

If you need to make use of these events:

• Use overload of WScript.CreateObject with 2 arguments, passing an unique prefix as the second argument (e.g. “session_”);
• Define function with name <prefix><event> and two arguments (e.g. sender and e) for every event you need to handle.

See following JScript snippet:

function session_FileTransferred(sender, e)
{
 WScript.Echo(e.FileName + " => " + e.Destination);
}
 
var session = WScript.CreateObject("WinSCP.Session", "session_");

For a full example, see an example for Session.SynchronizeDirectories .

And equivalent in VBScript:

Sub session_FileTransferred(sender, e)
 WScript.Echo e.FileName & " => " & e.Destination
End Sub
 
Set session = WScript.CreateObject("WinSCP.Session", "session_")

VBScript does not support catching exceptions, what is a common way of handling errors in examples for most other languages.

In case you need to use custom error handling, instead of aborting the script on error (the default for WSH), use On Error statement.

Use On Error Resume Next to disable default error handling. Then you need to query Err.Number after every statement to test for errors. You can revert to default error handling (aborting the script) using On Error GoTo 0.

' Enable custom error handling
On Error Resume Next
 
' Now, with custom error handling enabled,
' script does not abort, when opening session fails
session.Open sessionOptions
 
' Query for errors
If Err.Number <> 0 Then
 WScript.Echo "Error opening session: " & Err.Description
 WScript.Quit 1
End If
 
' Restore default error handling
On Error GoTo 0
 
' Now, with default error handling restored,
' script aborts, if reading remote directory fails
Dim directoryInfo
Set directoryInfo = session.ListDirectory("/home/user/")

If you do not want to test for errors after every statement, you need to group the staments you want to guard into a subprocedure and enable custom error handling before calling/entering the subprocedure.

This approach is also recommended to ensure that Session.Dispose is called even in case of error.

Sub ListDirectory(ByRef session)
 ' Setup session options
 ...
 
 ' Connect
 session.Open sessionOptions
 
 Dim directoryInfo
 Set directoryInfo = session.ListDirectory("/home/user/")
 
 ' Do some stuff with directory listing
 ...
End Sub
 
Dim session
Set session = WScript.CreateObject("WinSCP.Session")
 
' Enable custom error handling
On Error Resume Next
 
' Now, with custom error handling enabled before calling the ListDirectory subprocedure,
' any statement in the subprocedure terminates the subprocedure (but not the whole script)
ListDirectory session
 
' Query for errors
If Err.Number <> 0 Then
 WScript.Echo "Listing directory failed: " & Err.Description
 
 ' Disconnect, clean up
 session.Dispose
 
 WScript.Quit 1
End If
 
' Disconnect, clean up
session.Dispose
 
' Restore default error handling
On Error GoTo 0
 
' Now with session cleanly closed, safely do anything unrelated to WinSCP session
...

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

There are also other JScript examples.

<job>
<reference object="WinSCP.Session" />
<script language="JScript">
 
try
{
 // Setup session options
 var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");
 sessionOptions.Protocol = Protocol_Sftp;
 sessionOptions.HostName = "example.com";
 sessionOptions.UserName = "user";
 sessionOptions.Password = "mypassword";
 sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx...";
 
 var session = WScript.CreateObject("WinSCP.Session");
 
 try
 {
 // Connect
 session.Open(sessionOptions);
 
 // Upload files
 var transferOptions = WScript.CreateObject("WinSCP.TransferOptions");
 transferOptions.TransferMode = TransferMode_Binary;
 
 var transferResult =
 session.PutFiles("d:\\toupload\\*", "/home/user/", false, transferOptions);
 
 // Throw on any error
 transferResult.Check();
 
 // Print results
 var enumerator = new Enumerator(transferResult.Transfers);
 for (; !enumerator.atEnd(); enumerator.moveNext())
 {
 WScript.Echo("Upload of " + enumerator.item().FileName + " succeeded");
 }
 }
 finally
 {
 // Disconnect, clean up
 session.Dispose();
 }
}
catch (e)
{
 WScript.Echo("Error: " + e.message);
 WScript.Quit(1);
}
 
</script>
</job>

This example is functionally equivalent to overall C# example for WinSCP .NET assembly, except for error handling.

There are also other VBScript examples.

<job>
<reference object="WinSCP.Session" />
<script language="VBScript">
 
Option Explicit
 
' Setup session options
Dim sessionOptions
Set sessionOptions = WScript.CreateObject("WinSCP.SessionOptions")
With sessionOptions
 .Protocol = Protocol_Sftp
 .HostName = "example.com"
 .UserName = "user"
 .Password = "mypassword"
 .SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
End With
 
Dim session
Set session = WScript.CreateObject("WinSCP.Session")
 
' Connect
session.Open sessionOptions
 
' Upload files
Dim transferOptions
Set transferOptions = WScript.CreateObject("WinSCP.TransferOptions")
transferOptions.TransferMode = TransferMode_Binary
 
Dim transferResult
Set transferResult = session.PutFiles("d:\toupload\*", "/home/user/", False, transferOptions)
 
' Throw on any error
transferResult.Check
 
' Print results
Dim transfer
For Each transfer In transferResult.Transfers
 WScript.Echo "Upload of " & transfer.FileName & " succeeded"
Next
 
' Disconnect, clean up
session.Dispose
 
</script>
</job>