This is an old revision of the document!

Documentation » Using WinSCP » Guides » Scripting/Automation »

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 that uses WinSCP .NET assembly (typically via PowerShell script) or WinSCP script.

Using a WinSCP .NET assembly gives you more power and flexibility, but requires you to install the assembly. To use a WinSCP script, you do not need anything else, but a WinSCP executable.

Advertisement

This article lists hints and features that will help you with the implementation.

Useful Patterns

You will typically using these 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 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.

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 type and Use remote paths 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 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 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 windows is blocked, while the command is running. Should you want to avoid that, use start command: 
    cmd.exe /c start powershell.exe -File c:\example\example.ps1

Advertisement

Using .NET Assembly

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.

For that use param keyword. You can also mark a parameter as mandatory using Parameter attribute or provide a default value. 

param (
    # Mandatory parameters
    [Parameter(Mandatory)]
    $session,
    [Parameter(Mandatory)]
    $remotePath,
    # Optional parameter with a default value
    $wildcard = "*.*"
)

To provide values to the parameters use syntax -name value on powershell.exe command-line. Typically you will use a custom command pattern to provide the value.

For example, to execute an example.ps1 script with a remotePath parameter set to a path to a selected remote file, use: 

powershell.exe -File c:\example\example.ps1 -remotePath "!/!"

Passing Session Settings

As mentioned above use a custom command pattern !S to pass the current session settings to the script. In the script, use SessionOption.ParseUrl to parse the URL. 

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

Use !S pattern in the custom command to feed the session URL to session parameter: 

powershell.exe -File c:\example\example.ps1 -session !S

Advertisement

Pausing at the End of the Script

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

Using Scripting

Path to WinSCP executable

The custom command has to point to WinSCP executable winscp.exe. Instead of hard-coding its path, use %WINSCP_PATH%. 

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

Parametrized Script

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.

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 "!/!"

Passing Session Settings

As mentioned above use a custom command pattern !S to pass the current session settings in form of session URL to the script. In the script, pass the URL to open command. 

open %1

Use !S pattern in the custom command to feed the session URL to script parameter: 

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

Last modified: by martin

Documentation

Support

Associations

Follow Us