Differences
This shows you the differences between the selected revisions of the page.
| 2016-05-24 | 2016-09-05 | ||
| many people require explanation why it is possible to use the .net assembly under mit license despite the applkication using gpl license (martin) | removed (210.56.127.87) (hidden) | ||
| Line 1: | Line 1: | ||
| - | ====== WinSCP .NET Assembly and COM Library ====== | ||
| - | The WinSCP .NET assembly ''winscpnet.dll'' is a .NET wrapper around WinSCP's [[scripting|scripting interface]] that allows your code to connect to a remote machine and manipulate remote files over SFTP, FTP, WebDAV and SCP sessions from .NET languages, such as [[#csharp|C#]], [[#vbnet|VB.NET]], and others, or from environments supporting .NET, such as [[library_powershell|PowerShell]], [[library_ssis|SQL Server Integration Services (SSIS)]], ASP.NET and Microsoft Azure WebSite. | ||
| - | The assembly is also exposed to COM, and as such it can be used from variety of other programming languages and development environments--e.g., [[library_com_wsh|WSH-hosted active scripting languages]] like JScript and VBScript, [[library_vb|Visual Basic for Applications (VBA)]], [[library_perl|Perl]], and Python. | ||
| - | |||
| - | The library is primarily intended for advanced automation tasks that require conditional processing, loops or other control structures for which the basic [[scripting|scripting interface]] is too limited. The library is not a general purpose file transfer library. It particularly lacks support for interactive processing and as such it is not well suited for use in GUI applications. | ||
| - | |||
| - | You can write a script using the assembly that [[guide_custom_commands_automation|extends functionality of WinSCP GUI]]. | ||
| - | |||
| - | ===== Downloading and Installing the Assembly ===== | ||
| - | First you need to [[library_install|download and install the assembly]]. | ||
| - | |||
| - | ===== Using Classes from WinSCP .NET Assembly ===== | ||
| - | - Create an instance of the ''[[library_sessionoptions|WinSCP.SessionOptions]]'' class and fill in all necessary information to allow an automatic connection and authentication of your session. | ||
| - | - Create an instance of the ''[[library_session|WinSCP.Session]]'' class. Optionally you can hook handlers of some events of the class. | ||
| - | - Open the session using ''[[library_session_open|Session.Open]]'' method, passing instance of your ''WinSCP.SessionOptions''. | ||
| - | |||
| - | Once the session is opened, you can use any of the ''WinSCP.Session'' [[library_session#methods|methods]] to manipulate remote files, e.g., | ||
| - | * ''[[library_session_getfiles|Session.GetFiles]]'' to [[task_download|download files]], | ||
| - | * ''[[library_session_putfiles|Session.PutFiles]]'' to [[task_upload|upload files]] or | ||
| - | * ''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]'' to [[task_synchronize_full|synchronize directories]]. | ||
| - | |||
| - | ===== Classes ===== | ||
| - | Namespace: ''WinSCP'' | ||
| - | |||
| - | ^ Class ^ Description ^ | ||
| - | | [[library_chmodeventargs|ChmodEventArgs]] | Provides data for change of permissions event. | | ||
| - | | [[library_commandexecutionresult|CommandExecutionResult]] | Represents results of [[library_session_executecommand|Session.ExecuteCommand]]. | | ||
| - | | [[library_failedeventargs|FailedEventArgs]] | Provides data for ''[[library_session_failed|Session.Failed]]'' event. | | ||
| - | | [[library_fileoperationeventargs|FileOperationEventArgs]] | Provides data for abstract file operation event. | | ||
| - | | [[library_filepermissions|FilePermissions]] | Represents *nix-style remote file permissions. | | ||
| - | | [[library_filetransferprogresseventargs|FileTransferProgressEventArgs]] | Provides data for file transfer progress event. | | ||
| - | | [[library_operationeventargs|OperationEventArgs]] | Provides data for abstract operation event. | | ||
| - | | [[library_operationresultbase|OperationResultBase]] | Represents results of abstract batch operation. | | ||
| - | | [[library_remotedirectoryinfo|RemoteDirectoryInfo]] | Represents data about remote directory. | | ||
| - | | [[library_remotefileinfo|RemoteFileInfo]] | Represents data about remote file. | | ||
| - | | [[library_removaleventargs|RemovalEventArgs]] | Provides data for remote file removal event. | | ||
| - | | [[library_removaloperationresult|RemovalOperationResult]] | Represents results of file removal (''[[library_session_removefiles|Session.RemoveFiles]]''). | | ||
| - | | [[library_session|Session]] | Represents session. Provides methods for manipulating remote files. | | ||
| - | | [[library_sessionexception|SessionException]] | Exception associated with the ''[[library_session|Session]]''. | | ||
| - | | [[library_sessionlocalexception|SessionLocalException]] | Exception associated with the ''[[library_session|Session]]'' originating from this assembly. | | ||
| - | | [[library_sessionoptions|SessionOptions]] | Defines information to allow an automatic connection and authentication of the session. Is used with ''[[library_session_open|Session.Open]]'' method. | | ||
| - | | [[library_sessionremoteexception|SessionRemoteException]] | Exception associated with the ''[[library_session|Session]]'', originating from WinSCP console session. | | ||
| - | | [[library_synchronizationresult|SynchronizationResult]] | Represents results of synchronization (''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]''). | | ||
| - | | [[library_toucheventargs|TouchEventArgs]] | Provides data for remote file timestamp change event. | | ||
| - | | [[library_transfereventargs|TransferEventArgs]] | Provides data for file transfer event. | | ||
| - | | [[library_transferoperationresult|TransferOperationResult]] | Represents results of file transfer (''[[library_session_getfiles|Session.GetFiles]]'' or ''[[library_session_putfiles|Session.PutFiles]]''). | | ||
| - | | [[library_transferoptions|TransferOptions]] | Defines options for file transfers. | | ||
| - | | [[library_transferresumesupport|TransferResumeSupport]] | Configures automatic resume/transfer to temporary filename. | | ||
| - | |||
| - | ===== Generating Code ===== | ||
| - | |||
| - | You can have WinSCP [[ui_generateurl|generate a code template for you]]. | ||
| - | |||
| - | ===== [[example]] Examples ===== | ||
| - | |||
| - | See [[library_examples|list of all examples]]. | ||
| - | |||
| - | ==== [[csharp]] C# Example ==== | ||
| - | There are also [[library_examples|other C# examples]]. | ||
| - | |||
| - | <code csharp> | ||
| - | using System; | ||
| - | using WinSCP; | ||
| - | |||
| - | class Example | ||
| - | { | ||
| - | public static int Main() | ||
| - | { | ||
| - | try | ||
| - | { | ||
| - | // Setup session options | ||
| - | SessionOptions sessionOptions = new SessionOptions | ||
| - | { | ||
| - | Protocol = Protocol.Sftp, | ||
| - | HostName = "example.com", | ||
| - | UserName = "user", | ||
| - | Password = "mypassword", | ||
| - | SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | ||
| - | }; | ||
| - | |||
| - | using (Session session = new Session()) | ||
| - | { | ||
| - | // Connect | ||
| - | session.Open(sessionOptions); | ||
| - | |||
| - | // Upload files | ||
| - | TransferOptions transferOptions = new TransferOptions(); | ||
| - | transferOptions.TransferMode = TransferMode.Binary; | ||
| - | |||
| - | TransferOperationResult transferResult; | ||
| - | transferResult = session.PutFiles(@"d:\toupload\*", "/home/user/", false, transferOptions); | ||
| - | |||
| - | // Throw on any error | ||
| - | transferResult.Check(); | ||
| - | |||
| - | // Print results | ||
| - | foreach (TransferEventArgs transfer in transferResult.Transfers) | ||
| - | { | ||
| - | Console.WriteLine("Upload of {0} succeeded", transfer.FileName); | ||
| - | } | ||
| - | } | ||
| - | |||
| - | return 0; | ||
| - | } | ||
| - | catch (Exception e) | ||
| - | { | ||
| - | Console.WriteLine("Error: {0}", e); | ||
| - | return 1; | ||
| - | } | ||
| - | } | ||
| - | } | ||
| - | </code> | ||
| - | |||
| - | ==== [[vbnet]] VB.NET Example ==== | ||
| - | There are also [[library_examples|other VB.NET examples]]. | ||
| - | |||
| - | <code vbnet> | ||
| - | Imports WinSCP | ||
| - | |||
| - | Friend Class Example | ||
| - | |||
| - | Public Shared Function Main() As Integer | ||
| - | |||
| - | Try | ||
| - | ' Setup session options | ||
| - | Dim sessionOptions As New SessionOptions | ||
| - | With sessionOptions | ||
| - | .Protocol = Protocol.Sftp | ||
| - | .HostName = "example.com" | ||
| - | .UserName = "user" | ||
| - | .Password = "mypassword" | ||
| - | .SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | ||
| - | End With | ||
| - | |||
| - | Using session As New Session | ||
| - | ' Connect | ||
| - | session.Open(sessionOptions) | ||
| - | |||
| - | ' Upload files | ||
| - | Dim transferOptions As New TransferOptions | ||
| - | transferOptions.TransferMode = TransferMode.Binary | ||
| - | |||
| - | Dim transferResult As TransferOperationResult | ||
| - | transferResult = session.PutFiles("d:\toupload\*", "/home/user/", False, transferOptions) | ||
| - | |||
| - | ' Throw on any error | ||
| - | transferResult.Check() | ||
| - | |||
| - | ' Print results | ||
| - | For Each transfer In transferResult.Transfers | ||
| - | Console.WriteLine("Upload of {0} succeeded", transfer.FileName) | ||
| - | Next | ||
| - | End Using | ||
| - | |||
| - | Return 0 | ||
| - | Catch e As Exception | ||
| - | Console.WriteLine("Error: {0}", e) | ||
| - | Return 1 | ||
| - | End Try | ||
| - | |||
| - | End Function | ||
| - | |||
| - | End Class | ||
| - | </code> | ||
| - | |||
| - | ==== [[powershell]] PowerShell Example ==== | ||
| - | See [[library_powershell#example|overall PowerShell example]] or [[library_examples|any other PowerShell example]]. | ||
| - | |||
| - | ==== [[jscript]] JScript Example ==== | ||
| - | See [[library_com_wsh#jscript|overall JScript example]] or [[library_examples|any other JScript example]]. | ||
| - | |||
| - | ==== [[vbscript]] VBScript Example ==== | ||
| - | See [[library_com_wsh#vbscript|overall VBScript example]] or [[library_examples|any other VBScript example]]. | ||
| - | |||
| - | ==== [[vba]] VBA Example ==== | ||
| - | See [[library_vb#example|overall VBA example]]. | ||
| - | |||
| - | ==== [[perl]] Perl Example ==== | ||
| - | See [[library_perl#example|overall Perl example]]. | ||
| - | |||
| - | ==== [[ssis]] SSIS Example ==== | ||
| - | See [[library_ssis#example|overall SSIS example]]. | ||
| - | |||
| - | ===== [[net]] Converting Script to Code Based on .NET Assembly ===== | ||
| - | When you find yourself limited by [[scripting]] capabilities, you may consider [[library_from_script|converting your script to code that uses WinSCP .NET assembly]]. | ||
| - | |||
| - | ===== [[license]] License ===== | ||
| - | The WinSCP .NET Assembly is a free library: you can use it, redistribute it and/or modify it under the terms of the [[https://www.mozilla.org/MPL/2.0/|Mozilla Public License Version 2.0]]. | ||
| - | |||
| - | Note that [[library_install#installing|the assembly interacts with WinSCP executable]], which uses a [[license|different license, the GPL]]. Though as WinSCP is used as an executable, via its public [[scripting|scripting interface]], not as a library, all you need to do to comply with the GPL license, is to keep %%GPL%% license file around.((Simply said, keep all files from ''winscpXXXautomation.zip'' package together.)) | ||