Differences
This shows you the differences between the selected revisions of the page.
| library_session 2012-09-05 | library_session 2023-09-08 (current) | ||
| Line 2: | Line 2: | ||
| This is the main interface class of the [[library|WinSCP assembly]]. | This is the main interface class of the [[library|WinSCP assembly]]. | ||
| - | It represents a session and provides methods for manipulating remote files over SFTP, SCP or FTP session. | + | It represents a session and provides methods for manipulating remote files over SFTP, FTP, WebDAV, S3 or SCP session. |
| ~~AD~~ | ~~AD~~ | ||
| - | &beta_feature | + | ===== [[syntax]] Syntax ===== |
| - | + | ||
| - | ===== Syntax ===== | + | |
| Namespace: ''WinSCP'' | Namespace: ''WinSCP'' | ||
| Line 24: | Line 22: | ||
| | Session() | Default constructor. | | | Session() | Default constructor. | | ||
| - | ===== Properties ===== | + | ===== [[properties]] Properties ===== |
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| - | | string AdditionalExecutableArguments | Additional command-line arguments to be passed to ''[[executables#winscp.com|winscp.com]]''. In general, this should be left with default ''null''. | | + | | string ==AdditionalExecutableArguments== | Additional command-line arguments to be passed to ''[[executables#winscp.com|winscp.com]]''. In general, this should be left with default ''null''. | |
| - | | string DebugLogPath | Path to store assembly debug log to. Default ''null'' means, no debug log file is created. See also ''SessionLogPath''. | | + | | int ==DebugLogLevel== | Logging level of session and debug logs. The default value is ''0''. The value can be in range ''-1''...''2'' (for session log file that means //Reduced//, //Normal//, //Debug 1// and //Debug 2// logging levels respectively). | |
| - | | bool DefaultConfiguration | Should WinSCP be forced with the default [[config|configuration]]? ''true'' by default. Useful to isolate the console session run from any configuration stored on this machine. Set to ''false'' only in an exceptional scenarios. | | + | | string ==DebugLogPath== | Path to store assembly debug log to. Default ''null'' means, no debug log file is created. See also ''[[#sessionlogpath|SessionLogPath]]''. The property has to be set before calling ''Open''. | |
| - | | bool DisableVersionCheck | Disables test that WinSCP [[executables|executables]] have the same product version as this assembly.((Note, even if you set this property, you need to use the assembly with compatible WinSCP executable only. Otherwise the behaviour is unpredictable. In general, it is not recommended to use this. It neither case you will be able to use the assembly with WinSCP 5.0.4 or older.)) | | + | | <del>bool ==DefaultConfiguration==</del> | Deprecated. Do not use. Use ''[[library_session_addrawconfiguration|Session.AddRawConfiguration]]'' instead. | |
| - | | string ExecutablePath | Path to ''[[executables#winscp.exe|winscp.exe]]''. The default is ''null'', meaning that ''winscp.exe'' is looked for in the same directory as this assembly or in an installation folder. | | + | | bool ==DisableVersionCheck== | Disables test that WinSCP [[executables|executables]] have the same product version as this assembly.((Note, even if you set this property, you need to use the assembly with compatible WinSCP executable only. Otherwise the behavior is unpredictable. In general, it is not recommended to use this. In neither case will you be able to use the assembly with WinSCP 5.0.4 or older.)) The property has to be set before calling ''Open''. \\ One of few legitimate uses of the property is when [[library_install#merge|merging WinSCP .NET assembly into another 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 ==ExecutablePath== | Path to ''[[executables#winscp.exe|winscp.exe]]''. If not set, ''winscp.exe'' is looked for in the same directory as this assembly or in an installation folder (and the property returns the found path). The property has to be set before calling ''Open''. | |
| - | | string SessionLogPath | Path to store [[logging|session log file]] to. Default ''null'' means, no session log file is created. See also ''DebugLogPath''. | | + | | string ==ExecutableProcessUserName== | If the .NET process is running in an impersonated environment, you need to provide credentials of the impersonated account, so that the ''winscp.exe'' process can be started with the same privileges. \\ Not supported in .NET Standard. | |
| - | | bool Opened | Is session opened yet? ''true'', when ''Open'' was successfully called already. Read-only. | | + | | SecureString ==ExecutableProcessPassword== | See ''[[#executableprocessusername|ExecutableProcessUserName]]''. | |
| - | | [[library_doc_collections|StringCollection]] Output | Output of WinSCP console session. See also ''[[library_session_outputdatareceived|OutputDataReceived]]'' event. Read-only. | | + | | string ==HomePath== | Path to a remote home directory. The property can be read only after calling ''Open''. | |
| - | | TimeSpan ReconnectTime | Sets time limit in seconds to try reconnecting broken sessions. Default is unlimited. | | + | | <del>string ==IniFilePath==</del> | Deprecated. Do not use. Use ''[[library_session_addrawconfiguration|Session.AddRawConfiguration]]'' instead. | |
| - | | TimeSpan Timeout | Maximal interval between two consecutive outputs from WinSCP console session, before TimeoutException is thrown. The default is one minute. | | + | | string ==SessionLogPath== | Path to store [[logging|session log file]] to. Default ''null'' means, no session log file is created. See also ''[[#debuglogpath|DebugLogPath]]''. The property has to be set before calling ''Open''. | |
| + | | bool ==Opened== | Is session opened yet? ''true'', when ''Open'' was successfully called already. Read-only. | | ||
| + | | [[library_doc_collections|StringCollection]] ==Output== | Output of WinSCP console session. See also ''[[library_session_outputdatareceived|OutputDataReceived]]'' event. Read-only. | | ||
| + | | TimeSpan ==ReconnectTime== | Sets time limit in seconds to try reconnecting broken sessions. Default is 120 seconds. Use ''TimeSpan.MaxValue'' to remove any limit. The property has to be set before calling ''Open''. | | ||
| + | | int ==ReconnectTimeInMilliseconds== | Alternative to ''[[#reconnecttime|ReconnectTime]]''. Particularly useful for COM hosts, that cannot use ''TimeSpan'', such as Visual Basic. | | ||
| + | | TimeSpan ==Timeout== | Maximal interval between two consecutive outputs from WinSCP console session, before ''TimeoutException'' is thrown. The default is one minute. It's not recommended to change the value. For session/connection timeout, see ''[[library_sessionoptions#timeout|SessionOptions.Timeout]]''. When ''SessionOptions.Timeout'' is longer, its value is used instead. | | ||
| + | | string XmlLogPath | Path to XML log file. If not set explicitly, temporary path is generated on ''Open'' call. The property has to be changed afterwards. | | ||
| + | | bool XmlLogPreserve | When set to ''true'', the XML log is preserved after the session closes. | | ||
| - | ===== Methods ===== | + | ===== [[methods]] Methods ===== |
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| | [[library_session_abort|Abort]] | Forcefully aborts session. | | | [[library_session_abort|Abort]] | Forcefully aborts session. | | ||
| + | | [[library_session_addrawconfiguration|AddRawConfiguration]] | Allows setting any configuration settings using raw format as in an INI file. | | ||
| + | | [[library_session_calculatefilechecksum|CalculateFileChecksum]] | Calculates a checksum of a remote file. | | ||
| + | | [[library_session_close|Close]] | Closes session. | | ||
| + | | <del>[[library_session_combinepaths|CombinePaths]]</del> | Deprecated. Combines strings into a remote path. | | ||
| + | | [[library_session_comparedirectories|CompareDirectories]] | Compares directories, the same way ''Session.SynchronizeDirectories'' method does, but returns differences only. | | ||
| | [[library_session_createdirectory|CreateDirectory]] | Creates remote directory. | | | [[library_session_createdirectory|CreateDirectory]] | Creates remote directory. | | ||
| - | | [[library_session_dispose|Dispose]] | Closes session, terminates underlying WinSCP process. | | + | | [[library_session_dispose|Dispose]] | Closes session and disposes object. | |
| - | | [[library_session_escapefilemask|EscapeFileMask]] | Converts special characters in remote file name to make it unambiguous file mask/wildcard. | | + | | [[library_session_duplicatefile|DuplicateFile]] | Duplicates remote file to another remote directory. | |
| + | | <del>[[library_session_escapefilemask|EscapeFileMask]]</del> | Deprecated. Converts special characters in file path to make it unambiguous file mask/wildcard. | | ||
| + | | [[library_session_enumerateremotefiles|EnumerateRemoteFiles]] | Recursively enumerates remote files. | | ||
| | [[library_session_executecommand|ExecuteCommand]] | Executes command on the remote server. | | | [[library_session_executecommand|ExecuteCommand]] | Executes command on the remote server. | | ||
| | [[library_session_fileexists|FileExists]] | Checks for existence of remote file. | | | [[library_session_fileexists|FileExists]] | Checks for existence of remote file. | | ||
| | [[library_session_getfileinfo|GetFileInfo]] | Retrieves information about remote file. | | | [[library_session_getfileinfo|GetFileInfo]] | Retrieves information about remote file. | | ||
| - | | [[library_session_getfiles|GetFiles]] | Downloads files. | | + | | [[library_session_getfile|GetFile]] | Streams remote file data. | |
| + | | [[library_session_getfiles|GetFiles]] | Downloads files (optionally under a different name). | | ||
| + | | [[library_session_getfilestodirectory|GetFilesToDirectory]] | Downloads files. | | ||
| + | | [[library_session_getfiletodirectory|GetFileToDirectory]] | Downloads one specific file. | | ||
| | [[library_session_listdirectory|ListDirectory]] | Lists remote directory. | | | [[library_session_listdirectory|ListDirectory]] | Lists remote directory. | | ||
| | [[library_session_movefile|MoveFile]] | Moves remote file to another remote directory and/or renames remote file. | | | [[library_session_movefile|MoveFile]] | Moves remote file to another remote directory and/or renames remote file. | | ||
| | [[library_session_open|Open]] | Opens the session. | | | [[library_session_open|Open]] | Opens the session. | | ||
| - | | [[library_session_putfiles|PutFiles]] | Uploads files. | | + | | [[library_session_putfile|PutFile]] | Streams data to a remote file. | |
| + | | [[library_session_putfiles|PutFiles]] | Uploads files (optionally under a different name). | | ||
| + | | [[library_session_putfilestodirectory|PutFilesToDirectory]] | Uploads files. | | ||
| + | | [[library_session_putfiletodirectory|PutFileToDirectory]] | Uploads one specific file. | | ||
| + | | [[library_session_removefile|RemoveFile]] | Removes one specific remote file. | | ||
| | [[library_session_removefiles|RemoveFiles]] | Removes remote files. | | | [[library_session_removefiles|RemoveFiles]] | Removes remote files. | | ||
| + | | [[library_session_scanfingerprint|ScanFingerprint]] | Scans a fingerprint of SSH server public key or FTPS/WebDAVS TLS certificate. | | ||
| | [[library_session_synchronizedirectories|SynchronizeDirectories]] | Synchronizes local directory with remote directory. | | | [[library_session_synchronizedirectories|SynchronizeDirectories]] | Synchronizes local directory with remote directory. | | ||
| + | | <del>[[library_session_translatelocalpathtoremote|TranslateLocalPathToRemote]]</del> | Deprecated. Generates a remote path equivalent of a local path, given root paths. | | ||
| + | | <del>[[library_session_translateremotepathtolocal|TranslateRemotePathToLocal]]</del> | Deprecated. Generates a local path equivalent of a remote path, given root paths. | | ||
| + | | [[library_session_trygetfileinfo|TryGetFileInfo]] | Retrieves information about remote file. | | ||
| + | |||
| - | ===== Events ===== | + | ===== [[events]] Events ===== |
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| | [[library_session_failed|Failed]] | Occurs on error during any operation. | | | [[library_session_failed|Failed]] | Occurs on error during any operation. | | ||
| - | | [[library_session_filetransferred|FileTransferred]] | Occurs when file is transfered. | | + | | [[library_session_filetransferprogress|FileTransferProgress]] | Occurs regularly during file transfer to report transfer progress. | |
| + | | [[library_session_filetransferred|FileTransferred]] | Occurs when file is transferred. | | ||
| | [[library_session_outputdatareceived|OutputDataReceived]] | Occurs on output from WinSCP console session. | | | [[library_session_outputdatareceived|OutputDataReceived]] | Occurs on output from WinSCP console session. | | ||
| + | | [[library_session_queryreceived|QueryReceived]] | Occurs when a decision is needed (i.e. typically on any non-fatal error). | | ||
| - | ===== Remarks ===== | + | ===== [[remarks]] Remarks ===== |
| To use the class: | To use the class: | ||
| * Create an instance of ''[[library_sessionoptions|SessionOptions]]'' and fill in all needed information to connect and authenticate the session automatically; | * Create an instance of ''[[library_sessionoptions|SessionOptions]]'' and fill in all needed information to connect and authenticate the session automatically; | ||
| Line 70: | Line 96: | ||
| * Use any file manipulation methods you need, such as ''[[library_session_getfiles|GetFiles]]'', ''[[library_session_putfiles|PutFiles]]'', ''[[library_session_synchronizedirectories|SynchronizeDirectories]]''. | * Use any file manipulation methods you need, such as ''[[library_session_getfiles|GetFiles]]'', ''[[library_session_putfiles|PutFiles]]'', ''[[library_session_synchronizedirectories|SynchronizeDirectories]]''. | ||
| - | The class is locked against concurrent accesses from multiple threads. Though you can use several instances of the class in paralel, even from different threads. | + | 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. |
| ==== [[results]] Capturing Results of Operations ==== | ==== [[results]] Capturing Results of Operations ==== | ||
| - | There are two classes of operations, hence two classes of methods; atomic operations, such as ''[[library_session_open|Open]]'', ''[[library_session_open|ListDirectory]]'', ''[[library_session_executecommand|ExecuteCommand]]'', etc; and batch operations, such as ''[[library_session_getfiles|GetFiles]]'', ''[[library_session_putfiles|PutFiles]]'', ''[[library_session_synchronizedirectories|SynchronizeDirectories]]'', etc. | + | There are two classes of operations, hence two classes of methods; atomic operations, such as ''[[library_session_open|Open]]'', ''[[library_session_listdirectory|ListDirectory]]'', etc; and batch operations, such as ''[[library_session_getfiles|GetFiles]]'', ''[[library_session_putfiles|PutFiles]]'', ''[[library_session_synchronizedirectories|SynchronizeDirectories]]'', etc. |
| Methods from both classes throw ''[[library_sessionlocalexception|SessionLocalException]]'' on error in communication with WinSCP console session. | Methods from both classes throw ''[[library_sessionlocalexception|SessionLocalException]]'' on error in communication with WinSCP console session. | ||
| - | Methods for atomic operations throw ''[[library_sessionremoteexception|SessionRemoteException]]'' on error originating from WinSCP console session (refered to as "failure" below). | + | Methods for atomic operations throw ''[[library_sessionremoteexception|SessionRemoteException]]'' on error originating from WinSCP console session (referred to as "failure" below). |
| - | Methods for batch operations returns an instance of descendant of ''[[library_operationresultbase|OperationResultBase]]'' class (such as ''[[library_transferoperationresult|TransferOperationResult]]'' or ''[[library_synchronizationresult|SynchronizationResult]]''). Such result class stores list of operations performed (e.g. ''TransferOperationResult.Uploads''), and list of failures (''OperationResultBase.Failures''). | + | Methods for batch operations return an instance of descendant of ''[[library_operationresultbase|OperationResultBase]]'' class (such as ''[[library_transferoperationresult|TransferOperationResult]]'' or ''[[library_synchronizationresult|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 ''[[library_transfereventargs|TransferEventArgs]].Error'') to one of the failures, if the failure can be explicitly associated with the operation. So often the same failure (represented by ''[[library_sessionremoteexception|SessionRemoteException]]'') will be referenced twice in the results. | Every structure representing operation performed may refer (e.g. in ''[[library_transfereventargs|TransferEventArgs]].Error'') to one of the failures, if the failure can be explicitly associated with the operation. So often the same failure (represented by ''[[library_sessionremoteexception|SessionRemoteException]]'') will be referenced twice in the results. | ||
| Line 85: | Line 111: | ||
| 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. | 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 ''[[library_operationresultbase|OperationResultBase]].Check'' to throw the first failure in the list, if any failure occured: | + | If you do not want to check the list of failures after every batch operation method call, you can use method ''[[library_operationresultbase#check|OperationResultBase.Check]]'' to throw the first failure in the list, if any failure occurred: |
| <code csharp> | <code csharp> | ||
| Line 93: | Line 119: | ||
| Also for all failures the ''[[library_session_failed|Session.Failed]]'' event is raised. | Also for all failures the ''[[library_session_failed|Session.Failed]]'' event is raised. | ||
| + | |||
| + | The batch operation though typically aborts on the first major failure. To customize error processing, handle ''[[library_session_queryreceived|Session.QueryReceived]]''. //For an example, see [[library_example_recursive_download_custom_error_handling|*]].// | ||
| ===== Example ===== | ===== Example ===== | ||
| - | See [[library#example|overall example for WinSCP .NET assembly]] or [[library_examples|any other example]]. | + | For simple handling of errors, see [[library#example|overall example for WinSCP .NET assembly]] or [[library_examples|any other example]]. |
| + | |||
| + | For example how to check and print errors, but continue, see real-life example [[library_example_recursive_search_text|*]]. | ||