library » Revisions »

Differences

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

library 2012-09-05 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 ''winscp.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, SCP, and FTP sessions from .NET languages, such as [[library#csharp|C#]], [[library#vbnet|VB.NET]], [[library#powershell|PowerShell]] and others, or from environments supporting .NET addons, such as [[library_ssis|SQL Server Integration Services (SSIS)]].+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.
-&beta_feature+The assembly targets .NET Framework 4.0 and .NET Standard 2.0. 
 + 
 +===== [[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]].
-===== Three Steps to Start Using 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 19: 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 25: 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_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 44: Line 57:
| [[library_transferoperationresult|TransferOperationResult]] | Represents results of file transfer (''[[library_session_getfiles|Session.GetFiles]]'' or ''[[library_session_putfiles|Session.PutFiles]]'').  | | [[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 ===== ===== [[example]] Examples =====
 +
 +See [[library_examples|list of all examples]].
 +
==== [[csharp]] C# Example ==== ==== [[csharp]] C# Example ====
There are also [[library_examples|other C# examples]]. There are also [[library_examples|other C# examples]].
Line 60: Line 81:
        {         {
            // Setup session options             // Setup session options
-            SessionOptions sessionOptions = new SessionOptions {+            SessionOptions sessionOptions = new SessionOptions 
 + ···········{
                Protocol = Protocol.Sftp,                 Protocol = Protocol.Sftp,
                HostName = "example.com",                 HostName = "example.com",
                UserName = "user",                 UserName = "user",
                Password = "mypassword",                 Password = "mypassword",
-                SshHostKeyFingerprint = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"+                SshHostKeyFingerprint = "ssh-rsa 2048 xxxxxxxxxxx..."
            };             };
Line 78: 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 105: Line 128:
<code vbnet> <code vbnet>
-Imports System 
Imports WinSCP Imports WinSCP
Line 120: Line 142:
                .UserName = "user"                 .UserName = "user"
                .Password = "mypassword"                 .Password = "mypassword"
-                .SshHostKeyFingerprint = "ssh-rsa 1024 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 Session = New Session+            Using session As New Session
                ' Connect                 ' Connect
                session.Open(sessionOptions)                 session.Open(sessionOptions)
Line 132: Line 154:
                Dim transferResult As TransferOperationResult                 Dim transferResult As TransferOperationResult
-                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
-                Dim transfer As TransferEventArgs 
                For Each transfer In transferResult.Transfers                 For Each transfer In transferResult.Transfers
                    Console.WriteLine("Upload of {0} succeeded", transfer.FileName)                     Console.WriteLine("Upload of {0} succeeded", transfer.FileName)
Line 156: Line 178:
==== [[powershell]] PowerShell Example ==== ==== [[powershell]] PowerShell Example ====
-There are also [[library_examples|other PowerShell examples]]. +See [[library_powershell#example|overall PowerShell example]] or [[library_examples|any other PowerShell example]].
- +
-<code powershell> +
-try +
-{ +
-   # Load WinSCP .NET assembly +
-····[Reflection.Assembly]::LoadFrom("WinSCP.dll") | Out-Null +
- +
-   # Setup session options +
-    $sessionOptions = New-Object WinSCP.SessionOptions +
-    $sessionOptions.Protocol = [WinSCP.Protocol]::Sftp +
-    $sessionOptions.HostName = "example.com" +
-    $sessionOptions.UserName = "user" +
-    $sessionOptions.Password = "mypassword" +
-    $sessionOptions.SshHostKeyFingerprint = "ssh-rsa 1024 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" +
- +
-    $session = New-Object WinSCP.Session +
- +
-    try +
-    { +
-        # Connect +
-        $session.Open($sessionOptions) +
- +
-        # Upload files +
-        $transferOptions = New-Object WinSCP.TransferOptions +
-        $transferOptions.TransferMode = [WinSCP.TransferMode]::Binary +
- +
-        $transferResult = $session.PutFiles("b:\toupload\*", "./", $FALSE, $transferOptions) +
- +
-        # Throw on any error +
-        $transferResult.Check() +
- +
-        # Print results +
-        foreach ($transfer in $transferResult.Transfers) +
-        { +
-            Write-Host ("Upload of {0} succeeded" -f $transfer.FileName) +
-        } +
-    } +
-    finally +
-    { +
-        # Disconnect, clean up +
-        $session.Dispose() +
-    } +
- +
-    exit 0 +
-} +
-catch [Exception] +
-{ +
-    Write-Host $_.Exception.Message +
-    exit 1 +
-} +
-</code>+
==== [[jscript]] JScript Example ==== ==== [[jscript]] JScript Example ====
Line 224: Line 195:
See [[library_ssis#example|overall 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