Differences
This shows you the differences between the selected revisions of the page.
| library_session_putfiles 2015-08-04 | library_session_putfiles 2022-08-12 (current) | ||
| Line 1: | Line 1: | ||
| ====== Session.PutFiles Method ====== | ====== Session.PutFiles Method ====== | ||
| [[task_upload|Uploads]] one or more files from local directory to remote directory. | [[task_upload|Uploads]] one or more files from local directory to remote directory. | ||
| + | |||
| + | You can have WinSCP [[guide_automation#generating|generate a code template]] for ''Session.PutFiles'' for you. | ||
| + | |||
| + | The method is quite powerful, but due to a wide range of it uses, its syntax can be cumbersome initially. For specific tasks, consider using convenient alternatives: [[library_session_putfilestodirectory|''Session.PutFilesToDirectory'']] and [[library_session_putfiletodirectory|''Session.PutFileToDirectory'']]. | ||
| ===== Syntax ===== | ===== Syntax ===== | ||
| Line 13: | Line 17: | ||
| <code vbnet *> | <code vbnet *> | ||
| - | Public Function PutFiles( _ | + | Public Function PutFiles( |
| - | ByVal localPath As String, _ | + | localPath As String, |
| - | ByVal remotePath As String, _ | + | remotePath As String, |
| - | ByVal Optional remove As Boolean = False, _ | + | Optional remove As Boolean = False, |
| - | ByVal Optional options As TransferOptions = Null _ | + | Optional options As TransferOptions = Nothing |
| ) As TransferOperationResult | ) As TransferOperationResult | ||
| </code> | </code> | ||
| - | ==== Parameters ==== | + | ==== [[parameters]] Parameters ==== |
| ^ Name ^ Description ^ | ^ Name ^ Description ^ | ||
| - | | string localPath | Full path to local file or directory to upload.((Contrary to ''[[library_session_getfiles|Session.GetFiles]]'', when the path ends with a backslash, the backslash is ignored. The local directory is uploaded as a subdirectory of the destination directory.)) Filename in the path can be replaced with Windows wildcard ((The Windows wildcard supports ''*'' and ''?'' only. If you want to use a full syntax of [[file_mask|file masks]], use a ''[[library_transferoptions|TransferOptions.FileMask]]''.)) to select multiple files. | | + | | string ==localPath== | Full path to local file or directory to upload. Filename in the path can be replaced with Windows wildcard ((The Windows wildcard supports ''*'' and ''?'' only. If you want to use a full syntax of [[file_mask|file masks]], use a ''[[library_transferoptions#filemask|TransferOptions.FileMask]]''.)) to select multiple files. To upload all files in a directory, use mask ''*''. | |
| - | | string remotePath | Full path to upload the file to. When uploading multiple files, the filename in the path should be replaced with [[operation_mask|operation mask]] or omitted (path ends with slash). | | + | | string ==remotePath== | Full path to upload the file to. When uploading multiple files, the filename in the path should be replaced with [[operation_mask|operation mask]] or omitted (path ends with slash). | |
| - | | bool remove | When set to ''true'', deletes source local file(s) after transfer. Defaults to ''false''. | | + | | bool ==remove== | When set to ''true'', deletes source local file(s) after a successful transfer. Defaults to ''false''. | |
| - | | [[library_transferoptions|TransferOptions]] options | Transfer options. Defaults to ''null'', what is equivalent to ''new TransferOptions()''. | | + | | [[library_transferoptions|TransferOptions]] ==options== | Transfer options. Defaults to ''null'', what is equivalent to ''new TransferOptions()''. | |
| ==== Return Value ==== | ==== Return Value ==== | ||
| ''[[library_transferoperationresult|TransferOperationResult]]''. See also [[library_session#results|Capturing results of operations]]. | ''[[library_transferoperationresult|TransferOperationResult]]''. See also [[library_session#results|Capturing results of operations]]. | ||
| - | ===== Exceptions ===== | + | ===== [[exceptions]] Exceptions ===== |
| ^ Exception ^ Condition ^ | ^ Exception ^ Condition ^ | ||
| | InvalidOperationException | Session is not opened. | | | InvalidOperationException | Session is not opened. | | ||
| | ArgumentException \\ ArgumentOutOfRangeException | Invalid combination of values of ''[[library_transferoptions|TransferOptions]]'' properties. | | | ArgumentException \\ ArgumentOutOfRangeException | Invalid combination of values of ''[[library_transferoptions|TransferOptions]]'' properties. | | ||
| | [[library_sessionlocalexception|SessionLocalException]] | Error communicating with ''[[executables#winscp.com|winscp.com]]''. \\ See the exception documentation for details. | | | [[library_sessionlocalexception|SessionLocalException]] | Error communicating with ''[[executables#winscp.com|winscp.com]]''. \\ See the exception documentation for details. | | ||
| + | | [[library_sessionremoteexception|SessionRemoteException]] | Session has failed. \\ Uploading of files has failed. \\ See the exception documentation for details. | | ||
| | TimeoutException | Timeout waiting for ''winscp.com'' to respond. | | | TimeoutException | Timeout waiting for ''winscp.com'' to respond. | | ||
| ===== Remarks ===== | ===== Remarks ===== | ||
| - | Event ''[[library_session_filetransferred|Session.FileTransferred]]'' is raised for every uploaded file. | + | Event ''[[library_session_filetransferred|Session.FileTransferred]]'' is raised for every uploaded file. Also raises [[library_session_filetransferprogress|''Session.FileTransferProgress'']] throughout the transfer. |
| - | The upload aborts on the first error. See example on [[library_example_recursive_download_custom_error_handling|implementing recursive directory tree download with custom error handling]], uploads can be implemented similarly too. | + | The upload aborts on the first error. See the example on [[library_example_recursive_download_custom_error_handling|implementing recursive directory tree download with custom error handling]]. Uploads can be implemented similarly too, see an example of [[library_example_moves_files_keeping_directory_structure|implementing recursive directory tree upload]]. |
| ===== Example ===== | ===== Example ===== | ||
| Line 48: | Line 53: | ||
| ==== Real-Life Examples ==== | ==== Real-Life Examples ==== | ||
| - | * [[script_local_move_after_successful_upload|Moving local files to different location after successful upload]]; | + | * [[script_local_move_after_successful_upload|*]]; |
| - | * [[script_locking_files_while_uploading|Locking files while uploading / Upload to temporary file name]]. | + | * [[script_locking_files_while_uploading|*]]; |
| + | * [[library_example_moves_files_keeping_directory_structure|*]]. | ||