WinSCP Extensions

A WinSCP extension is a text file with a standardized metadata syntax that defines a custom command. As such, it can be easily distributed and installed into WinSCP. The installed extensions can then be executed as any other custom command.

The extension file can include solely the metadata, if the defined custom command relies on standard tools only (such as WinSCP command-line, scripting, built-in Windows commands, etc.). Though typically the extension file will include an actual code too, that implements the extension. In that case the custom command definition will refer to the file itself using %EXTENSION_PATH% variable and the extension metadata will be escaped using “comments” syntax of the respective language. The language can be a Windows batch-file (potentially using the WinSCP scripting), a PowerShell script (potentially using WinSCP .NET assembly), or other language.

Advertisement

The WinSCP installer deploys some useful official extensions. You can install some additional optional extensions too.

Syntax

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:

Key Description
@name Name of the custom command.
You can insert ampersand (&) before a letter to make it a keyboard accelerator. The name should end with ... (ellipsis), if some prompt is displayed (confirmation or input) before the actual command is executed). For example &Grep....
This key is mandatory.
@command The actual custom command.
The command will typically include some custom command patterns and may use %EXTENSION_PATH% variable to refer to the extension file itself. You can also use %WINSCP_PATH% to refer to the WinSCP executable path, or any other environment variable.
This key is mandatory.
@require Defines extension dependencies. Prevents installing the extension on a system that does not meet extension requirements.
Recognized dependencies are:
WinSCP – Defines a minimal supported version of WinSCP, e.g. @require WinSCP 5.8.2
Windows – Defines a minimal supported version of Windows, e.g. @require Windows 6.1 (for Windows 7)
.NET – Defines a minimal supported version of .NET framework, e.g. @require .NET 4.5
PowerShell – Defines a minimal supported version of PowerShell, e.g. @require PowerShell 5.0
To define multiple dependencies, use multiple @require entries on separate lines.
@side Local or Remote type of custom command.
Defaults to Local.
@flag Custom command option.
Recognized options are:
ApplyToDirectories – Makes the command be executed even for selected directories. Makes sense for commands that work with files only (patterns !, !& and !^!).
Recursive – Makes the command be executed for files in selected directories. Makes sense for commands that work with single file only (pattern !).
ShowResults – Makes the output of the custom command be shown in Console window. Can be used with the Remote type custom commands only. The local commands can use their own Windows console window.
ShowResultsInMsgBox – Makes the output of the custom command be shown in message box.
CopyResults – Makes the output of the custom command be copied to a clipboard. Can be used with the Remote type custom commands only. The local commands can make use of an API of their language to copy a contents to the clipboard.
RemoteFiles – With Local type custom command, makes !, !& and !/ patterns refer to remote paths, instead of paths to a local copy of the remote files (prevents the download itself too).
To set multiple options, use multiple @flag entries on separate lines.
@shortcut Associates default custom keyboard shortcut with the custom command. The shortcut can be changed by a user.
@description Description of the custom command. Will be used as a hint in the WinSCP GUI.
@author An author of the extension. Not used.
@version A version of the extension. Has to use pattern major[.minor[.build[.release]]] with digits only. Not used.
@homepage A http:// or https:// URL to the web page of the extension. Not used.
@source A http:// or https:// URL to the extension file itself. Not used. In future versions, it can be used to check for extension updates (with use of the @version key).
@option Defines a user-configurable option of the extension.
To define multiple options, use multiple @option entries on separate lines.
@optionspage URL of a help page for the options dialog. If missing, the @homepage is used instead.

Advertisement

Example

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

# @name         Verify &Checksum
# @command      powershell.exe -ExecutionPolicy Bypass -File "%EXTENSION_PATH%" ^
#                   -sessionUrl "!E" -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.

Options

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 ...>
Parameters Description
name Unique name of the option. In the custom command, any %name% string will get replaced with configured value of the option.
For options dialog control types label, link and group use - (dash), as these have no value.
-config The option is used when configuring the extension on Preferences dialog.
-run The option is used when running the extension. When both the -config and the -run are used, the value configured on the Preferences dialog is used as the default value, when running the extension.
-site A value of the option is site-specific. A session has to be opened, when configuring an extension with site-specific option.
type Type of the option or options dialog control.
Supported types are: textbox, file, dropdownlist, combobox, checkbox, label, link
caption Caption of the options dialog control representing the option.
default Default value of the option.
For run-time options (those without the -config switch) of type textbox and file, non-file custom command patterns (!/, !E, !S, !@, !U, !P, !# and !\) are expanded.
additional Additional parameters specific to the option type. See below.

Details about individual option types:

Type Description
textbox Plain text edit box. The default defines the default text value. The value of the option equals the value entered into the edit box.
file File selector. The default defines the default path. Environment variables in the default value are resolved. The value of the option equals the path selected.
dropdownlist Drop-down menu. The additional parameters define a list of possible values with syntax [value=]text. The text will be displayed in the drop-down menu. The value of the option equals the value of the selected item. If the value= part is missing, the text is used as a value. The item with value equal to the default will be selected by default.
combobox Combo box. The additional parameters define a list of possible values with syntax [value=]text. The text will be displayed in the drop-down menu. The value of the option equals the value of the selected item. If the value= part is missing, the text is used as a value. If a custom text is entered, the value equals to the text. The item with value equal to the default will be selected by default. If no such item exists, the default is used as the default custom text.
checkbox Checkbox. Two optional additional parameters define values of the option, when the checkbox is checked and not checked, respectively. If the default equals to the first additional parameter, the checkbox is checked by default.
label Text label. Just a plain text label displayed on the options dialog.
This “option” has no value. Use - for the name parameter.
link Hyperlink. Either use URL for caption, or use link text for the caption and URL for the default parameter.
This “option” has no value. Use - for the name parameter.
group Group box. Groups all following options to a group box.
This “option” has no value. Use - for the name parameter.

Advertisement

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

Shorthand Description
sessionlogfile Equivalent to: file "&Session log file:"
In addition to that, while it defaults to an empty log file, when browsing for the new log file, it defaults to %TEMP%\extensionname.log. File browser also displays .log files by default only.
pausecheckbox Equivalent to checkbox "&Pause at the end" -pause -pause

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 (the Keyboard shortcut option is added implicitly):

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

Official Extensions

These official extensions are deployed by WinSCP installer:

Advertisement

Optional Extensions

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

Loading

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.

Publishing

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

Further Reading

Last modified: by martin