Differences

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

library_com_wsh 2012-02-18		library_com_wsh 2022-10-21 (current)
	Line 1:		Line 1:
	====== Using WinSCP .NET Assembly from WSH-hosted Active Scripting Languages ======		====== Using WinSCP .NET Assembly from WSH-hosted Active Scripting Languages ======
-	&future_feature

	===== Installing and Registering for COM =====		===== Installing and Registering for COM =====
	Line 10:		Line 9:
	Though there are some less known techniques that you may need to use, which are described in following sections.		Though there are some less known techniques that you may need to use, which are described in following sections.

-	==== Accessing Enumeration Values ====	+	==== [[enums]] Accessing Enumeration Values ====
-	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 ''[[library_sessionoptions#properties\|Protocol.Sftp]]'' for instance. To use these, you have to instruct WSH to import the type library into the script namespace.	+	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 ''[[library_sessionoptions#protocol\|Protocol.Sftp]]'' for instance. To use these, you have to instruct WSH to import the type library into the script namespace.

	You can use [[wp>Windows_Script_File\|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''.		You can use [[wp>Windows_Script_File\|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''.
	Line 27:		Line 26:
	sessionOptions.UserName = "user";		sessionOptions.UserName = "user";
	sessionOptions.Password = "mypassword";		sessionOptions.Password = "mypassword";
-	sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx";	+	sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx...";

	var session = WScript.CreateObject("WinSCP.Session");		var session = WScript.CreateObject("WinSCP.Session");
	Line 40:		Line 39:

	You run the ''.wsf'' file the same way as you run ''.js'' or ''.vbs'':		You run the ''.wsf'' file the same way as you run ''.js'' or ''.vbs'':
-	<code>	+	<code batch>
	cscript upload.wsf		cscript upload.wsf
	</code>		</code>

-	==== Event Handlers ====	+	==== [[event_handlers]] Event Handlers ====
	The ''[[library_session\|Session]]'' class exposes several [[library_session#events\|events]].		The ''[[library_session\|Session]]'' class exposes several [[library_session#events\|events]].

	Line 56:		Line 55:
	function session_FileTransferred(sender, e)		function session_FileTransferred(sender, e)
	{		{
-	WScript.Echo(e.FileName, "=>", e.Destination);	+	WScript.Echo(e.FileName + "·=>·" + e.Destination);
	}		}

	var session = WScript.CreateObject("WinSCP.Session", "session_");		var session = WScript.CreateObject("WinSCP.Session", "session_");
	</code>		</code>
		+
		+	For a full example, see an example for ''[[library_session_synchronizedirectories#jscript\|Session.SynchronizeDirectories]]''.

	And equivalent in VBScript:		And equivalent in VBScript:
	Line 66:		Line 67:
	<code vb>		<code vb>
	Sub session_FileTransferred(sender, e)		Sub session_FileTransferred(sender, e)
-	WScript.Echo e.FileName, "=>", e.Destination	+	WScript.Echo e.FileName & "·=>·" & e.Destination
	End Sub		End Sub

	Set session = WScript.CreateObject("WinSCP.Session", "session_")		Set session = WScript.CreateObject("WinSCP.Session", "session_")
		+	</code>
		+
		+
		+	==== [[vberror]] Error Handling in VBScript ====
		+	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 ''[[https://learn.microsoft.com/en-us/previous-versions/53f3k80h(v=vs.85)\|On Error]]'' statement.
		+
		+	Use ''On Error Resume Next'' to disable default error handling. Then you need to query ''[[https://learn.microsoft.com/en-us/office/vba/language/reference/user-interface-help/err-object\|Err.Number]]'' after every statement to test for errors. You can revert to default error handling (aborting the script) using ''On Error GoTo 0''.
		+
		+	<code vb>
		+	' 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/")
		+	</code>
		+
		+	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 ''[[library_session_dispose\|Session.Dispose]]'' is called even in case of error.
		+
		+	<code vb>
		+	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
		+	...
	</code>		</code>

	===== [[jscript]] JScript Example =====		===== [[jscript]] JScript Example =====
	This example is functionally equivalent to [[library#example\|overall C# example for WinSCP .NET assembly]].		This example is functionally equivalent to [[library#example\|overall C# example for WinSCP .NET assembly]].
		+
		+	There are also [[library_examples\|other JScript examples]].

	<code javascript>		<code javascript>
	Line 80:		Line 163:
	<script language="JScript">		<script language="JScript">

-	// Setup session options	+	try
-	var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");	+	{
-	sessionOptions.Protocol = Protocol_Sftp;	+	····// Setup session options
-	sessionOptions.HostName = "example.com";	+	····var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");
-	sessionOptions.UserName = "user";	+	····sessionOptions.Protocol = Protocol_Sftp;
-	sessionOptions.Password = "mypassword";	+	····sessionOptions.HostName = "example.com";
-	sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx";	+	····sessionOptions.UserName = "user";
		+	····sessionOptions.Password = "mypassword";
		+	····sessionOptions.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx...";

-	var session = WScript.CreateObject("WinSCP.Session");	+	····var session = WScript.CreateObject("WinSCP.Session");

-	// Connect	+	try
-	session.Open(sessionOptions);	+	{
		+	········// Connect
		+	········session.Open(sessionOptions);

-	// Upload files	+	········// Upload files
-	var transferOptions = WScript.CreateObject("WinSCP.TransferOptions");	+	········var transferOptions = WScript.CreateObject("WinSCP.TransferOptions");
-	transferOptions.TransferMode = TransferMode_Binary;	+	········transferOptions.TransferMode = TransferMode_Binary;

-	var transferResult = session.PutFiles("d:\\toupload\\*", "/home/user/", false, transferOptions);	+	········var transferResult =
-		+	···········session.PutFiles("d:\\toupload\\*", "/home/user/", false, transferOptions);
-	// Throw on any error	+	········
-	transferResult.Check();	+	········// Throw on any error
-		+	········transferResult.Check();
-	// Print results	+	········
-	for (var enumerator = new Enumerator(transferResult.Transfers); !enumerator.atEnd(); enumerator.moveNext())	+	········// 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("Upload of", enumerator.item().FileName, "succeeded");	+	WScript.Echo("Error: " + e.message);
		+	···WScript.Quit(1);
	}		}

	Line 113:		Line 214:

	===== [[vbscript]] VBScript Example =====		===== [[vbscript]] VBScript Example =====
-	This example is functionally equivalent to [[library#example\|overall C# example for WinSCP .NET assembly]].	+	This example is functionally equivalent to [[library#example\|overall C# example for WinSCP .NET assembly]], except for [[#vberror\|error handling]].
		+
		+	There are also [[library_examples\|other VBScript examples]].

	<code vb>		<code vb>
	Line 119:		Line 222:
	<reference object="WinSCP.Session" />		<reference object="WinSCP.Session" />
	<script language="VBScript">		<script language="VBScript">
		+
		+	Option Explicit

	' Setup session options		' Setup session options
		+	Dim sessionOptions
	Set sessionOptions = WScript.CreateObject("WinSCP.SessionOptions")		Set sessionOptions = WScript.CreateObject("WinSCP.SessionOptions")
	With sessionOptions		With sessionOptions
	Line 127:		Line 233:
	.UserName = "user"		.UserName = "user"
	.Password = "mypassword"		.Password = "mypassword"
-	.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"	+	.SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
	End With		End With

		+	Dim session
	Set session = WScript.CreateObject("WinSCP.Session")		Set session = WScript.CreateObject("WinSCP.Session")

	Line 136:		Line 243:

	' Upload files		' Upload files
		+	Dim transferOptions
	Set transferOptions = WScript.CreateObject("WinSCP.TransferOptions")		Set transferOptions = WScript.CreateObject("WinSCP.TransferOptions")
	transferOptions.TransferMode = TransferMode_Binary		transferOptions.TransferMode = TransferMode_Binary

		+	Dim transferResult
	Set transferResult = session.PutFiles("d:\toupload\*", "/home/user/", False, transferOptions)		Set transferResult = session.PutFiles("d:\toupload\*", "/home/user/", False, transferOptions)

	Line 145:		Line 254:

	' Print results		' Print results
		+	Dim transfer
	For Each transfer In transferResult.Transfers		For Each transfer In transferResult.Transfers
-	WScript.Echo "Upload of", transfer.FileName, "succeeded"	+	WScript.Echo "Upload of·" & transfer.FileName & "·succeeded"
	Next		Next
		+
		+	' Disconnect, clean up
		+	session.Dispose

	</script>		</script>
	</job>		</job>
	</code>		</code>

Differences

Documentation

Support

Associations

Follow Us