Differences
This shows you the differences between the selected revisions of the page.
| guide_custom_commands_automation 2016-10-13 | guide_custom_commands_automation 2022-10-21 (current) | ||
| Line 7: | Line 7: | ||
| ===== Useful Patterns ===== | ===== Useful Patterns ===== | ||
| - | You will typically using these [[custom_command#patterns|custom command patterns]]: | + | You will typically be using these [[custom_command#patterns|custom command patterns]]: |
| - | * ''!S'' (session URL) to pass the current session settings to the script. If you want to pass a password too, you have to [[security_credentials|store or remember it]]. | + | * ''!E'' (session URL) to pass the current session settings to the script. If you want to pass a password too, you have to [[security_credentials|store or remember it]]. |
| * ''!/'' and ''!'' combined to ''!/!'' to pass a full path to a selected remote file. | * ''!/'' and ''!'' combined to ''!/!'' to pass a full path to a selected remote file. | ||
| * ''!^!'' to pass a full path to a selected local file. | * ''!^!'' to pass a full path to a selected local file. | ||
| - | ===== General Hints ===== | + | ===== [[general_hints]] General Hints ===== |
| * Both PowerShell script and WinSCP script are to be executed locally using path to the remote files, so make sure you select //Local command// [[custom_command#types|type]] and //[[ui_customcommand|Use remote files]]// option. | * Both PowerShell script and WinSCP script are to be executed locally using path to the remote files, so make sure you select //Local command// [[custom_command#types|type]] and //[[ui_customcommand|Use remote files]]// option. | ||
| * The application run as a custom command (be it the ''powershell.exe'' or WinSCP in a console mode) is executed in WinSCP startup directory, not in a WinSCP [[executable]] directory, nor directory shown in a local panel (in [[ui_commander|Commander interface]]). \\ So generally, you should use a full path to local files, both in the custom command itself (particularly for a path to WinSCP executable and path to the script) and the script (including a [[library_powershell#loading|path to WinSCP .NET assembly]]). \\ You can make use of ''[[local_path|%WINSCP_PATH%]]'' to refer to the WinSCP executable path. | * The application run as a custom command (be it the ''powershell.exe'' or WinSCP in a console mode) is executed in WinSCP startup directory, not in a WinSCP [[executable]] directory, nor directory shown in a local panel (in [[ui_commander|Commander interface]]). \\ So generally, you should use a full path to local files, both in the custom command itself (particularly for a path to WinSCP executable and path to the script) and the script (including a [[library_powershell#loading|path to WinSCP .NET assembly]]). \\ You can make use of ''[[local_path|%WINSCP_PATH%]]'' to refer to the WinSCP executable path. | ||
| * If the custom command refers to files (i.e. uses [[custom_command#patterns|patterns]] like ''!'', ''!&'', ''!^!''), WinSCP window is blocked, while the command is running. Should you want to avoid that, use the ''start'' command. Though note this prevents WinSCP from uploading files back to the server, if they were modified by the command. \\ <code batch> | * If the custom command refers to files (i.e. uses [[custom_command#patterns|patterns]] like ''!'', ''!&'', ''!^!''), WinSCP window is blocked, while the command is running. Should you want to avoid that, use the ''start'' command. Though note this prevents WinSCP from uploading files back to the server, if they were modified by the command. \\ <code batch> | ||
| - | cmd.exe /c start powershell.exe -File c:\example\example.ps1 | + | cmd /C start "" powershell.exe -File c:\example\example.ps1 |
| </code> | </code> | ||
| * If the command modifies a remote directory, you can run WinSCP with the ''[[commandline#operations|/refresh]]'' parameter at the end of the (PowerShell) script to have the remote panel reloaded. \\ <code powershell> | * If the command modifies a remote directory, you can run WinSCP with the ''[[commandline#operations|/refresh]]'' parameter at the end of the (PowerShell) script to have the remote panel reloaded. \\ <code powershell> | ||
| Line 33: | Line 33: | ||
| When using the WinSCP .NET assembly from a [[library_powershell|PowerShell script]], the script needs to take parameters to be customized for a current session settings or selected file path, etc. | When using the WinSCP .NET assembly from a [[library_powershell|PowerShell script]], the script needs to take parameters to be customized for a current session settings or selected file path, etc. | ||
| - | For that use ''param'' keyword. You can also mark a parameter as mandatory using ''[[https://msdn.microsoft.com/en-us/library/ms714348.aspx|Parameter]]'' attribute or provide a default value. | + | For that use ''param'' keyword. You can also mark a parameter as mandatory using ''[[https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/parameter-attribute-declaration|Parameter]]'' attribute or provide a default value. |
| <code powershell> | <code powershell> | ||
| param ( | param ( | ||
| # Mandatory parameters | # Mandatory parameters | ||
| - | [Parameter(Mandatory = $True)] # The explicit $True value assignment is not needed since PowerShell 3.0 | + | # The explicit $True value assignment is not needed since PowerShell 3.0 |
| + | [Parameter(Mandatory = $True)] | ||
| $sessionUrl, | $sessionUrl, | ||
| [Parameter(Mandatory = $True)] | [Parameter(Mandatory = $True)] | ||
| Line 57: | Line 58: | ||
| ==== Passing Session Settings ==== | ==== Passing Session Settings ==== | ||
| - | As mentioned above use a custom command pattern ''!S'' to pass the current session settings in a form of a session URL to the script.·In the script, use ''[[library_sessionoptions_parseurl|SessionOption.ParseUrl]]'' to parse the %%URL%%. | + | As mentioned above use a custom command pattern ''!E'' to pass the current session settings in a form of a session URL to the script. |
| + | |||
| + | In the script, accept the %%URL%% using a parameter (''sessionUrl'' here) and use ''[[library_sessionoptions_parseurl|SessionOption.ParseUrl]]'' to parse the %%URL%%. | ||
| <code powershell> | <code powershell> | ||
| Line 74: | Line 77: | ||
| </code> | </code> | ||
| - | Use ''!S'' pattern in the custom command to feed the session %%URL%% to ''sessionUrl'' parameter: | + | In the custom command, feed the session %%URL%% to the ''sessionUrl'' parameter: |
| <code batch> | <code batch> | ||
| - | powershell.exe -File c:\example\example.ps1 -sessionUrl !S | + | powershell.exe -File c:\example\example.ps1 -sessionUrl !E |
| </code> | </code> | ||
| Line 89: | Line 92: | ||
| </code> | </code> | ||
| - | ==== Examples ==== | + | ==== [[library_examples]] Examples ==== |
| Some real-life examples: | Some real-life examples: | ||
| - | * [[library_example_verify_file_checksum|Verify checksum of a remote file against a local file over SFTP/FTP protocol]] | + | * [[library_example_verify_file_checksum|*]]; |
| - | * [[library_example_find_duplicate_files|Find duplicate files in SFTP/FTP server]] | + | * [[library_example_find_duplicate_files|*]]; |
| - | * [[library_example_recursive_search_text|Search recursively for text in remote directory / Grep files over SFTP/FTP protocol]] | + | * [[library_example_recursive_search_text|*]]. |
| ===== Using Scripting ===== | ===== Using Scripting ===== | ||
| Line 123: | Line 126: | ||
| ==== Passing Session Settings ==== | ==== Passing Session Settings ==== | ||
| - | As mentioned above use a custom command pattern ''!S'' to pass the current session settings in a form of a session URL to the script.·In the script, pass the %%URL%% to ''[[scriptcommand_open|open]]'' command. | + | As mentioned above use a custom command pattern ''!E'' to pass the current session settings in a form of a session URL to the script. |
| + | |||
| + | In the script, accept a session %URL% as a script parameter and pass it to ·[[scriptcommand_open|''open'' command]]. | ||
| <code winscp> | <code winscp> | ||
| Line 129: | Line 134: | ||
| </code> | </code> | ||
| - | Use ''!S'' pattern in the custom command to feed the session %%URL%% to a script parameter: | + | In the custom command, feed the session %%URL%% to the script parameter: |
| <code batch> | <code batch> | ||
| - | "%WINSCP_PATH%\winscp.exe" /script=c:\example\example.txt /parameter // !S | + | "%WINSCP_PATH%\winscp.exe" /script=c:\example\example.txt /parameter // !E |
| </code> | </code> | ||