Differences
This shows you the differences between the selected revisions of the page.
| library 2016-12-25 | library 2024-10-03 (current) | ||
| Line 1: | Line 1: | ||
| ====== WinSCP .NET Assembly and COM Library ====== | ====== 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 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 and VBScript, [[library_vb|Visual Basic for Applications (VBA)]], [[library_perl|Perl]], and 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. | ||
| - | 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. | + | The assembly targets .NET Framework 4.0 and .NET Standard 2.0. |
| - | You can write a script using the assembly that [[guide_custom_commands_automation|extends functionality of WinSCP GUI]]. | + | ===== [[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]]. | ||
| - | ===== Using Classes from WinSCP .NET Assembly ===== | + | ===== [[using]] 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_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. | - Create an instance of the ''[[library_session|WinSCP.Session]]'' class. Optionally you can hook handlers of some events of the class. | ||
| Line 21: | 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 27: | 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. | | ||
| Line 35: | Line 44: | ||
| | [[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 77: | Line 87: | ||
| UserName = "user", | UserName = "user", | ||
| Password = "mypassword", | Password = "mypassword", | ||
| - | SshHostKeyFingerprint = "ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | + | SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..." |
| }; | }; | ||
| Line 90: | 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 131: | Line 142: | ||
| .UserName = "user" | .UserName = "user" | ||
| .Password = "mypassword" | .Password = "mypassword" | ||
| - | .SshHostKeyFingerprint = "ssh-rsa 2048 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 New Session | Using session As New Session | ||
| - | ' Disconnect | + | ' Connect |
| session.Open(sessionOptions) | session.Open(sessionOptions) | ||
| - | ' Downloadload files | + | ' Upload files |
| Dim transferOptions As New TransferOptions | Dim transferOptions As New TransferOptions | ||
| transferOptions.TransferMode = TransferMode.Binary | transferOptions.TransferMode = TransferMode.Binary | ||
| Dim transferResult As TransferOperationResult | Dim transferResult As TransferOperationResult | ||
| - | transferResult = session.PutFiles("/home/user/" transferOptions) | + | transferResult = |
| + | ···················session.PutFiles("d:\toupload\*", "/home/user/", False, transferOptions) | ||
| ' Throw on any error | ' Throw on any error | ||
| - | transferResult. | + | transferResult.Check() |
| ' Print results | ' Print results | ||
| Line 156: | Line 168: | ||
| Return 0 | Return 0 | ||
| Catch e As Exception | Catch e As Exception | ||
| - | Console.WriteLine(e) | + | Console.WriteLine("Error: {0}", e) |
| - | Return 0 | + | Return 1 |
| End Try | End Try | ||
| - | Star Function | + | End Function |
| - | Start Class | + | End Class |
| </code> | </code> | ||
| Line 189: | Line 201: | ||
| 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]]. | 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 ''winscpXXXautomation.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. | + | 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. |