Differences

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

library_com_wsh 2012-02-08		library_com_wsh 2022-10-21 (current)
	Line 1:		Line 1:
-	====== Using WinSCP .NET Assembly via COM and from WSH-hosted Languages ======	+	====== Using WinSCP .NET Assembly from WSH-hosted Active Scripting Languages ======
-	&future_feature	+
-	===== [[registering]] Registering for COM =====	+
-	[[library\|WinSCP .NET assembly]] exposes its full interface to COM. As a COM library, it needs to be registered before use. To register the assembly use:	+
-	<code>	+
-	%WINDIR%\Microsoft.NET\Framework\<version>\RegAsm.exe WinSCP.dll /codebase /tlb	+
-	</code>	+
-	Where the ''%WINDIR%'' is path to your Windows installation, what is typically ''C:\Windows'' or ''C:\WINNT''. Note that you can keep ''%WINDIR%'' as this environment variable should be set on your system to point to the Windows folder. The ''<version>'' is version of .NET framework to register the assembly with. It is recommended to use the latest available, what currenly is ''v4.0.30319''. You may however use any framework version from 2.0 (''v2.0.50727'') up. Note that framework 3.0 and 3.5 do not ship with ''RegAsm.exe''. For these versions use ''RegAsm.exe'' from 2.0.	+

-	Typical registration command for .NET 4.0 would be:	+	===== Installing and Registering for COM =====
-	<code>	+	First, you need to [[library_install\|install the WinSCP·.NET assembly and register it for COM]].
-	%WINDIR%\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe WinSCP.dll /codebase /tlb	+
-	</code>	+

	===== Using from WSH =====		===== Using from WSH =====
	Line 18:		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]] (WSF) and its ''<reference>'' tag for that. It makes WSH convert all enums in the assembly interface into constants 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''.
		+
		+	See how ''%%<reference object="WinSCP.Session"/>%%'' allows use of ''Protocol_Sftp'' in below JScript script embedded in WSF:

	<code javascript>		<code javascript>
	<job>		<job>
-	<reference object="WinSCP.Session"/>	+	<reference object="WinSCP.Session"·/>
	<script language="JScript">		<script language="JScript">

	var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");		var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");
-
	sessionOptions.Protocol = Protocol_Sftp;		sessionOptions.Protocol = Protocol_Sftp;
	sessionOptions.HostName = "example.com";		sessionOptions.HostName = "example.com";
	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 47:		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]].

	If you need to make use of these events:		If you need to make use of these events:
-	* Use overload of ''CreateObject'' with 2 arguments, passing an unique prefix as the second argument (e.g. "session_");	+	* 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.		* Define function with name ''<prefix><event>'' and two arguments (e.g. ''sender'' and ''e'') for every event you need to handle.

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

	Line 69:		Line 61:
	</code>		</code>

-	===== JScript Example =====	+	For a full example, see an example for ''[[library_session_synchronizedirectories#jscript\|Session.SynchronizeDirectories]]''.
		+
		+	And equivalent in VBScript:
		+
		+	<code vb>
		+	Sub session_FileTransferred(sender, e)
		+	WScript.Echo e.FileName & " => " & e.Destination
		+	End Sub
		+
		+	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>
		+
		+	===== [[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>
	<job>		<job>
-	<reference object="WinSCP.Session"/>	+	<reference object="WinSCP.Session"·/>
	<script language="JScript">		<script language="JScript">

-	// Setup session options	+	try
-	var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");	+	{
-		+	····// Setup session options
-	sessionOptions.Protocol = Protocol_Sftp;	+	····var sessionOptions = WScript.CreateObject("WinSCP.SessionOptions");
-	sessionOptions.HostName = "example.com";	+	···sessionOptions.Protocol = Protocol_Sftp;
-	sessionOptions.UserName = "user";	+	····sessionOptions.HostName = "example.com";
-	sessionOptions.Password = "mypassword";	+	····sessionOptions.UserName = "user";
-	sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx";	+	····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);
	}		}
		+
		+	</script>
		+	</job>
		+	</code>
		+
		+	===== [[vbscript]] VBScript Example =====
		+	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>
		+	<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>		</script>
	</job>		</job>
	</code>		</code>

Differences

Documentation

Support

Associations

Follow Us