Differences
This shows you the differences between the selected revisions of the page.
| library 2012-02-18 | library 2024-10-03 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== WinSCP .NET Assembly ====== | + | ====== WinSCP .NET Assembly and COM Library ====== |
| - | WinSCP .NET Assembly ''winscp.dll'' is .NET wrapper around WinSCP [[scripting|scripting interface]] that allows connecting to a remote machine and manipulating remote files over SFTP, SCP or FTP session from .NET applications. | + | 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, S3 and SCP sessions from .NET languages, such as [[#csharp|C#]], [[#vbnet|VB.NET]], and others, or from automation environments supporting .NET, such as [[library_powershell|PowerShell]], [[library_ssis|SQL Server Integration Services (SSIS)]] and Microsoft Azure WebSites and Functions. |
| - | 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, VBScript, Perl or Python. | + | 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. |
| - | &future_feature | + | The assembly targets .NET Framework 4.0 and .NET Standard 2.0. |
| + | |||
| + | ===== [[purpose]] Purpose of the Assembly ===== | ||
| + | |||
| + | The library is primarily intended for advanced automation tasks on Microsoft Windows that require conditional processing, loops or other control structures for which the basic [[scripting|scripting interface]] is too limited. | ||
| + | |||
| + | You can also use the assembly to write scripts that [[guide_custom_commands_automation|extend functionality of WinSCP GUI]]. | ||
| + | |||
| + | The library is not a general purpose file transfer library. It particularly has a limited support for an interactive processing, and as such it is not well suited for use in GUI applications. | ||
| + | |||
| + | Because the assembly uses ''winscp.exe'' internally, it is also difficult (but not impossible) to use the assembly within a restricted environment like a ==web== server (e.g. with ASP.NET), that limits or even restricts execution of external processes. | ||
| ===== Downloading and Installing the Assembly ===== | ===== Downloading and Installing the Assembly ===== | ||
| - | First, you need to [[library_install|download and install the assembly]]. | + | First you need to [[library_install|download and install the assembly]]. |
| - | ===== Three Steps to Start Using WinSCP .NET Assembly ===== | + | ===== [[using]] Using Classes from WinSCP .NET Assembly ===== |
| - | - Create an instance of ''[[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_sessionoptions|WinSCP.SessionOptions]]'' class and fill in all necessary information to allow an automatic connection and authentication of your session. |
| - | - Create an instance of ''[[library_session|WinSCP.Session]]'' class. Optionally you can hook handlers of some events of the class. | + | - 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''. | - Open the session using ''[[library_session_open|Session.Open]]'' method, passing instance of your ''WinSCP.SessionOptions''. | ||
| Line 19: | Line 29: | ||
| * ''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]'' to [[task_synchronize_full|synchronize directories]]. | * ''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]'' to [[task_synchronize_full|synchronize directories]]. | ||
| - | ===== Classes ===== | + | ===== [[classes]] Classes ===== |
| Namespace: ''WinSCP'' | Namespace: ''WinSCP'' | ||
| Line 25: | Line 35: | ||
| | [[library_chmodeventargs|ChmodEventArgs]] | Provides data for change of permissions event. | | | [[library_chmodeventargs|ChmodEventArgs]] | Provides data for change of permissions event. | | ||
| | [[library_commandexecutionresult|CommandExecutionResult]] | Represents results of [[library_session_executecommand|Session.ExecuteCommand]]. | | | [[library_commandexecutionresult|CommandExecutionResult]] | Represents results of [[library_session_executecommand|Session.ExecuteCommand]]. | | ||
| + | | [[library_comparisondifference|ComparisonDifference]] | Represents data about a single difference identified by [[library_session_comparedirectories|''Session.CompareDirectories'']]. | | ||
| | [[library_failedeventargs|FailedEventArgs]] | Provides data for ''[[library_session_failed|Session.Failed]]'' event. | | | [[library_failedeventargs|FailedEventArgs]] | Provides data for ''[[library_session_failed|Session.Failed]]'' event. | | ||
| | [[library_fileoperationeventargs|FileOperationEventArgs]] | Provides data for abstract file operation event. | | | [[library_fileoperationeventargs|FileOperationEventArgs]] | Provides data for abstract file operation event. | | ||
| | [[library_filepermissions|FilePermissions]] | Represents *nix-style remote file permissions. | | | [[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_operationeventargs|OperationEventArgs]] | Provides data for abstract operation event. | | ||
| | [[library_operationresultbase|OperationResultBase]] | Represents results of abstract batch operation. | | | [[library_operationresultbase|OperationResultBase]] | Represents results of abstract batch operation. | | ||
| | [[library_remotedirectoryinfo|RemoteDirectoryInfo]] | Represents data about remote directory. | | | [[library_remotedirectoryinfo|RemoteDirectoryInfo]] | Represents data about remote directory. | | ||
| | [[library_remotefileinfo|RemoteFileInfo]] | Represents data about remote file. | | | [[library_remotefileinfo|RemoteFileInfo]] | Represents data about remote file. | | ||
| + | | [[library_remotepath|RemotePath]] | Performs operations on ''string'' instances that contain file or directory path. | | ||
| | [[library_removaleventargs|RemovalEventArgs]] | Provides data for remote file removal event. | | | [[library_removaleventargs|RemovalEventArgs]] | Provides data for remote file removal event. | | ||
| | [[library_removaloperationresult|RemovalOperationResult]] | Represents results of file removal (''[[library_session_removefiles|Session.RemoveFiles]]''). | | | [[library_removaloperationresult|RemovalOperationResult]] | Represents results of file removal (''[[library_session_removefiles|Session.RemoveFiles]]''). | | ||
| Line 44: | Line 57: | ||
| | [[library_transferoperationresult|TransferOperationResult]] | Represents results of file transfer (''[[library_session_getfiles|Session.GetFiles]]'' or ''[[library_session_putfiles|Session.PutFiles]]''). | | | [[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_transferoptions|TransferOptions]] | Defines options for file transfers. | | ||
| + | | [[library_transferresumesupport|TransferResumeSupport]] | Configures automatic resume/transfer to temporary filename. | | ||
| - | ===== Examples ===== | + | ===== Generating Code ===== |
| - | ==== C# Example ==== | + | |
| - | There are also [[library_examples#csharp|other C# examples]]. | + | 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> | <code csharp> | ||
| Line 60: | Line 81: | ||
| { | { | ||
| // Setup session options | // Setup session options | ||
| - | SessionOptions sessionOptions = new SessionOptions(); | + | SessionOptions sessionOptions = new SessionOptions |
| - | sessionOptions.Protocol = Protocol.Sftp; | + | { |
| - | sessionOptions.HostName = "example.com"; | + | ················Protocol = Protocol.Sftp, |
| - | sessionOptions.UserName = "user"; | + | ···············HostName = "example.com", |
| - | sessionOptions.Password = "mypassword"; | + | ···············UserName = "user", |
| - | sessionOptions.SshHostKey = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"; | + | ···············Password = "mypassword", |
| + | ···············SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." | ||
| + | }; | ||
| using (Session session = new Session()) | using (Session session = new Session()) | ||
| Line 77: | Line 100: | ||
| TransferOperationResult transferResult; | TransferOperationResult transferResult; | ||
| - | transferResult = session.PutFiles(@"d:\toupload\*", "/home/user/", false, transferOptions); | + | transferResult = |
| + | ···················session.PutFiles(@"d:\toupload\*", "/home/user/", false, transferOptions); | ||
| // Throw on any error | // Throw on any error | ||
| Line 91: | Line 115: | ||
| return 0; | return 0; | ||
| } | } | ||
| - | catch(Exception e) | + | catch·(Exception e) |
| { | { | ||
| Console.WriteLine("Error: {0}", e); | Console.WriteLine("Error: {0}", e); | ||
| Line 100: | Line 124: | ||
| </code> | </code> | ||
| - | ==== VB.NET Example ==== | + | ==== [[vbnet]] VB.NET Example ==== |
| - | There are also [[library_examples#vbnet|other VB.NET examples]]. | + | There are also [[library_examples|other VB.NET examples]]. |
| <code vbnet> | <code vbnet> | ||
| - | Imports System | ||
| Imports WinSCP | Imports WinSCP | ||
| Line 119: | Line 142: | ||
| .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 | ||
| - | Using session As Session = New Session | + | Using session As New Session |
| ' Connect | ' Connect | ||
| session.Open(sessionOptions) | session.Open(sessionOptions) | ||
| Line 131: | Line 154: | ||
| Dim transferResult As TransferOperationResult | Dim transferResult As TransferOperationResult | ||
| - | transferResult = session.PutFiles("d:\toupload\*", "/home/user/", False, transferOptions) | + | 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 As TransferEventArgs | ||
| For Each transfer In transferResult.Transfers | For Each transfer In transferResult.Transfers | ||
| Console.WriteLine("Upload of {0} succeeded", transfer.FileName) | Console.WriteLine("Upload of {0} succeeded", transfer.FileName) | ||
| Line 154: | Line 177: | ||
| </code> | </code> | ||
| - | ==== Examples in Other Languages ==== | + | ==== [[powershell]] PowerShell Example ==== |
| - | See [[library_examples|examples in other languages]]. | + | 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]]. | ||
| + | Because WinSCP uses [[license|the GPL license]] it's important to keep the %%GPL%% license file around.((Simply said, keep all files from ''WinSCP-X.X.X-Automation.zip'' package together.)) Your software doesn't have to be licensed under GPL as the WinSCP .NET Assembly is using WinSCP as an executable, via its public [[scripting|scripting interface]], and not as a library. | ||