Differences

This shows you the differences between the selected revisions of the page.

guide_custom_commands_automation 2015-07-10 guide_custom_commands_automation 2022-10-21 (current)
Line 1: Line 1:
====== Extending WinSCP with Custom commands that run .NET assembly or WinSCP script ====== ====== Extending WinSCP with Custom commands that run .NET assembly or WinSCP script ======
If WinSCP GUI lacks a certain file operation, you may be able to implement it using a [[custom_command|custom command]] that uses [[library|WinSCP .NET assembly]] (typically via [[library_powershell|PowerShell]] script) or WinSCP [[scripting|script]]. If WinSCP GUI lacks a certain file operation, you may be able to implement it using a [[custom_command|custom command]] that uses [[library|WinSCP .NET assembly]] (typically via [[library_powershell|PowerShell]] script) or WinSCP [[scripting|script]].
- 
-Using a WinSCP .NET assembly gives you more power and flexibility, but requires you to [[library_install|install the assembly]]. To use a WinSCP script, you do not need anything else, but a WinSCP [[executables|executable]]. 
This article lists hints and features that will help you with the implementation. This article lists hints and features that will help you with the implementation.
 +
 +You can pack your custom command to a [[extension|WinSCP extension]] format to ease its deployment.
===== 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 ''powershell.exe'' or WinSCP in a console mode) is executed in WinSCP startup directory, not in a WinSCP [[executable]] directory, nor directory shown in local panel (in [[ui_commander|Commander interface]]). \\ So generally, you should use a full path to a 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 ''[[scripting#variables|%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 ''start'' 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> 
 +  * 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> 
 +& "$env:WINSCP_PATH\WinSCP.exe" "$sessionUrl" /refresh "$remotePath"
</code> </code>
 +
 +
Line 26: Line 31:
==== Parametrized PowerShell Script ==== ==== Parametrized PowerShell Script ====
-When using WinSCP .NET assembly from a 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 ''[[http://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)] +    # The explicit $True value assignment is not needed since PowerShell 3.0 
-    $session+····[Parameter(Mandatory = $True)] 
-    [Parameter(Mandatory)]+    $sessionUrl
 +    [Parameter(Mandatory = $True)]
    $remotePath,     $remotePath,
    # Optional parameter with a default value     # Optional parameter with a default value
Line 52: 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>
param ( param (
-    [Parameter(Mandatory)] +    [Parameter(Mandatory = $True)] 
-    $session+    $sessionUrl
) )
Line 63: Line 71:
$sessionOptions = New-Object WinSCP.SessionOptions $sessionOptions = New-Object WinSCP.SessionOptions
-$sessionOptions.ParseUrl($session)+$sessionOptions.ParseUrl($sessionUrl)
$session = New-Object WinSCP.Session $session = New-Object WinSCP.Session
Line 69: Line 77:
</code> </code>
-Use ''!S'' pattern in the custom command to feed the session %%URL%% to ''session'' parameter:+In the custom command, feed the session %%URL%% to the ''sessionUrl'' parameter:
<code batch> <code batch>
-powershell.exe -File c:\example\example.ps1 -session !S+powershell.exe -File c:\example\example.ps1 -sessionUrl !E
</code> </code>
Line 84: Line 92:
</code> </code>
-==== Example ====+==== [[library_examples]] Examples ====
-See real-life example [[library_example_verify_file_checksum|Verify checksum of a remote file against a local file over SFTP/FTP protocol]].+Some real-life examples: 
 + 
 +  * [[library_example_verify_file_checksum|*]]; 
 +  * [[library_example_find_duplicate_files|*]]; 
 +  * [[library_example_recursive_search_text|*]].
===== Using Scripting ===== ===== Using Scripting =====
Line 92: Line 104:
==== Path to WinSCP executable ==== ==== Path to WinSCP executable ====
-The custom command has to point to WinSCP [[executables|executable]] ''winscp.exe''. Instead of hard-coding its path, use ''[[scripting#variables|%WINSCP_PATH%]]''.+The custom command has to point to WinSCP [[executables|executable]] ''winscp.exe''. Instead of hard-coding its path, use ''[[local_path|%WINSCP_PATH%]]''.
<code batch> <code batch>
Line 114: 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 120: 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>

Last modified: by martin