library » Revisions »

Differences

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

library 2011-12-29 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 interface]] 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 =====
-===== Classes =====+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'' 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_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_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_removeargs|RemoveArgs]] | 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]]''. |
 +| [[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_sessionoptions|SessionOptions]] | Defines information to allow an automatic connection and authentication of the session. Is used with ''[[library_session_open|Session.Open]]'' method. |
-| [[library_synchronizationresult|SynchronizationResult]] | Represents results of synchronization (''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]''. | +| [[library_sessionremoteexception|SessionRemoteException]] | Exception associated with the ''[[library_session|Session]]'', originating from WinSCP console session. | 
-| [[library_touchargs|TouchArgs]] | Provides data for remote file timestamp change event. | +| [[library_synchronizationresult|SynchronizationResult]] | Represents results of synchronization (''[[library_session_synchronizedirectories|Session.SynchronizeDirectories]]''). | 
-| [[library_transferargs|TransferArgs]] | Provides data for ''[[library_session_filetransfer|Session.FileTransfer]]'' event. |+| [[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_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