Differences
This shows you the differences between the selected revisions of the page.
| extension 2016-05-24 | extension 2023-03-30 (current) | ||
| Line 1: | Line 1: | ||
| ====== WinSCP Extensions ====== | ====== WinSCP Extensions ====== | ||
| - | &beta_feature | ||
| - | A WinSCP extension is a text file with a standardized metadata syntax that defines a [[custom_command|custom command]]. As such, it can be easily distributed and [[ui_pref_commands#extensions|installed into WinSCP]]. | + | A WinSCP extension is a text file with a standardized metadata syntax that defines a [[custom_command|custom command]]. As such, it can be easily distributed and [[ui_pref_commands#extensions|installed into WinSCP]]. The installed extensions can then be [[custom_command#executing_and_configuring|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 [[commandline|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 ''[[#name|%EXTENSION_PATH%]]'' variable and the extension metadata will be escaped using [[#syntax|"comments" syntax]] of the respective language. The language can be a Windows batch-file (potentially using the WinSCP [[scripting]]), a PowerShell script (potentially using [[library|WinSCP .NET assembly]]), or other language. | The extension file can include solely the metadata, if the defined custom command relies on standard tools only (such as [[commandline|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 ''[[#name|%EXTENSION_PATH%]]'' variable and the extension metadata will be escaped using [[#syntax|"comments" syntax]] of the respective language. The language can be a Windows batch-file (potentially using the WinSCP [[scripting]]), a PowerShell script (potentially using [[library|WinSCP .NET assembly]]), or other language. | ||
| Line 8: | Line 7: | ||
| The [[installation|WinSCP installer]] deploys some useful [[#official|official extensions]]. You can install some additional [[#optional|optional extensions]] too. | The [[installation|WinSCP installer]] deploys some useful [[#official|official extensions]]. You can install some additional [[#optional|optional extensions]] too. | ||
| - | ===== Syntax ===== | + | ===== [[syntax]] 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. | 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, space(s), and a value. | + | 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). | + | 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: | The recognized metadata keys are: | ||
| Line 21: | Line 20: | ||
| | ''@==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. | | | ''@==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|custom command]]. \\ The command will typically include some [[custom_command#patterns|custom command patterns]] and may use ''%EXTENSION_PATH%'' variable to refer to the extension file itself. You can also use ''[[scripting#variables|%WINSCP_PATH%]]'' to refer to the WinSCP executable path, or any other environment variable. \\ This key is mandatory. | | | ''@command'' | The actual [[custom_command|custom command]]. \\ The command will typically include some [[custom_command#patterns|custom command patterns]] and may use ''%EXTENSION_PATH%'' variable to refer to the extension file itself. You can also use ''[[scripting#variables|%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'' \\ ''.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. | | + | | ''@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'' [[custom_command#types|type of custom command]]. \\ Defaults to ''Local''. | | | ''@side'' | ''Local'' or ''Remote'' [[custom_command#types|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 [[ui_console|Console window]]. Can be used with the ''Remote'' type custom commands only. The local commands can 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. | | + | | ''@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 [[ui_console|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 [[custom_key_shortcuts|custom keyboard shortcut]] with the custom command. | | + | | ''@==shortcut=='' | Associates default [[custom_key_shortcuts|custom keyboard shortcut]] with the custom command. The shortcut [[ui_pref_commands#extensions|can be changed by a user]]. | |
| | ''@description'' | Description of the custom command. Will be used as a hint in the WinSCP GUI. | | | ''@description'' | Description of the custom command. Will be used as a hint in the WinSCP GUI. | | ||
| | ''@author'' | An author of the extension. Not used. | | | ''@author'' | An author of the extension. Not used. | | ||
| Line 30: | Line 29: | ||
| | ''@homepage'' | A ''%%http://%%'' or ''%%https://%%'' URL to the web page of the extension. 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). | | | ''@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|option of the extension]]. \\ To define multiple options, use multiple ''@option'' entries on separate lines. | | + | | ''@option'' | Defines a user-configurable [[#options|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. | | | ''@optionspage'' | URL of a help page for the options dialog. If missing, the ''@homepage'' is used instead. | | ||
| Line 39: | Line 38: | ||
| <code powershell> | <code powershell> | ||
| # @name Verify &Checksum | # @name Verify &Checksum | ||
| - | # @command powershell.exe -ExecutionPolicy Bypass -File "%EXTENSION_PATH%" -sessionUrl "!S" -localPath "!^!" -remotePath "!/!" -pause | + | # @command powershell.exe -ExecutionPolicy Bypass -File "%EXTENSION_PATH%" ^ |
| + | # -sessionUrl "!E" -localPath "!^!" -remotePath "!/!" -pause | ||
| # @description Compares checksums of the selected local and remote file | # @description Compares checksums of the selected local and remote file | ||
| # @flag RemoteFiles | # @flag RemoteFiles | ||
| Line 47: | Line 47: | ||
| For full examples, see the official and optional extensions below. | For full examples, see the official and optional extensions below. | ||
| - | ===== Options ==== | + | ===== [[options]] Options ==== |
| The extension can have user-configurable options, which are defined using ''@option'' metadata. | The extension can have user-configurable options, which are defined using ''@option'' metadata. | ||
| Line 54: | Line 54: | ||
| <code> | <code> | ||
| - | @option <name> <type> "<caption>" <default> <additional ...> | + | @option <name> [-config [-site]] [-run] <type> "<caption>" <default> <additional ...> |
| </code> | </code> | ||
| ^ Parameters ^ Description ^ | ^ 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'' and ''link'' use ''-'' (dash), as these have no value. | | + | | ''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 [[ui_pref_commands|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'' | | | ''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. | | | ''caption'' | Caption of the options dialog control representing the option. | | ||
| - | | ''default'' | Default value of 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|custom command patterns]] (''!/'', ''!E'', ''!S'', ''!@'', ''!U'', ''!P'', ''!#'' and ''!\'') are expanded. | |
| | ''additional'' | Additional parameters specific to the option type. See below. | | | ''additional'' | Additional parameters specific to the option type. See below. | | ||
| Line 69: | Line 72: | ||
| | ''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. | | | ''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. | | | ''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'' | Dropdown menu. The ''additional'' parameters define a list of possible values with syntax ''[value=]text''. The ''text'' will be displayed in the dropdown 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. | | + | | ''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 dropdown 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. | | + | | ''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. | | | ''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. | | | ''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. | | | ''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. | | ||
| + | |||
| + | 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: | For example the following entries: | ||
| <code powershell> | <code powershell> | ||
| - | # @option - label "Example extension options" | + | # @option - -config label "Example extension options" |
| - | # @option - link https://winscp.net/eng/docs/extension#options | + | # @option - -config link https://winscp.net/eng/docs/extension#options |
| - | # @option Mask textbox "&File mask" "*.txt; *.html" | + | # @option Mask -config textbox "&File mask" "*.txt; *.html" |
| - | # @option SearchType dropdownlist "Search for:" -files -files="Files" -dirs="Directories" -both="Files and Directories" | + | # @option SearchType -config dropdownlist "Search for:" -files ^ |
| - | # @option LogFile file "&Log File:" "%APPDATA%\mylog.log" | + | # -files="Files" -dirs="Directories" -both="Files and Directories" |
| - | # @option Pause checkbox "&Pause at the end" -pause -pause | + | # @option LogFile -config file "&Log File:" "%APPDATA%\mylog.log" |
| + | # @option Pause -config checkbox "&Pause at the end" -pause -pause | ||
| </code> | </code> | ||
| - | Produce this options dialog: | + | Produce this options dialog (the [[ui_pref_commands#configure|//Keyboard shortcut// option]] is added implicitly): |
| &screenshotpict(extension_options) | &screenshotpict(extension_options) | ||
| Line 93: | Line 104: | ||
| <code> | <code> | ||
| - | example.exe -Mask="%Mask%" %SearchType% -Log="%LogFile%" %Pause% | + | example.exe -mask="%Mask%" %SearchType% -log="%LogFile%" %Pause% |
| </code> | </code> | ||
| Line 99: | Line 110: | ||
| <code> | <code> | ||
| - | example.exe -Mask="*.txt; *.html" -files -Log="C:\Users\username\AppData\Roaming\mylog.log" -pause | + | example.exe -mask="*.txt; *.html" -files -log="C:\Users\username\AppData\Roaming\mylog.log" -pause |
| </code> | </code> | ||
| Line 106: | Line 117: | ||
| These official extensions are deployed by WinSCP installer: | These official extensions are deployed by WinSCP installer: | ||
| - | * [[library_example_verify_file_checksum|Verify checksum of a remote file against a local file over SFTP/FTP protocol]]; | + | * [[extension_generate_http_url|*]]; |
| - | * [[library_example_recursive_search_text|Search recursively for text in remote directory / Grep files over SFTP/FTP protocol]]; | + | * [[extension_compare_files|*]]; |
| - | * [[library_example_zip_and_upload|Pack files to ZIP archive and upload it]]. | + | * [[library_example_verify_file_checksum|*]]; |
| + | * [[library_example_recursive_search_text|*]]; | ||
| + | * [[library_example_zip_and_upload|*]]; | ||
| + | * [[library_example_keep_local_directory_up_to_date|*]]; | ||
| + | * [[library_example_advanced_rename|*]]; | ||
| + | * [[extension_synchronize_another_server|*]]. | ||
| ===== [[optional]] Optional Extensions ===== | ===== [[optional]] Optional Extensions ===== | ||
| Line 114: | Line 130: | ||
| You can install these optional extensions by using their page URL's in the //[[ui_pref_commands#extensions|Add Extension]]// command: | You can install these optional extensions by using their page URL's in the //[[ui_pref_commands#extensions|Add Extension]]// command: | ||
| - | * [[library_example_find_duplicate_files|Find duplicate files in SFTP/FTP server]]. | + | * [[library_example_find_duplicate_files|*]]; |
| + | * [[library_example_download_clipboard|*]]; | ||
| + | * [[library_example_moves_files_keeping_directory_structure#upload_powershell|*]]; | ||
| + | * [[library_example_remember_downloaded_files|*]]; | ||
| + | * [[extension_archive_and_download|*]]; | ||
| + | * [[library_example_two_way_synchronize_delete|*]]. | ||
| ===== [[loading]] Loading ===== | ===== [[loading]] Loading ===== | ||
| Line 121: | Line 142: | ||
| * ''Extension'' subfolder of WinSCP installation folder. This is where WinSCP installer installs the official WinSCP extensions (see above). | * ''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|portable use]] of WinSCP. Just put your extensions to the same folder (USB drive) as the [[executable|WinSCP executables]]. | + | * ''WinSCP.exe'' executable folder. This is handy for a [[portable|portable use]] of WinSCP. Just put your extensions to the same folder (USB drive) as the [[executables|WinSCP executables]]. |
| * ''Extensions'' subfolder of WinSCP application data folder. I.e. ''%APPDATA%\WinSCP\Extensions'', typically ''C:\Users\username\AppData\Roaming\WinSCP\Extensions''. &winpath This is where WinSCP [[ui_pref_commands#extensions|stores the user-installed extensions]]. | * ''Extensions'' subfolder of WinSCP application data folder. I.e. ''%APPDATA%\WinSCP\Extensions'', typically ''C:\Users\username\AppData\Roaming\WinSCP\Extensions''. &winpath This is where WinSCP [[ui_pref_commands#extensions|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 [[ui_pref_commands#extensionsuser-installed extension files]] to match this requirement. | + | The extensions must have a file extension ''.WinSCPextension'', optionally followed by an actual file type extension, e.g. ''.WinSCPextension.ps1''. WinSCP automatically renames the [[ui_pref_commands#extensions|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. | Files with other file extensions in the extension locations are ignored, as well as files that have invalid extension metadata. | ||
| Line 134: | Line 155: | ||
| ===== Further Reading ===== | ===== Further Reading ===== | ||
| - | * [[guide_custom_commands_automation|Extending WinSCP with Custom commands that run .NET assembly or WinSCP script]]. | + | * [[guide_custom_commands_automation|*]]. |