library » Revisions »

Differences

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

library 2011-12-28 library 2024-10-03 (current)
Line 1: Line 1:
-~~NOINDEX~~ +====== WinSCP .NET Assembly and COM Library ====== 
-====== WinSCP .NET Assembly ====== +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.
-WinSCP .NET Assembly ''winscp.dll'' is C# wrapper around WinSCP [[scripting|scripting intnerface]] that allows connecting to a remote machine and manipulating remote files over SFTP, SCP or FTP session from .NET applications.+
-===== Using WinSCP .NET Assembly ===== +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.
-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''.+The assembly targets .NET Framework 4.0 and .NET Standard 2.0.
-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]].+===== [[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''. 
 + 
 +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''
-===== Classes ===== 
^ 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_operationresult|OperationResult]]'' | Represents results of batch operation. ·| +| [[library_comparisondifference|ComparisonDifference]] | Represents data about a single difference identified by [[library_session_comparedirectories|''Session.CompareDirectories'']]. | 
-| ''[[library_permissions|Permissions]]'' | Represents *nix-style remote file permissions.  | +| [[library_failedeventargs|FailedEventArgs]] | Provides data for ''[[library_session_failed|Session.Failed]]'' event. | 
-| ''[[library_removeargs|RemoveArgs]]'' | Provides data for remote file removal event. | +| [[library_fileoperationeventargs|FileOperationEventArgs]] | Provides data for abstract file operation event. | 
-| ''[[library_remotefileinfo|RemoteFileInfo]]'' | Represents data about remote file.  | +| [[library_filepermissions|FilePermissions]] | Represents *nix-style remote file permissions.  | 
-| ''[[library_session|Session]]'' | Represents session. Provides methods for manipulating remote files. | +| [[library_filetransferprogresseventargs|FileTransferProgressEventArgs]] | Provides data for file transfer progress event. | 
-| ''[[library_sessionexception|SessionException]]'' | Exception associated with the ''[[library_session|Session]]''. | +| [[library_operationeventargs|OperationEventArgs]] | Provides data for abstract operation event. | 
-| ''[[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_operationresultbase|OperationResultBase]] | Represents results of abstract batch operation.  | 
-| ''[[library_synchronizeresult|SynchronizeResult]]'' | Represents results of synchronization, ''[[library_session_synchronize|Session.Synchronize]]''. | +| [[library_remotedirectoryinfo|RemoteDirectoryInfo]] | Represents data about remote directory.  | 
-| ''[[library_touchargs|TouchArgs]]'' | Provides data for remote file timestamp change event. | +| [[library_remotefileinfo|RemoteFileInfo]] | Represents data about remote file.  | 
-| ''[[library_transferargs|TransferArgs]]'' | Provides data for ''[[library_session_filetransfer|Session.FileTransfer]]'' event. | +| [[library_remotepath|RemotePath]] | Performs operations on ''string'' instances that contain file or directory path. | 
-| ''[[library_transferoptions|TransferOptions]]'' | Defines options for file transfers. |+| [[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 xxxxxxxxxxx..." 
 +            }; 
 + 
 +            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 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