library » Revisions »

Differences

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

library 2012-01-27 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.
-&future_feature+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.
-===== Three Steps to Start Using WinSCP .NET Assembly ===== +The assembly targets .NET Framework 4.0 and .NET Standard 2.0. 
-  - 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 ''[[library_session|WinSCP.Session]]'' class. Optionally you can hook handlers of some events of the class.+===== [[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 ===== 
 +First you need to [[library_install|download and install the 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_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 14: 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 20: 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_removaleventargs|RemovalEventArgs]] | Provides data for remote file removal event. | 
| [[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_removaloperationresult|RemovalOperationResult]] | Represents results of file removal (''[[library_session_removefiles|Session.RemoveFiles]]'').  |
| [[library_session|Session]] | Represents session. Provides methods for manipulating remote files. | | [[library_session|Session]] | Represents session. Provides methods for manipulating remote files. |
| [[library_sessionexception|SessionException]] | Exception associated with the ''[[library_session|Session]]''. | | [[library_sessionexception|SessionException]] | Exception associated with the ''[[library_session|Session]]''. |
Line 36: Line 55:
| [[library_toucheventargs|TouchEventArgs]] | Provides data for remote file timestamp change event. | | [[library_toucheventargs|TouchEventArgs]] | Provides data for remote file timestamp change event. |
| [[library_transfereventargs|TransferEventArgs]] | Provides data for file transfer 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_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]].
-===== Example ===== 
<code csharp> <code csharp>
using System; using System;
Line 50: 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 66: Line 99:
                transferOptions.TransferMode = TransferMode.Binary;                 transferOptions.TransferMode = TransferMode.Binary;
-                OperationResult<TransferEventArgs> 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 73: Line 107:
                // Print results                 // Print results
-                foreach (TransferEventArgs transfer in transferResult.Operations)+                foreach (TransferEventArgs transfer in transferResult.Transfers)
                {                 {
                    Console.WriteLine("Upload of {0} succeeded", transfer.FileName);                     Console.WriteLine("Upload of {0} succeeded", transfer.FileName);
Line 81: Line 115:
            return 0;             return 0;
        }         }
-        catch(Exception e)+        catch·(Exception e)
        {         {
            Console.WriteLine("Error: {0}", e);             Console.WriteLine("Error: {0}", e);
Line 90: Line 124:
</code> </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 xxxxxxxxxxx..."
 +            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]].
 +
 +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.

Last modified: by martin

Documentation

Support

Associations

Follow Us