This is an old revision of the document!
Session Class
This is the main interface class of the WinSCP assembly.
It represents a session and provides methods for manipulating remote files over SFTP, SCP or FTP session.
This feature will be available only with the next release.
Advertisement
Syntax
Namespace: WinSCP
public sealed class Session : IDisposable
Constructors
| Name | Description |
|---|---|
| Session() | Default constructor. |
Properties
| Name | Description |
|---|---|
| string AdditionalExecutableArguments | Additional command-line arguments to be passed to winscp.com. In general, this should be left with default null. |
| bool DefaultConfiguration | Should WinSCP be forced with the default configuration? true by default. Useful to isolate the console session run from any configuration stored on this machine. |
| string ExecutablePath | Path to winscp.com. The default is null, meaning that winscp.com is expected is the same directory as this assembly. |
| string IniFilePath | Path to an INI file. Used only when DefaultConfiguration is false. When null, default WinSCP configuration storage is used, meaning INI file, if any is present in WinSCP startup directory, or Windows Registry otherwise. |
| string LogPath | Path to store session log file to. Default null mean, no session log file is created. |
| bool Opened | Is session opened yet? true, when Open was successfully called already. Read-only. |
| IList<string> Output | Output of WinSCP console session. See also OutputDataReceived event. Read-only. |
| TimeSpan Timeout | Maximal interval between two consecutive outputs from WinSCP console session, before TimeoutException is thrown. The default is one minute. |
Advertisement
Methods
| Name | Description |
|---|---|
| Dispose | Terminates underlying WinSCP process. Removes XML log file. |
| ExecuteCommand | Executes command on the remote server. |
| FileExists | Checks for existence of remote file. |
| GetFileInfo | Retrieves information about remote file. |
| GetFiles | Downloads files. |
| ListDirectory | Lists remote directory. |
| Open | Opens the session. |
| PutFiles | Uploads files. |
| RemoveFiles | Removes remote files. |
| SynchronizeDirectories | Synchronizes local directory with remote directory. |
Events
| Name | Description |
|---|---|
| Failed | Occurs on error during any operation. |
| FileTransferred | Occurs when file is transfered. |
| OutputDataReceived | Occurs on output from WinSCP console session. |
Remarks
To use the class:
- Create an instance of
SessionOptionsand fill in all needed information to connect and authenticate the session automatically; - Create an instance of
Sessionclass; - Usually all properties of
Sessioncan be left with their default values; - Assign event handlers, if continuous monitoring of operation is required;
- Call
Openmethod passing instance ofSessionOptions; - Use any file manipulation methods you need, such as
GetFiles,PutFiles,SynchronizeDirectories.
Advertisement
The class is not thread safe. Though you can use several instances of the class in paralel, even from different threads.
Capturing Results of Operations
There are two classes of operations, hence two classes of methods; atomic operations, such as Open, ListDirectory, ExecuteCommand, 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 (refered to as “failure” below).
Methods for batch operations returns an instance of descendant of OperationResultBase class (such as OperationResult<T> or SynchronizationResult). Such result class stores list of operations performed (e.g. OperationResult<T>.Operations or SynchronizationResult.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 occured:
// Throw, if upload fails session.PutFiles(localPath, remotePath).Check();
Also for all failures the Session.Failed event is raised.