Differences
This shows you the differences between the selected revisions of the page.
| library_session 2018-12-21 | library_session 2023-09-08 (current) | ||
| Line 6: | Line 6: | ||
| ~~AD~~ | ~~AD~~ | ||
| - | ===== Syntax ===== | + | ===== [[syntax]] Syntax ===== |
| Namespace: ''WinSCP'' | Namespace: ''WinSCP'' | ||
| Line 25: | Line 25: | ||
| ^ 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 ==DebugLogLevel== | Logging level of debug log to. The default value is ''0''. The maximal logging level is ''2''. | | + | | 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). | |
| | 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''. | | | 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''. | | ||
| | <del>bool ==DefaultConfiguration==</del> | Deprecated. Do not use. Use ''[[library_session_addrawconfiguration|Session.AddRawConfiguration]]'' instead. | | | <del>bool ==DefaultConfiguration==</del> | Deprecated. Do not use. Use ''[[library_session_addrawconfiguration|Session.AddRawConfiguration]]'' instead. | | ||
| - | | <del>bool ==DisableVersionCheck==</del> | Deprecated. 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''. | | + | | 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 ==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. The property has to be set before calling ''Open''. | | + | | 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 ==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. | | + | | 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. | |
| | SecureString ==ExecutableProcessPassword== | See ''[[#executableprocessusername|ExecutableProcessUserName]]''. | | | SecureString ==ExecutableProcessPassword== | See ''[[#executableprocessusername|ExecutableProcessUserName]]''. | | ||
| | string ==HomePath== | Path to a remote home directory. The property can be read only after calling ''Open''. | | | string ==HomePath== | Path to a remote home directory. The property can be read only after calling ''Open''. | | ||
| Line 40: | Line 40: | ||
| | int ==ReconnectTimeInMilliseconds== | Alternative to ''[[#reconnecttime|ReconnectTime]]''. Particularly useful for COM hosts, that cannot use ''TimeSpan'', such as Visual Basic. | | | 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. | | | 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]] Methods ===== | ||
| Line 57: | Line 59: | ||
| | [[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_scanfingerprint|ScanFingerprint]] | Scans a fingerprint of SSH server public key or FTPS/WebDAVS TLS certificate. | | ||
| Line 67: | Line 76: | ||
| | <del>[[library_session_translatelocalpathtoremote|TranslateLocalPathToRemote]]</del> | Deprecated. Generates a remote path equivalent of a local path, given root paths. | | | <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. | | | <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. | | ||
| Line 95: | Line 105: | ||
| Methods for atomic operations throw ''[[library_sessionremoteexception|SessionRemoteException]]'' on error originating from WinSCP console session (referred 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 110: | Line 120: | ||
| 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|Recursively download directory tree with custom error handling]].// | + | 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 ===== | ||
| For simple handling of errors, 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|Search recursively for text in remote directory / Grep files over SFTP/FTP protocol]]. | + | For example how to check and print errors, but continue, see real-life example [[library_example_recursive_search_text|*]]. |