WinSCP Extensions

The extension metadata have to start on the very first line of the extension file. Metadata parsing stops on the first non-metadata line.

All metadata are prefixed with @, followed by a metadata key, space(s) or tab(s), and a value.

The metadata line have to start with the @, optionally escaped with some recognized “single-line comments” syntax. The recognized comment syntaxes are rem (Windows batch file), # (e.g. WinSCP script, PowerShell, Perl, Python), // (e.g. JavaScript), ' (VBScript). A metadata line can continue on following line(s) by using `^ at the end of the line. The following line(s) can also be escaped with a comment syntax, the same way as the first line.

The recognized metadata keys are:

This example shows a header of a PowerShell script with extension metadata:

# @name         Verify &Checksum
# @command      powershell.exe -ExecutionPolicy Bypass -File "%EXTENSION_PATH%" ^
#                   -sessionUrl "!S" -localPath "!^!" -remotePath "!/!" -pause
# @description  Compares checksums of the selected local and remote file
# @flag         RemoteFiles
# @version      1

For full examples, see the official and optional extensions below.

The extension can have user-configurable options, which are defined using @option metadata.

The @option entry has the following parameters:

@option <name> [-config [-site]] [-run] <type> "<caption>" <default> <additional ...>

Details about individual option types:

There are two aliases for common options. Captions of the aliases are localized.

For example the following entries:

# @option       - -config label "Example extension options"
# @option       - -config link https://winscp.net/eng/docs/extension#options
# @option       Mask -config textbox "&File mask" "*.txt; *.html"
# @option       SearchType -config dropdownlist "Search for:" -files ^
#                   -files="Files" -dirs="Directories" -both="Files and Directories"
# @option       LogFile -config file "&Log File:" "%APPDATA%\mylog.log"
# @option       Pause -config checkbox "&Pause at the end" -pause -pause

Produce this options dialog:

When the option names are used in a command like:

example.exe -Mask="%Mask%" %SearchType% -Log="%LogFile%" %Pause%

The resulting command (with the options configured as shown on the screenshot, i.e. with the default values) will be:

example.exe -Mask="*.txt; *.html" -files -Log="C:\Users\username\AppData\Roaming\mylog.log" -pause

These official extensions are deployed by WinSCP installer:

• Generate HTTP URL;
• Verify checksum of a remote file against a local file over SFTP/FTP protocol;
• Search recursively for text in remote directory / Grep files over SFTP/FTP protocol;
• Pack files to ZIP archive and upload it;
• Keep local directory up to date;
• Batch rename.

You can install these optional extensions by using their page URL’s in the Add Extension command:

• Find duplicate files in SFTP/FTP server;
• Download remote file from a path stored in clipboard;
• Recursively move files in directory tree to SFTP/FTP server while preserving source directory structure.

WinSCP looks for extensions in three locations:

• Extension subfolder of WinSCP installation folder. This is where WinSCP installer installs the official WinSCP extensions (see above).
• WinSCP.exe executable folder. This is handy for a portable use of WinSCP. Just put your extensions to the same folder (USB drive) as the WinSCP executables.
• Extensions subfolder of WinSCP application data folder. I.e. %APPDATA%\WinSCP\Extensions, typically C:\Users\username\AppData\Roaming\WinSCP\Extensions. This is where WinSCP stores the user-installed extensions.

The extensions must have a file extension .WinSCPextension, optionally followed by an actual file type extension, e.g. .WinSCPextension.ps1. WinSCP automatically renames the user-installed extension files to match this requirement.

Files with other file extensions in the extension locations are ignored, as well as files that have invalid extension metadata.

If you created a useful extension and want to make it publicly available on the WinSCP site, contact us on the support forum.

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