library » Revisions »

Differences

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

library 2011-12-31 library 2024-10-03 (current)
Line 1: Line 1:
-====== WinSCP .NET Assembly ====== +====== WinSCP .NET Assembly and COM Library ====== 
-WinSCP .NET Assembly ''winscp.dll'' is C# 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.
-===== Using WinSCP .NET Assembly ===== +The assembly targets .NET Framework 4.0 and .NET Standard 2.0.
-First, you need to 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.+
-Then you create an instance of ''[[library_session|WinSCP.Session]]'' class. Optionally you hook handlers of some events of the class. Then you open the session using ''[[library_session_open|Session.Open]]'' method, passing instance of your ''WinSCP.SessionOptions''.+===== [[purpose]] Purpose of the Assembly =====
-Once the session is opened, you can use any of the ''WinSCP.Session'' methods to manipulate remote files. For example use ''[[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]].+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.
-===== Classes =====+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''. 
 + 
 +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]] Classes =====
Namespace: ''WinSCP'' Namespace: ''WinSCP''
^ Class ^ Description ^ ^ Class ^ Description ^
-| [[library_chmodargs|ChmodArgs]] | Provides data for change of permissions event. | +| [[library_chmodeventargs|ChmodEventArgs]] | Provides data for change of permissions event. | 
-| [[library_failedargs|FailedArgs]] | Provides data for ''[[library_session_failed|Session.Failed]]'' event. |+| [[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_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_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_operationresult|OperationResult<T>]] | Represents results of simple batch operation.  | +| [[library_remotedirectoryinfo|RemoteDirectoryInfo]] | Represents data about remote directory.  |
-| [[library_permissions|Permissions]] | Represents *nix-style remote file permissions.  | +
-| [[library_removalargs|RemovalArgs]] | 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 30: Line 53:
| [[library_sessionremoteexception|SessionRemoteException]] | Exception associated with the ''[[library_session|Session]]'', originating from WinSCP console session. | | [[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_synchronizationresult|SynchronizationResult]] | Represents results of synchronization (''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]''). |
-| [[library_touchargs|TouchArgs]] | Provides data for remote file timestamp change event. | +| [[library_toucheventargs|TouchEventArgs]] | Provides data for remote file timestamp change event. | 
-| [[library_transferargs|TransferArgs]] | 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;
using WinSCP; using WinSCP;
-class Test+class Example
{ {
-    static void Main()+    public static int Main()
    {     {
        try         try
        {         {
            // Setup session options             // Setup session options
-            SessionOptions sessionOptions = new SessionOptions(); +            SessionOptions sessionOptions = new SessionOptions 
-            sessionOptions.Protocol = SessionProtocols.Sftp; +            { 
-           sessionOptions.HostName = "example.com"; +················Protocol = Protocol.Sftp, 
-           sessionOptions.UserName = "user"; + ···············HostName = "example.com", 
-           sessionOptions.Password = "mypassword"; + ···············UserName = "user", 
-           sessionOptions.HostKey = "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..." 
 +            };
-            // Connect +            using (Session session = new Session()) 
-············Session session = new Session(); +            { 
-            session.Open(sessionOptions);+                // Connect 
 +················session.Open(sessionOptions);
-············// Upload files +················// Upload files 
- ···········TransferOptions transferOptions = new TransferOptions(); + ···············TransferOptions transferOptions = new TransferOptions(); 
- ···········transferOptions.TransferMode = TransferMode.Binary;+ ···············transferOptions.TransferMode = TransferMode.Binary;
-············OperationResult<TransferArgs> 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 
- ···········transferResult.Check();+ ···············transferResult.Check();
-············// Print results +················// Print results 
- ···········foreach (TransferArgs transfer in transferResult.Operations) + ···············foreach (TransferEventArgs transfer in transferResult.Transfers)
-            { +
-                if (transfer.Error == null)+
                {                 {
                    Console.WriteLine("Upload of {0} succeeded", transfer.FileName);                     Console.WriteLine("Upload of {0} succeeded", transfer.FileName);
-                } 
-                else 
-                { 
-                    Console.WriteLine("Upload of {0} failed: {1}", transfer.FileName, transfer.Error); 
                }                 }
            }             }
 +
 +            return 0;
        }         }
-        catch(Exception e)+        catch·(Exception e)
        {         {
            Console.WriteLine("Error: {0}", e);             Console.WriteLine("Error: {0}", e);
 +            return 1;
        }         }
    }     }
Line 88: 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