Differences
This shows you the differences between the selected revisions of the page.
| library_com_wsh 2012-02-17 | 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 23: | Line 22: | ||
| 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 41: | 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 57: | 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 67: | 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 | ||
| Line 73: | Line 73: | ||
| </code> | </code> | ||
| - | ===== JScript Example ===== | + | |
| + | ==== [[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> | ||
| Line 81: | Line 163: | ||
| <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); | ||
| } | } | ||
| Line 114: | Line 213: | ||
| </code> | </code> | ||
| - | ===== 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 121: | 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 |
| - | sessionOptions.Protocol = Protocol_Sftp | + | ····.Protocol = Protocol_Sftp |
| - | sessionOptions.HostName = "example.com" | + | ····.HostName = "example.com" |
| - | sessionOptions.UserName = "user" | + | ····.UserName = "user" |
| - | sessionOptions.Password = "mypassword" | + | ····.Password = "mypassword" |
| - | sessionOptions.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 | ||
| + | Dim session | ||
| Set session = WScript.CreateObject("WinSCP.Session") | Set session = WScript.CreateObject("WinSCP.Session") | ||
| ' Connect | ' Connect | ||
| - | session.Open(sessionOptions) | + | session.Open·sessionOptions |
| ' 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 | ||
| - | Set transferResult = session.PutFiles("d:\\toupload\\*", "/home/user/", False, transferOptions) | + | Dim transferResult |
| + | Set transferResult = session.PutFiles("d:\toupload\*", "/home/user/", False, transferOptions) | ||
| ' Throw on any error | ' Throw on any error | ||
| - | transferResult.Check() | + | transferResult.Check |
| ' 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> | ||