WinSCP .NET Assembly and COM Library

The WinSCP .NET assembly winscpnet.dll is a .NET wrapper around WinSCP’s 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 C#, VB.NET, and others, or from automation environments supporting .NET, such as PowerShell, 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., WSH-hosted active scripting languages like JScript and VBScript, Visual Basic for Applications (VBA), Perl, and Python.

Advertisement

The assembly targets .NET Framework 4.0 and .NET Standard 2.0.

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 interface is too limited.

Advertisement

You can also use the assembly to write scripts that 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 download and install the assembly.

Using Classes from WinSCP .NET Assembly

  1. Create an instance of the WinSCP.SessionOptions class and fill in all necessary information to allow an automatic connection and authentication of your session.
  2. Create an instance of the WinSCP.Session class. Optionally you can hook handlers of some events of the class.
  3. Open the session using Session.Open method, passing instance of your WinSCP.SessionOptions.

Once the session is opened, you can use any of the WinSCP.Session methods to manipulate remote files, e.g.,

Classes

Namespace: WinSCP

Class Description
ChmodEventArgs Provides data for change of permissions event.
CommandExecutionResult Represents results of Session.ExecuteCommand.
ComparisonDifference Represents data about a single difference identified by Session.CompareDirectories.
FailedEventArgs Provides data for Session.Failed event.
FileOperationEventArgs Provides data for abstract file operation event.
FilePermissions Represents *nix-style remote file permissions.
FileTransferProgressEventArgs Provides data for file transfer progress event.
OperationEventArgs Provides data for abstract operation event.
OperationResultBase Represents results of abstract batch operation.
RemoteDirectoryInfo Represents data about remote directory.
RemoteFileInfo Represents data about remote file.
RemotePath Performs operations on string instances that contain file or directory path.
RemovalEventArgs Provides data for remote file removal event.
RemovalOperationResult Represents results of file removal (Session.RemoveFiles).
Session Represents session. Provides methods for manipulating remote files.
SessionException Exception associated with the Session.
SessionLocalException Exception associated with the Session originating from this assembly.
SessionOptions Defines information to allow an automatic connection and authentication of the session. Is used with Session.Open method.
SessionRemoteException Exception associated with the Session, originating from WinSCP console session.
SynchronizationResult Represents results of synchronization (Session.SynchronizeDirectories).
TouchEventArgs Provides data for remote file timestamp change event.
TransferEventArgs Provides data for file transfer event.
TransferOperationResult Represents results of file transfer (Session.GetFiles or Session.PutFiles).
TransferOptions Defines options for file transfers.
TransferResumeSupport Configures automatic resume/transfer to temporary filename.

Advertisement

Generating Code

You can have WinSCP generate a code template for you.

Examples

See list of all examples.

C# Example

There are also other C# examples.

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;
        }
    }
}

Advertisement

VB.NET Example

There are also other VB.NET examples.

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

Advertisement

PowerShell Example

See overall PowerShell example or any other PowerShell example.

JScript Example

See overall JScript example or any other JScript example.

VBScript Example

See overall VBScript example or any other VBScript example.

VBA Example

See overall VBA example.

Perl Example

See overall Perl example.

SSIS Example

See overall SSIS example.

Converting Script to Code Based on .NET Assembly

When you find yourself limited by scripting capabilities, you may consider converting your script to code that uses WinSCP .NET assembly.

License

The WinSCP .NET Assembly is a free library: you can use it, redistribute it and/or modify it under the terms of the Mozilla Public License Version 2.0.

Because WinSCP uses the GPL license it’s important to keep the GPL license file around.1 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 interface, and not as a library.

  1. Simply said, keep all files from WinSCP-X.X.X-Automation.zip package together.Back

Last modified: by martin