Session Class

Namespace: WinSCP

public sealed class Session : IDisposable

Public NotInheritable Class Session
    Implements IDisposable

To use the class:

• Create an instance of SessionOptions and fill in all needed information to connect and authenticate the session automatically;
• Create an instance of Session class;
• Usually all properties of Session can be left with their default values;
• Assign event handlers, if continuous monitoring of operation is required;
• Call Open method passing instance of SessionOptions;
• Use any file manipulation methods you need, such as GetFiles, PutFiles, SynchronizeDirectories.

The class is locked against concurrent accesses from multiple threads. Though you can use several instances of the class in parallel, even from different threads.

There are two classes of operations, hence two classes of methods; atomic operations, such as Open, ListDirectory, etc; and batch operations, such as GetFiles, PutFiles, SynchronizeDirectories, etc.

Methods from both classes throw SessionLocalException on error in communication with WinSCP console session.

Methods for atomic operations throw SessionRemoteException on error originating from WinSCP console session (referred to as “failure” below).

Methods for batch operations return an instance of descendant of OperationResultBase class (such as TransferOperationResult or SynchronizationResult). Such result class stores list of operations performed (e.g. TransferOperationResult.Uploads), and list of failures (OperationResultBase.Failures).

Every structure representing operation performed may refer (e.g. in TransferEventArgs.Error) to one of the failures, if the failure can be explicitly associated with the operation. So often the same failure (represented by SessionRemoteException) will be referenced twice in the results.

But there can be failures that cannot be explicitly associated with any operation represented in results. An example is an error when listing contents of remote directory to determine list of files to downloads. The listing is not represented in the results, so the failure will be included only in a generic list of failures.

If you do not want to check the list of failures after every batch operation method call, you can use method OperationResultBase.Check to throw the first failure in the list, if any failure occurred:

// Throw, if upload fails
session.PutFiles(localPath, remotePath).Check();

Also for all failures the Session.Failed event is raised.

The batch operation though typically aborts on the first major failure. To customize error processing, handle Session.QueryReceived. For an example, see Recursively download directory tree with custom error handling.

For simple handling of errors, see overall example for WinSCP .NET assembly or any other example.

For example how to check and print errors, but continue, see real-life example Search recursively for text in remote directory / Grep files over SFTP/FTP protocol.