WinSCP Extensions

This feature is available only in the latest beta release.

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

WinSCP installer deploys some useful extensions, see the Example section for a list.

Syntax
Example
Loading

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 @, follower by a metadata key, whitespace(s), and a value.

The metadata line have to start with the @, optionally escaped with some recognized “comments” syntax. The recognized comment syntaxes are, rem (Windows batch file), # (e.g. WinSCP script, PowerShell, Perl, Python), // (e.g. JavaScript), ' (VBScript).

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 meat extension requirements. Recognized dependencies are: `WinSCP` - Defines a minimal supported version of WinSCP, e.g. `@require WinSCP 5.8.2` `.NET` - Defines a minimal supported version of .NET framework, e.g. `@require .NET 4.5` To define multiple dependencies, use multiple `@require` entries on separate lines.
`@side`	`Local` or `Remote` type of custom command.
`@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 make use their own Windows console window. `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 custom keyboard shortcut with the custom command.
`@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).

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 "!S" -localPath "!^!" -remotePath "!/!" -pause
# @description  Compares checksums of the selected local and remote file
# @flag         RemoteFiles
# @version      1

For full examples, see the official WinSCP extensions (deployed by WinSCP installer):

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.