Extending WinSCP with Custom commands that run .NET assembly or WinSCP script

You will typically be using these custom command patterns:

• !E (session URL) to pass the current session settings to the script. If you want to pass a password too, you have to store or remember it.
• !/ and ! combined to !/! to pass a full path to a selected remote file.
• !^! to pass a full path to a selected local file.

• Both PowerShell script and WinSCP script are to be executed locally using path to the remote files, so make sure you select Local command type and 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 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 path to WinSCP .NET assembly).
  You can make use of %WINSCP_PATH% to refer to the WinSCP executable path.
• If the custom command refers to files (i.e. uses 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.
  

  cmd /C start "" powershell.exe -File c:\example\example.ps1

• If the command modifies a remote directory, you can run WinSCP with the /refresh parameter at the end of the (PowerShell) script to have the remote panel reloaded.
  

  & "$env:WINSCP_PATH\WinSCP.exe" "$sessionUrl" /refresh "$remotePath"

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 SessionOption.ParseUrl to parse the URL.

param (
    [Parameter(Mandatory = $True)]
    $sessionUrl
)
 
...
 
$sessionOptions = New-Object WinSCP.SessionOptions
$sessionOptions.ParseUrl($sessionUrl)
 
$session = New-Object WinSCP.Session
$session.Open($sessionOptions)

In the custom command, feed the session URL to the sessionUrl parameter:

powershell.exe -File c:\example\example.ps1 -sessionUrl !E

The PowerShell script console window disappears as soon as the script finishes. If you want to inspect the script output, you have to explicitly pause at its end:

Write-Host "Press any key to exit..."
[System.Console]::ReadKey() | Out-Null

Some real-life examples:

• Verify checksum of a remote file against a local file over SFTP/FTP protocol;
• Find duplicate files in SFTP/FTP server;
• Search recursively for text in remote directory / Grep files over SFTP/FTP protocol.

The script needs to take parameters to be customized for a current session settings or selected file path, etc.

Learn how to write Parametrized script using /parameter command-line parameter.

Typically you will use a custom command pattern to provide the value to parameter. If the script requires an input from user, you can use !?prompt! pattern to have WinSCP ask user for the input.

For example, to execute an example.txt script with the first parameter set to a path to a selected remote file, use:

"%WINSCP_PATH%\winscp.exe" /script=c:\example\example.txt /parameter // "!/!"

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 open command.

open %1

In the custom command, feed the session URL to the script parameter:

"%WINSCP_PATH%\winscp.exe" /script=c:\example\example.txt /parameter // !E