Differences
This shows you the differences between the selected revisions of the page.
| ui_generateurl 2015-12-18 | ui_generateurl 2024-12-10 (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: |
| - | * //Session > Generate %%URL%%// command on main window to generate session %%URL%% for current session. | + | * //Tabs > Generate Session %%URL%%/Code// command on the main window to generate session %%URL%% or code template for the current session. (preferred) |
| - | * //Manage > Generate %%URL%%// command on [[ui_login|Login dialog]] to generate session %%URL%% for selected site (this approach will not include host key fingerprint for SFTP/SCP sessions needed for scripting/.NET assembly). | + | * //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 //(This limitation is removed in the latest beta version)//. &beta 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|*]]// | ||