Differences

This shows you the differences between the selected revisions of the page.

extension 2020-12-18		extension 2023-03-30 (current)
	Line 1:		Line 1:
	====== WinSCP Extensions ======		====== WinSCP Extensions ======

-	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 13:		Line 13:
	All metadata are prefixed with ''@'', followed by a metadata key, space(s) or tab(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). 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 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 72:		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'' \| 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. \|	+	\| ''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. \|	+	\| ''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. \|
	Line 97:		Line 97:
	</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 117:		Line 117:
	These official extensions are deployed by WinSCP installer:		These official extensions are deployed by WinSCP installer:

-	* [[extension_generate_http_url\|Generate HTTP URL]];	+	* [[extension_generate_http_url\|*]];
-	* [[extension_compare_files\|Compare files]];	+	* [[extension_compare_files\|*]];
-	* [[library_example_verify_file_checksum\|Verify checksum of a remote file against a local file over SFTP/FTP protocol]];	+	* [[library_example_verify_file_checksum\|*]];
-	* [[library_example_recursive_search_text\|Search recursively for text in remote directory / Grep files over SFTP/FTP protocol]];	+	* [[library_example_recursive_search_text\|*]];
-	* [[library_example_zip_and_upload\|Pack files to ZIP archive and upload it]];	+	* [[library_example_zip_and_upload\|*]];
-	* [[library_example_keep_local_directory_up_to_date\|Keep local directory up to date]];	+	* [[library_example_keep_local_directory_up_to_date\|*]];
-	* [[library_example_advanced_rename\|Batch rename]];	+	* [[library_example_advanced_rename\|*]];
-	* [[extension_synchronize_another_server\|Synchronize with another remote server]].	+	* [[extension_synchronize_another_server\|*]].

	===== [[optional]] Optional Extensions =====		===== [[optional]] Optional Extensions =====
	Line 131:		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\|Download remote file from a path stored in clipboard]];	+	* [[library_example_download_clipboard\|*]];
-	* [[library_example_moves_files_keeping_directory_structure#upload_powershell\|Recursively move files in directory tree to SFTP/FTP server while preserving source directory structure]];	+	* [[library_example_moves_files_keeping_directory_structure#upload_powershell\|*]];
-	* [[library_example_remember_downloaded_files\|Remember already downloaded files so they are not downloaded again]];	+	* [[library_example_remember_downloaded_files\|*]];
-	* [[extension_archive_and_download\|Archive remote files to ZIP archive, download it, and optionally extract it]];	+	* [[extension_archive_and_download\|*]];
-	* [[library_example_two_way_synchronize_delete\|Two-Way Synchronization with Delete with SFTP/FTP server]].	+	* [[library_example_two_way_synchronize_delete\|*]].

	===== [[loading]] Loading =====		===== [[loading]] Loading =====
	Line 143:		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]].

	Line 156:		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\|*]].

extension 2020-12-18		extension 2023-03-30 (current)
	Line 1:		Line 1:
	====== WinSCP Extensions ======		====== WinSCP Extensions ======

-	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 13:		Line 13:
	All metadata are prefixed with ''@'', followed by a metadata key, space(s) or tab(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). 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 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 72:		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'' \| 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. \|	+	\| ''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. \|	+	\| ''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. \|
	Line 97:		Line 97:
	</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 117:		Line 117:
	These official extensions are deployed by WinSCP installer:		These official extensions are deployed by WinSCP installer:

-	* [[extension_generate_http_url\|Generate HTTP URL]];	+	* [[extension_generate_http_url\|*]];
-	* [[extension_compare_files\|Compare files]];	+	* [[extension_compare_files\|*]];
-	* [[library_example_verify_file_checksum\|Verify checksum of a remote file against a local file over SFTP/FTP protocol]];	+	* [[library_example_verify_file_checksum\|*]];
-	* [[library_example_recursive_search_text\|Search recursively for text in remote directory / Grep files over SFTP/FTP protocol]];	+	* [[library_example_recursive_search_text\|*]];
-	* [[library_example_zip_and_upload\|Pack files to ZIP archive and upload it]];	+	* [[library_example_zip_and_upload\|*]];
-	* [[library_example_keep_local_directory_up_to_date\|Keep local directory up to date]];	+	* [[library_example_keep_local_directory_up_to_date\|*]];
-	* [[library_example_advanced_rename\|Batch rename]];	+	* [[library_example_advanced_rename\|*]];
-	* [[extension_synchronize_another_server\|Synchronize with another remote server]].	+	* [[extension_synchronize_another_server\|*]].

	===== [[optional]] Optional Extensions =====		===== [[optional]] Optional Extensions =====
	Line 131:		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\|Download remote file from a path stored in clipboard]];	+	* [[library_example_download_clipboard\|*]];
-	* [[library_example_moves_files_keeping_directory_structure#upload_powershell\|Recursively move files in directory tree to SFTP/FTP server while preserving source directory structure]];	+	* [[library_example_moves_files_keeping_directory_structure#upload_powershell\|*]];
-	* [[library_example_remember_downloaded_files\|Remember already downloaded files so they are not downloaded again]];	+	* [[library_example_remember_downloaded_files\|*]];
-	* [[extension_archive_and_download\|Archive remote files to ZIP archive, download it, and optionally extract it]];	+	* [[extension_archive_and_download\|*]];
-	* [[library_example_two_way_synchronize_delete\|Two-Way Synchronization with Delete with SFTP/FTP server]].	+	* [[library_example_two_way_synchronize_delete\|*]].

	===== [[loading]] Loading =====		===== [[loading]] Loading =====
	Line 143:		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]].

	Line 156:		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\|*]].

Differences

Documentation

Support

Associations

Follow Us