Differences
This shows you the differences between the selected revisions of the page.
| ui_generateurl 2015-02-18 | ui_generateurl 2024-01-19 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== Generate URL Dialog ====== | + | ====== Generate Session URL/Code/Transfer Code Dialog ====== |
| - | Generate %%URL%% dialog is used to generate a [[session_url|session URL]] or a file URL. | + | Generate session %%URL/code%% dialog is used to generate a [[session_url|session URL]], a file URL or a code template. |
| - | To open the dialog use: | + | To open the dialog to generate the session %%URL%% or code, use: |
| - | * //Manage > Generate %%URL%%// command on [[ui_login|Login dialog]] to generate session %%URL%% for selected site. | + | * //Tabs > Generate Session %%URL%%/Code// command on the main window to generate session %%URL%% or code template for the current session. (preferred) |
| - | * //Session > Generate %%URL%%// command on main window to generate session %%URL%% for current session. | + | * //Manage > Generate Session %%URL/Code%%// command on the [[ui_login|Login dialog]] to generate session %%URL%% or code template for the selected site. |
| - | * //File(s) > File Names > Generate %%URL%%// command on main window to generate file %%URL%% for files selected in remote [[ui_file_panel|file panel]]. | + | |
| + | To open the dialog to generate a file transfer code, use: | ||
| + | |||
| + | * //Transfer Settings > Generate Code// command on the [[ui_copy|Transfer Options dialog]]. | ||
| + | |||
| + | To open the dialog to generate the file %%URL%%, use: | ||
| + | |||
| + | * //Files > File Names > Generate File %%URL%%// command on main window to generate file %%URL%% for files selected in the remote [[ui_file_panel|file panel]]. | ||
| + | |||
| + | &toc_title(The dialog has three tabs. Each is described individually.) | ||
| + | |||
| + | ===== [[url]] URL Tab ===== | ||
| + | Use the //%%URL%% tab// to generate a [[session_url|session URL]] or a file URL. The tab is not available when generating a file transfer code. | ||
| &screenshotpict(generateurl) | &screenshotpict(generateurl) | ||
| - | ===== URL Options ===== | + | The generated %%URL%% always includes a protocol and a host name portions. Other parts can be included optionally. |
| - | Generated %%URL%% always includes protocol and host name portions. Other parts can be included optionally. | + | |
| + | Check the //User name// to include username into the %%URL%%. The option is not available when the dialog is opened from the Login dialog and the user name was not specified; or (rarely) when the current session did not require the user name. | ||
| + | |||
| + | Check the //Password// to include password into the %%URL%%. Make sure you protect an %%URL%% that includes the password appropriately. The option is not available when the dialog is opened from the Login dialog and the password was not specified; or when the current session does not use a password authentication; or when [[security_credentials|the password was not stored nor remembered]]. | ||
| + | |||
| + | Check the //Initial directory// to include an initial remote directory into the %%URL%%. When the dialog is opened from the Login dialog, //Remote directory// as specified on the [[ui_login_directories|Advanced site settings dialog]] is used. When opened from the main window, the current working remote directory is used. The option is not available when generating an %%URL%% for selected file(s) as a path to the file(s) is used instead. | ||
| + | |||
| + | Check the //%%SSH%% host key// to [[session_url#hostkey|include an SSH host key fingerprint into the URL]]. The option is available for an SFTP and an SCP (SSH-based) sessions only. The option is not available, if no session was opened to the host as the host key is not known yet. Note that some (most) %%SSH%% clients need not understand a session %%URL%% that includes the host key fingerprint. | ||
| + | |||
| + | Check the //WinSCP-specific// to generate an [[integration_url#winscp|WinSCP-specific URL]]. Note that you need to enable the option with the WebDAV protocol, if you want WinSCP to handle the %%URL%%, as WinSCP [[integration_url#registering|never registers]] for the ''http'' protocol. | ||
| + | |||
| + | Check the //Save extension// to include a [[integration_url#save|save extension]] into the %%URL%%. As the extension is WinSCP-specific, the option //WinSCP-specific// should be selected along. | ||
| + | |||
| + | Check the //Advanced settings// to serialize all [[session_url#advanced|advanced site settings]] into the URL. As the generated syntax is WinSCP-specific, the option //WinSCP-specific// should be selected along. | ||
| + | |||
| + | The generated %%URL%%(s) is shown in the bottom box. When generating an %%URL%% for a site, only one %%URL%% is displayed. When generating an %%URL%% for a selected file(s), one %%URL%% per a file is displayed. | ||
| + | |||
| + | ===== [[script]] Script Tab ===== | ||
| + | Use the //Script tab// to generate a [[scripting|WinSCP script]] template for the session or the file transfer. | ||
| + | |||
| + | &screenshotpict(generateurl_script) | ||
| + | |||
| + | The script will include: | ||
| + | |||
| + | * the ''[[scriptcommand_open|open]]'' command with the [[session_url|session URL]] and all other switches needed to configure the session. | ||
| + | * (//When generating a code for a session//) a placeholder text to be replaced with [[scripting#commands|commands]]. | ||
| + | * (//When generating a code for a file transfer//) the ''[[scriptcommand_cd|cd]]'' and ''[[scriptcommand_lcd|lcd]]'' commands to navigate to the source and destination folders of the transfer and the ''[[scriptcommand_put|put]]'' or ''[[scriptcommand_get|get]]'' commands to actually transfer the files (with all needed switches to setup any non-default [[ui_transfer_custom|transfer settings]]). | ||
| + | * If you had all files selected in the source panel, a code to upload all files from the source directory will be generated. | ||
| + | * If you had only some files selected in the source panel, a code to upload only the selected files (but three at most) will be generated. If file names contain any [[file_mask#basic|file mask special characters]], they will be escaped. | ||
| + | * the ''[[scriptcommand_exit|exit]]'' command to end the script. | ||
| + | |||
| + | Use the //Format// to select a format of the script to generate: | ||
| + | |||
| + | * //Script file// -- Generates a script file template that you execute using the ''[[commandline#scripting|/script]]'' command-line switch. | ||
| + | * //Batch file// -- Generates a Windows batch file (''.bat'') template that executes the ''[[executables|winscp.com]]'' with the above commands, specified using the ''[[commandline#scripting|/command]]'' command-line switch. Additionally the batch file enables [[logging|session logging]] using the ''[[commandline#logging|/log]]'' switch and [[scripting#configuration|isolates the script run from a GUI configuration]] using the ''[[commandline#configuration|/ini=nul]]'' switch. At the end, the batch file [[scripting#result|checks WinSCP exit code]] to choose further actions to take; and propagates the WinSCP exit code to a batch file exit code using the ''exit /b'' command. //Make sure you keep the exact format of the multi-line ''winscp.com'' command, as [[faq_batch_file|multi-line batch file commands are fragile]].// | ||
| + | * //Command-line// -- Generates a command-line for the ''[[executables|winscp.exe]]'' (but usable for ''winscp.com'' too) with the above commands, session logging and configuration isolation (see the previous point). The command-line is suitable for task managers of all kinds, like [[guide_schedule|Windows Scheduler]] or [[guide_ssis|SSIS]]. Depending on your requirements, you may want prepend the ''[[commandline#scripting|/console]]'' switch to make the script console visible, while the script is running. | ||
| + | * //PowerShell script// -- Generates a PowerShell script file (''.ps1'') template that executes the ''[[executables|winscp.com]]'' with the above commands, specified using the ''[[commandline#scripting|/command]]'' command-line switch. Additionally the script file enables [[logging|session logging]] using the ''[[commandline#logging|/log]]'' switch and [[scripting#configuration|isolates the script run from a GUI configuration]] using the ''[[commandline#configuration|/ini=nul]]'' switch. At the end, the script file [[scripting#result|checks WinSCP exit code]] to choose further actions to take; and propagates the WinSCP exit code to a script exit code using the [[ps>microsoft.powershell.core/about/about_language_keywords#exit|''exit'' keyword]]. The script additionally sets [[ps>microsoft.powershell.core/about/about_preference_variables#psnativecommandargumentpassing|''$PSNativeCommandArgumentPassing'']] to ''"Legacy"'', what is needed for PowerShell 7.3 and newer to be able to pass the arguments properly to WinSCP.((You may want to reset the ''$PSNativeCommandArgumentPassing'' back to default ''"Windows"'' value after running WinSCP.)) //Instead of running ''winscp.com'', consider [[library_powershell|*]].// | ||
| + | |||
| + | In the //Command-line// (and possibly also in the //Batch file//), you should modify a path to [[logging|a session log file]] in the ''[[commandline#logging|/log]]'' switch. | ||
| + | |||
| + | The script will not include options to [[scripting#hostkey|verify a host key or an untrusted certificate]], if the session was not opened before yet. Open the session at least once, before generating the script. | ||
| + | |||
| + | You can click on script commands and switches and command-line switches to open their respective help pages. | ||
| + | |||
| + | ===== [[code]] .NET Assembly Code Tab ===== | ||
| + | Use the //.NET assembly tab// to generate a code template using [[library|WinSCP .NET assembly]] for the session or the file transfer. | ||
| + | |||
| + | &screenshotpict(generateurl_code) | ||
| - | Check //User name// to include username into %%URL%%. The option is not available when dialog is opened from Login dialog and user name was not specified; or (rarely) when current session did not require user name. | + | The code will: |
| - | Check //Password// to include password into %%URL%%. Make sure you protect %%URL%% that includes password appropriately. The option is not available when dialog is opened from Login dialog and password was not specified; or when current session does not use password authentication; or when [[security_credentials|password was not stored nor remembered]]. | + | * Set up ''[[library_sessionoptions|SessionOptions]]'' with all properties needed to configure the session. |
| + | * Create ''[[library_session|Session]]'' instance. | ||
| + | * Open the session using ''[[library_session_open|Session.Open]]'' | ||
| + | * //(When generating a code for a session)// Include a placeholder text to be replaced with calls to ''Session'' [[library_session#methods|methods]]. | ||
| + | * //(When generating a code for a file transfer)// Transfer files using ''[[library_session_putfiles|Session.PutFiles]]'' or ''[[library_session_getfiles|Session.GetFiles]]''. The ''[[library_transferoptions|TransferOptions]]'' class instance will be constructed and set up, if any non-default [[ui_transfer_custom|transfer settings]] are used. The ''[[library_operationresultbase#check|OperationResultBase.Check]]'' method will be called on results of the methods to [[library_session#results|throw an exception on any error]]. | ||
| + | * If you had all files selected in the source panel, a code to upload all files from the source directory will be generated. | ||
| + | ····* If you had only some files selected in the source panel, a code to upload only the selected files (but three at most) will be generated. If file names contain any [[file_mask#basic|file mask special characters]], the ''[[library_remotepath_escapefilemask|RemotePath.EscapeFileMask]]'' method will be called to escape them. | ||
| + | * Dispose the ''[[library_session|Session]]'' instance. | ||
| - | Check //%%SSH%% host key// to [[session_url#hostkey|include SSH host key fingerprint into URL]]. The option is available for SFTP and SCP (SSH-based) sessions only. The option is not available when the dialog is opened from Login dialog as the host key is not known before session is opened. Note that some (most) SSH clients need not understand session %%URL%% that includes host key fingerprint. | + | Use the //Language// to select a language to generate the template for. Available languages are C#, VB.NET and [[library_powershell|PowerShell]]. |
| - | Check //Initial directory// to include initial remote directory into %%URL%%. When opened from Login dialog, //Remote directory// as specified on [[ui_login_directories|Advanced site settings dialog]] is used. When opened from main window, the current working remote directory is used. The option is not available when generating %%URL%% for selected file(s) as path to the file(s) is used instead. | + | The code will not set properties to verify a host key (''[[library_sessionoptions#sshhostkeyfingerprint|SessionOptions.SshHostKeyFingerprint]]'') or an untrusted certificate (''[[library_sessionoptions#tlshostcertificatefingerprint|SessionOptions.TlsHostCertificateFingerprint]]''), if the session was not opened before yet. Open the session at least once, before generating the code. |
| - | Check //WinSCP-specific// to generate [[integration_url#winscp|WinSCP-specific URL]]. Note that you need to enable the option with WebDAV protocol, if you want WinSCP to handle the URL, as WinSCP [[integration_url#registering|never registers]] for ''http'' protocol. | + | You can click on classes, methods and properties to open their respective help pages. |
| - | Check //Save extension// to include [[integration_url#save|save extension]] into %%URL%%. As the extension is WinSCP-specific, option //WinSCP-specific// should be selected along. | + | ===== Copying Generated URL or Code to Clipboard ===== |
| - | ===== Generated URL ===== | + | Use //Copy to Clipboard// to copy generated %%URL%%(s) or code to a clipboard. |
| - | Generated %%URL%%(s) are shown in bottom box. When generating %%URL%% for site, only one %%URL%% is displayed. When generating %%URL%% for selected file(s), one %%URL%% per file is displayed. | + | |
| - | Use //Copy to Clipboard// to copy generated %%URL%%(s) to clipboard. | + | ===== Limitations ===== |
| + | WinSCP GUI cannot be aware of path limitations of your server. So even if your server requires you to start in a specific folder, WinSCP will not generate a code that will start in that folder. You need to add that manually. //See [[faq_root_path|*]]// | ||