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.

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

You can pack your custom command to a WinSCP extension format to ease its deployment.

Advertisement

Useful Patterns

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.

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

Advertisement

Using .NET Assembly

Parametrized PowerShell Script

When using the 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
    # The explicit $True value assignment is not needed since PowerShell 3.0
    [Parameter(Mandatory = $True)]
    $sessionUrl,
    [Parameter(Mandatory = $True)]
    $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. If the script requires an input from user, you can use !?prompt! pattern, instead of coding the prompt in PowerShell. You can also rely PowerShell automatically asking value for mandatory parameters that were not provided on command-line.

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 !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)

Advertisement

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

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

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

Examples

Some real-life examples:

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

Advertisement

Passing Session Settings

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

Last modified: by martin