Differences
This shows you the differences between the selected revisions of the page.
| guide_automation 2016-03-02 | guide_automation 2023-10-27 (current) | ||
| Line 3: | Line 3: | ||
| ~~AD~~ | ~~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//. | + | //This guide contains a 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. | 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.// | + | //There is also [[library|WinSCP .NET assembly]] built on top of the scripting interface. If you plan to call WinSCP from your .NET code or [[library_powershell|PowerShell]], 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 15: | Line 15: | ||
| * [[guide_connect|Know how to connect to your FTP/SFTP account]]. | * [[guide_connect|Know how to connect to your FTP/SFTP account]]. | ||
| - | ===== Commands ===== | + | ===== [[commands]] Commands ===== |
| To automate operation, you need to find out [[scripting#commands|commands]] necessary to implement it. For simple operations you need at least to: | To automate operation, you need to find out [[scripting#commands|commands]] necessary to implement it. For simple operations you need at least to: | ||
| * Open session using ''[[scriptcommand_open|open]]'' command. | * Open session using ''[[scriptcommand_open|open]]'' command. | ||
| Line 25: | Line 25: | ||
| <code winscp> | <code winscp> | ||
| # Connect to SFTP server using a password | # 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" | + | open sftp://user:password@example.com/ -hostkey="ssh-rsa 2048 xxxxxxxxxxx..." |
| # Upload file | # Upload file | ||
| put d:\examplefile.txt /home/user/ | put d:\examplefile.txt /home/user/ | ||
| Line 32: | Line 32: | ||
| </code> | </code> | ||
| - | ===== Script file ===== | + | ===== [[script_file]] 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]]. | 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#scripting|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: | + | Use the ''/script'' [[commandline#scripting|command line]] option to pass the script to the WinSCP [[executables|executable]]. Generally, you should also use [[commandline#configuration|''/ini=nul'' switch]] to [[scripting#configuration|isolate the script execution from GUI configuration]] and [[commandline#logging|''/log='' switch]] to enable [[logging|session logging]]. You can embed the complete command line into a Windows batch file (''.bat''), like as follows: |
| <code batch> | <code batch> | ||
| @echo off | @echo off | ||
| - | winscp.com /script=myscript.txt | + | winscp.com /ini=nul /log=myscript.log /script=myscript.txt |
| </code> | </code> | ||
| + | |||
| + | ~~AD~~ | ||
| + | |||
| + | ===== [[generating]] Generating script ===== | ||
| You can have WinSCP [[ui_generateurl|generate a script template for you]] or even a complete batch file. | You can have WinSCP [[ui_generateurl|generate a script template for you]] or even a complete batch file. | ||
| - | ~~AD~~ | + | To generate a script for a file transfer: |
| + | |||
| + | ··* [[guide_connect|Connect in the GUI]]. | ||
| + | * [[ui_file_panel#selecting_files|Select the files]] you want to transfer. | ||
| + | * Use one of the file transfer commands: //Upload//, //Download//, //Upload and Delete//, //Download and Delete//. | ||
| + | * On the [[ui_copy|transfer confirmation dialog]], setup transfer options (if you need any non-default settings). | ||
| + | * Use the //[[ui_copy#generating_code|Transfer Settings > Generate Code]]// command. | ||
| + | * The [[ui_generateurl#script|Generate transfer code]] dialog will appear with the generated script or code template. | ||
| ===== [[using]] Using script ===== | ===== [[using]] Using script ===== | ||
| Now to make using script easier/automatic you can: | 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 ''[[commandline#scripting|/console]]'' command-line parameter.)) | * 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 ''[[commandline#scripting|/console]]'' command-line parameter.)) | ||
| - | * If the wrapping batch file takes filename as command line parameter (see [[#modifying_the_script_automatically|below]]) you can: | + | * If the wrapping batch file takes filename as command line parameter (see [[#parametrized|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. | * 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 | * 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 | ||
| Line 54: | Line 65: | ||
| ===== Notes ===== | ===== Notes ===== | ||
| - | When connecting to SSH host, you will need to [[scripting#hostkey|accept its host key]]. | + | When connecting to the 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. | + | When connecting to FTPS or WebDAVS host with [[tls#certificate|certificate]] signed by an untrusted authority you will need to verify the certificate. |
| ===== [[parametrized]] Modifying the script automatically ===== | ===== [[parametrized]] Modifying the script automatically ===== | ||
| Line 74: | Line 85: | ||
| <code batch> | <code batch> | ||
| - | winscp.com /script=script.tmp /parameter // c:\myfile.txt | + | winscp.com /ini=nul /log=script.log /script=script.tmp /parameter // c:\myfile.txt |
| </code> | </code> | ||
| Line 84: | Line 95: | ||
| <code batch> | <code batch> | ||
| - | rem Generate temporary script to upload %1 | + | rem Generate a temporary script to upload %1 |
| - | echo open mysession >> script.tmp | + | ( |
| - | echo put %1 >> script.tmp | + | ··echo open mysession |
| - | echo exit >> script.tmp | + | · echo put %1 |
| + | echo <nohilite>exit</nohilite> | ||
| + | ) > script.tmp | ||
| - | rem Execute script | + | rem Execute the script |
| - | winscp.com /script=script.tmp | + | winscp.com /ini=nul /log=script.log /script=script.tmp |
| - | rem Delete temporary script | + | rem Delete the temporary script |
| del script.tmp | del script.tmp | ||
| </code> | </code> | ||
| Line 104: | Line 117: | ||
| See more hints on [[#using|using parametrized batch file]]. | 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.// | + | //See [[guide_automation_conditional#scripting|*]] for a more complex example; and [[guide_automation_advanced|*]] for examples of script generation using more powerful languages.// |
| ~~AD~~ | ~~AD~~ | ||
| Line 114: | Line 127: | ||
| * Save and inspect output of the script. Use [[executables|output redirection]]. | * 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.)). | + | Once you find out what was the result of the script, you can perform any action you like: print a message, [[script_email|send an email]], etc. |
| 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]]). | 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]]). | ||
| Line 121: | Line 134: | ||
| <code batch> | <code batch> | ||
| - | winscp.com /script=example.txt | + | winscp.com /ini=nul /log=example.log /script=example.txt |
| - | if %ERRORLEVEL% neq 0 goto error | + | if %ERRORLEVEL% equ 0 ( |
| - | + | ··echo Success | |
| - | echo Success | + | exit /b 0 |
| - | sendmail.exe -t < success_mail.txt | + | ) else ( |
| - | exit /b 0 | + | ··echo Error! |
| - | + | exit /b 1 | |
| - | :error | + | ) |
| - | echo Error! | + | |
| - | sendmail.exe -t < error_mail.txt | + | |
| - | exit /b 1 | + | |
| </code> | </code> | ||
| A similar error handling is used in [[ui_generateurl|the batch file template]] that WinSCP can generate for you. | A similar error handling is used in [[ui_generateurl|the batch file template]] that WinSCP can generate for you. | ||
| - | Where for example content of ''success_mail.txt'' may be: | + | //If you require checking results of each command individually, you should better use the [[library|WinSCP .NET assembly]]. Alternatively, see the guide [[guide_automation_advanced|*]] for examples of checking script results (including XML log parsing) using more powerful languages and the guide to [[guide_interpreting_xml_log|*]] using C# language.// |
| - | <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 ===== | ===== Example ===== | ||
| Line 151: | Line 152: | ||
| ===== Further reading ===== | ===== Further reading ===== | ||
| - | * [[troubleshooting|Troubleshooting]]; | + | * [[troubleshooting|*]]; |
| * [[scripting|Scripting]] documentation; | * [[scripting|Scripting]] documentation; | ||
| - | * Guide to [[guide_automation_advanced|advanced scripting]]; | + | * Guide to [[guide_automation_advanced|*]]; |
| - | * [[library|WinSCP .NET assembly]]; | + | * [[library|*]]; |
| * [[commandline|Command-line]] parameters; | * [[commandline|Command-line]] parameters; | ||
| * WinSCP [[executables|executables]]; | * WinSCP [[executables|executables]]; | ||
| - | * [[faq#scripting_automation|FAQ about scripting]]; | + | * [[faq#scripting|FAQ about scripting]]; |
| * Example [[scripts|scripts]]; | * Example [[scripts|scripts]]; | ||
| - | * [[guide_schedule|Schedule file transfers or synchronization]]. | + | * [[guide_schedule|*]]. |