Differences
This shows you the differences between the selected revisions of the page.
| 2014-11-30 | 2014-11-30 | ||
| no summary (154.122.119.149) (hidden) | Restored revision 1416844479. Undoing revision 1417364783. (martin) (hidden) | ||
| Line 1: | Line 1: | ||
| - | ====== Automate file transfers (or synchronization) to FTP server or SFTP server ======~~AD~~//This guide contains simplified description of automating operations on FTP/SFTP server with WinSCP. You may want to see [[scripting|detailed documentation]] of the scripting functionality instead//.WinSCP offers [[scripting]] interface that you can use to automate many operations that it supports, including file transfers, synchronization and other operations.//There is also [[library|WinSCP .NET assembly]] build on top of the scripting interface. If you plan to call WinSCP from your .NET code, or if your task requires conditional processing, loops or other control structures, you should better use the .NET assembly. This guide focuses on simple automation tasks using scripting interface only.// | + | ====== Automate file transfers (or synchronization) to FTP server or SFTP server ====== |
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | //This guide contains simplified description of automating operations on FTP/SFTP server with WinSCP. You may want to see [[scripting|detailed documentation]] of the scripting functionality instead//. | ||
| + | |||
| + | WinSCP offers [[scripting]] interface that you can use to automate many operations that it supports, including file transfers, synchronization and other operations. | ||
| + | |||
| + | //There is also [[library|WinSCP .NET assembly]] build on top of the scripting interface. If you plan to call WinSCP from your .NET code, or if your task requires conditional processing, loops or other control structures, you should better use the .NET assembly. This guide focuses on simple automation tasks using scripting interface only.// | ||
| ===== Before Starting ===== | ===== Before Starting ===== | ||
| Line 6: | Line 14: | ||
| * [[guide_install|Have WinSCP installed]]; | * [[guide_install|Have WinSCP installed]]; | ||
| * [[guide_connect|Know how to connect to your FTP/SFTP account]]. | * [[guide_connect|Know how to connect to your FTP/SFTP account]]. | ||
| - | secure http | ||
| - | ===== Commands =====To automate operation, you need to find out [[scripting#commands|commands]] necessary to implement it. For simple operations you need at least to: * Set script to be performed non-interactively. For most automation scripts, you should use commands ''[[scriptcommand_option|option batch abort]]'' and ''[[scriptcommand_option|option confirm off]]''. * Open session using ''[[scriptcommand_open|open]]'' command. * Perform operation. For [[task_upload|uploads]] use ''[[scriptcommand_put|put]]'' command. For [[task_download|downloads]] use ''[[scriptcommand_get|get]]'' command. For [[task_synchronize_full|synchronization]] use ''[[scriptcommand_synchronize|synchronize]]'' command. For other operations, see [[scripting#commands|supported commands]]. * Exit scripting using ''[[scriptcommand_exit|exit]]'' command.For example a typical script to upload a file is:<code winscp># Automatically abort script on errorsoption batch abort# Disable overwrite confirmations that conflict with the previousoption confirm off# Connect to SFTP server using a passwordopen sftp://user:password@example.com/ -hostkey="ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"# Upload fileput d:\examplefile.txt /home/user# Disconnectclose</code>===== Script file =====Assemble the commands into a script file. You can name the script file as you like. See [[scripting#example|simple example]] and some [[scripts|useful scripts]].Use the ''/script'' [[commandline|command line]] option to pass the script to the WinSCP [[executables|executable]]. You can embed the complete command line into a Windows batch file (''.bat''), like as follows:<code batch>@echo offwinscp.com /script=myscript.txt</code>~~AD~~===== [[using]] Using script =====Now to make using script easier/automatic you can: * Make shortcut to it on desktop to ease execution. Either make shortcut to batch file (''.bat'') or enter full command line to shortcut itself.((Note that it is not possible to use ''winscp.com'' (''.com'' files in general) directly from a shortcut. Call ''winscp.com'' from a batch file or use ''winscp.exe'' with ''/console'' command-line parameter.)) * If the wrapping batch file takes filename as command line parameter (see [[#modifying_the_script_automatically|below]]) you can: * Make shortcut to it on desktop and use it by dropping files on the icon. Windows automatically run the batch file and passes path to dropped file as command-line parameter. * In a similar way you can put the shortcut to the batch file into Explorer’s ‘Send To’ context menu (''C:\Users\username\AppData\Roaming\Microsoft\Windows\SendTo'' in Windows Vista and newer). &winpath &winvista * [[guide_schedule|Schedule automatic execution]].===== Notes =====When connecting to SSH host, you will need to [[scripting#hostkey|accept its host key]].When connecting to FTPS or WebDAVS host with [[tls#certificate|certificate]] signed by untrusted authority you will need to verify the certificate.===== [[parametrized]] Modifying the script automatically =====You may want to modify the script automatically. For example you may want to operate it with different file each time.//For tasks involving more complex modifications, conditional processing, loops or other control structures, you should better use the [[library|WinSCP .NET assembly]].//For simple modifications, you can pass the variable parts of the script from command line:<code winscp>option batch abortoption confirm offopen mysessionput %1%exit</code>Execute the above script using syntax:<code batch>winscp.com /script=script.tmp /parameter c:\myfile.txt</code>You can also use environment variables in the script.Alternatively, you can generate new script file each time. To automate that, make a wrapper script file. For simple tasks you can use built-in Windows scripting functionality from batch file (''.bat''). For complex tasks, you will need to use some scripting language, such JScript or VBScript from Windows script host or PHP or Perl.Following example shows batch file that takes filename on command line and generates WinSCP script file to upload that file to remote server:<code batch>rem Generate temporary script to upload %1echo option batch abort > script.tmpecho option confirm off >> script.tmpecho open mysession >> script.tmpecho put %1 >> script.tmpecho exit >> script.tmprem Execute scriptwinscp.com /script=script.tmprem Delete temporary scriptdel script.tmp</code>Now you can run the batch file like (supposing you have saved it to file ''upload.bat''):<code batch>upload.bat c:\myfile.txt</code>See more hints on [[#using|using parametrized batch file]].//See [[guide_automation_advanced|guide to advanced scripting]] for examples of script generation using more powerful languages.//~~AD~~===== [[results]] Checking script results =====To check results of the script you can: * Check exit code of WinSCP (exit code is the only relevant and reliable way to check if script completed successfully). See example below and [[faq_script_result|FAQ]]. * Save and inspect log file. [[logging_xml|XML log format]] is recommended. Use [[commandline|command-line]] parameter ''/xmllog''. * Save and inspect output of the script. Use [[executables|output redirection]].Once you find out what was the result of the script, you can perform any action you like. E.g. after evaluating exit code of WinSCP, you can send a "success" or "error" email. For that use any command-line email client you like, e.g. [[http://glob.com.au/sendmail/|sendmail]]((When installing sendmail, you can ignore all references to ''/usr/lib/'' (or ''c:\usr\lib'') directories in its installation instructions, as you will be running ''sendmail.exe'' directly from a Windows batch file. Just place sendmail files to any convenient location, e.g. along with WinSCP.)).You should also make the batch file indicate a result in its exit code, particularly if it is called from some parent system (for example [[guide_ssis|SSIS]]).See an example batch file:<code batch>winscp.com /script=example.txtif %ERRORLEVEL% neq 0 goto errorecho Successsendmail.exe -t < success_mail.txtexit 0:errorecho Error!sendmail.exe -t < error_mail.txtexit 1</code>Where for example content of ''success_mail.txt'' may be:<code>From: script@example.comTo: me@example.comSubject: SuccessThe files were uploaded successfully.</code>//If you require checking results of each command individually, you should better use the [[library|WinSCP .NET assembly]]. Alternatively, see [[guide_automation_advanced|guide to advanced scripting]] for examples of checking script results (including XML log parsing) using more powerful languages and guide to [[guide_interpreting_xml_log|interpreting XML log for advanced scripting]] using C# language.//===== Example =====See [[scripting#example|example]] in scripting documentation.===== Further reading ===== * [[troubleshooting|Troubleshooting]]; * [[scripting|Scripting]] documentation; * Guide to [[guide_automation_advanced|advanced scripting]]; * [[library|WinSCP .NET assembly]]; * [[commandline|Command-line]] parameters; * WinSCP [[executables|executables]]; * [[faq#scripting_automation|FAQ about scripting]]; * Example [[scripts|scripts]]; * [[guide_schedule|Schedule file transfers or synchronization]]. | + | ===== Commands ===== |
| + | To automate operation, you need to find out [[scripting#commands|commands]] necessary to implement it. For simple operations you need at least to: | ||
| + | * Set script to be performed non-interactively. For most automation scripts, you should use commands ''[[scriptcommand_option|option batch abort]]'' and ''[[scriptcommand_option|option confirm off]]''. | ||
| + | * Open session using ''[[scriptcommand_open|open]]'' command. | ||
| + | * Perform operation. For [[task_upload|uploads]] use ''[[scriptcommand_put|put]]'' command. For [[task_download|downloads]] use ''[[scriptcommand_get|get]]'' command. For [[task_synchronize_full|synchronization]] use ''[[scriptcommand_synchronize|synchronize]]'' command. For other operations, see [[scripting#commands|supported commands]]. | ||
| + | * Exit scripting using ''[[scriptcommand_exit|exit]]'' command. | ||
| + | |||
| + | For example a typical script to upload a file is: | ||
| + | |||
| + | <code winscp> | ||
| + | # Automatically abort script on errors | ||
| + | option batch abort | ||
| + | # Disable overwrite confirmations that conflict with the previous | ||
| + | option confirm off | ||
| + | # Connect to SFTP server using a password | ||
| + | open sftp://user:password@example.com/ -hostkey="ssh-rsa 2048 xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" | ||
| + | # Upload file | ||
| + | put d:\examplefile.txt /home/user | ||
| + | # Disconnect | ||
| + | close | ||
| + | </code> | ||
| + | |||
| + | ===== Script file ===== | ||
| + | Assemble the commands into a script file. You can name the script file as you like. See [[scripting#example|simple example]] and some [[scripts|useful scripts]]. | ||
| + | |||
| + | Use the ''/script'' [[commandline|command line]] option to pass the script to the WinSCP [[executables|executable]]. You can embed the complete command line into a Windows batch file (''.bat''), like as follows: | ||
| + | <code batch> | ||
| + | @echo off | ||
| + | winscp.com /script=myscript.txt | ||
| + | </code> | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | ===== [[using]] Using script ===== | ||
| + | Now to make using script easier/automatic you can: | ||
| + | * Make shortcut to it on desktop to ease execution. Either make shortcut to batch file (''.bat'') or enter full command line to shortcut itself.((Note that it is not possible to use ''winscp.com'' (''.com'' files in general) directly from a shortcut. Call ''winscp.com'' from a batch file or use ''winscp.exe'' with ''/console'' command-line parameter.)) | ||
| + | * If the wrapping batch file takes filename as command line parameter (see [[#modifying_the_script_automatically|below]]) you can: | ||
| + | * Make shortcut to it on desktop and use it by dropping files on the icon. Windows automatically run the batch file and passes path to dropped file as command-line parameter. | ||
| + | * In a similar way you can put the shortcut to the batch file into Explorer’s ‘Send To’ context menu (''C:\Users\username\AppData\Roaming\Microsoft\Windows\SendTo'' in Windows Vista and newer). &winpath &winvista | ||
| + | * [[guide_schedule|Schedule automatic execution]]. | ||
| + | |||
| + | ===== Notes ===== | ||
| + | When connecting to SSH host, you will need to [[scripting#hostkey|accept its host key]]. | ||
| + | |||
| + | When connecting to FTPS or WebDAVS host with [[tls#certificate|certificate]] signed by untrusted authority you will need to verify the certificate. | ||
| + | |||
| + | ===== [[parametrized]] Modifying the script automatically ===== | ||
| + | You may want to modify the script automatically. For example you may want to operate it with different file each time. | ||
| + | |||
| + | //For tasks involving more complex modifications, conditional processing, loops or other control structures, you should better use the [[library|WinSCP .NET assembly]].// | ||
| + | |||
| + | For simple modifications, you can pass the variable parts of the script from command line: | ||
| + | |||
| + | <code winscp> | ||
| + | option batch abort | ||
| + | option confirm off | ||
| + | open mysession | ||
| + | put %1% | ||
| + | exit | ||
| + | </code> | ||
| + | |||
| + | Execute the above script using syntax: | ||
| + | |||
| + | <code batch> | ||
| + | winscp.com /script=script.tmp /parameter c:\myfile.txt | ||
| + | </code> | ||
| + | |||
| + | You can also use environment variables in the script. | ||
| + | |||
| + | Alternatively, you can generate new script file each time. To automate that, make a wrapper script file. For simple tasks you can use built-in Windows scripting functionality from batch file (''.bat''). For complex tasks, you will need to use some scripting language, such JScript or VBScript from Windows script host or PHP or Perl. | ||
| + | |||
| + | Following example shows batch file that takes filename on command line and generates WinSCP script file to upload that file to remote server: | ||
| + | |||
| + | <code batch> | ||
| + | rem Generate temporary script to upload %1 | ||
| + | echo option batch abort > script.tmp | ||
| + | echo option confirm off >> script.tmp | ||
| + | echo open mysession >> script.tmp | ||
| + | echo put %1 >> script.tmp | ||
| + | echo exit >> script.tmp | ||
| + | |||
| + | rem Execute script | ||
| + | winscp.com /script=script.tmp | ||
| + | |||
| + | rem Delete temporary script | ||
| + | del script.tmp | ||
| + | </code> | ||
| + | |||
| + | Now you can run the batch file like (supposing you have saved it to file ''upload.bat''): | ||
| + | |||
| + | <code batch> | ||
| + | upload.bat c:\myfile.txt | ||
| + | </code> | ||
| + | |||
| + | See more hints on [[#using|using parametrized batch file]]. | ||
| + | |||
| + | //See [[guide_automation_advanced|guide to advanced scripting]] for examples of script generation using more powerful languages.// | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | ===== [[results]] Checking script results ===== | ||
| + | To check results of the script you can: | ||
| + | * Check exit code of WinSCP (exit code is the only relevant and reliable way to check if script completed successfully). See example below and [[faq_script_result|FAQ]]. | ||
| + | * Save and inspect log file. [[logging_xml|XML log format]] is recommended. Use [[commandline|command-line]] parameter ''/xmllog''. | ||
| + | * Save and inspect output of the script. Use [[executables|output redirection]]. | ||
| + | |||
| + | Once you find out what was the result of the script, you can perform any action you like. E.g. after evaluating exit code of WinSCP, you can send a "success" or "error" email. For that use any command-line email client you like, e.g. [[http://glob.com.au/sendmail/|sendmail]]((When installing sendmail, you can ignore all references to ''/usr/lib/'' (or ''c:\usr\lib'') directories in its installation instructions, as you will be running ''sendmail.exe'' directly from a Windows batch file. Just place sendmail files to any convenient location, e.g. along with WinSCP.)). | ||
| + | |||
| + | You should also make the batch file indicate a result in its exit code, particularly if it is called from some parent system (for example [[guide_ssis|SSIS]]). | ||
| + | |||
| + | See an example batch file: | ||
| + | |||
| + | <code batch> | ||
| + | winscp.com /script=example.txt | ||
| + | if %ERRORLEVEL% neq 0 goto error | ||
| + | |||
| + | echo Success | ||
| + | sendmail.exe -t < success_mail.txt | ||
| + | exit 0 | ||
| + | |||
| + | :error | ||
| + | echo Error! | ||
| + | sendmail.exe -t < error_mail.txt | ||
| + | exit 1 | ||
| + | </code> | ||
| + | |||
| + | Where for example content of ''success_mail.txt'' may be: | ||
| + | <code> | ||
| + | From: script@example.com | ||
| + | To: me@example.com | ||
| + | Subject: Success | ||
| + | |||
| + | The files were uploaded successfully. | ||
| + | </code> | ||
| + | |||
| + | //If you require checking results of each command individually, you should better use the [[library|WinSCP .NET assembly]]. Alternatively, see [[guide_automation_advanced|guide to advanced scripting]] for examples of checking script results (including XML log parsing) using more powerful languages and guide to [[guide_interpreting_xml_log|interpreting XML log for advanced scripting]] using C# language.// | ||
| + | |||
| + | ===== Example ===== | ||
| + | See [[scripting#example|example]] in scripting documentation. | ||
| + | |||
| + | ===== Further reading ===== | ||
| + | * [[troubleshooting|Troubleshooting]]; | ||
| + | * [[scripting|Scripting]] documentation; | ||
| + | * Guide to [[guide_automation_advanced|advanced scripting]]; | ||
| + | * [[library|WinSCP .NET assembly]]; | ||
| + | * [[commandline|Command-line]] parameters; | ||
| + | * WinSCP [[executables|executables]]; | ||
| + | * [[faq#scripting_automation|FAQ about scripting]]; | ||
| + | * Example [[scripts|scripts]]; | ||
| + | * [[guide_schedule|Schedule file transfers or synchronization]]. | ||