Incompatible Changes Between Versions

This is a summary of rare incompatible changes between versions of WinSCP, since 5.0 (August 2011).

With some changes, possible remedies are included.

The changes that most commonly causes issues are highlighted.

In the Last Major Release 5.13 (after December 2017)
- General
- Scripting and .NET Assembly
In Older Releases (August 2011 - December 2017)

In the Last Major Release 5.13 (after December 2017)

General

5.12: Last access time of downloaded files is no longer preserved. Note that modification time is still preserved.

Scripting and .NET Assembly

5.12: XML log tags <modification> and <permisssions> are absent, if their values are not known. Previously they would have value of 1899-12-30T01:00:00.000Z and --------- respectively. Consequently the .NET assembly RemoteFileInfo.LastWriteTime and RemoteFileInfo.FilePermissions have values DateTime.MinValue and null, respectively.
5.12: Scripting command mv and .NET assembly function Session.MoveFile tests, if a source file exists, before trying to rename. Consequently, an error message reported has changed significantly, if the source file does not exist.
5.12.1: .NET assembly instance methods Session.EscapeFileMask, Session.CombinePaths, Session.TranslateLocalPathToRemote and Session.TranslateRemotePathToLocal replaced by static methods of the same name in class RemotePath.
5.12.1: Session.ScanFingerprint has a new mandatory algorithm parameter. To keep the previous behavior use MD5 as a parameter value (though for new development, use SHA-256).

In Older Releases (August 2011 - December 2017)

General

5.10: Invalid size constraints in file mask will now fail the operation. Previously, invalid size constraints were ignored.
5.9.3: Not updating last access time of uploaded files with SFTP protocol to avoid problems with servers that do not support it. Previously last access time was updated. 1485
5.8.3: By default, warning is issued when using Diffie-Hellman group 1 key exchange algorithm. If you need this key exchange algorithm, in scripting use open … -rawsetting KEX=ecdh,dh-gex-sha1,dh-group14-sha1,rsa,dh-group1-sha1,WARN, in .NET assembly use SessionOptions.AddRawSettings("KEX", "ecdh,dh-gex-sha1,dh-group14-sha1,rsa,dh-group1-sha1,WARN"). See raw site settings.
5.8.3: Fallback between SSH versions is not supported anymore. This should not have any impact, as SSH-1 is not used anymore.
5.8.3: Port number is considered for site-specific caches and bookmarks. You will lose bookmarks for sites that use a non-standard port number. 1411
5.8: Using UTF-8 for strings (such as password) with SSH protocol. If your SSH password contains non-ASCII characters, and you were able to connect with previous versions of WinSCP, it means that your server does not comply with SSH specification (as older versions of WinSCP did not). You will not be able to login with the new version of WinSCP. Change your password to ASCII characters only as a workaround. 1014
5.6.4: Considering directories to have zero size, when matching file masks or sorting by size, even when the server reports size for the directory, to achieve consistent behavior.
5.2.5: Using UTF-8 for strings (such as file names) with SFTP protocol by default even for version 3 and lower. If your server does not use UTF-8, you can revert to the previous behavior by setting the UTF-8 encoding for filenames to Off. 1072
5.0.7: Blowfish is preferred SSH encryption cipher. 1
5.0.6: File mask that does not end with slash matches only files, not directories anymore.
5.0.6: Include directory masks are recursive.
5.0.6: Include file mask that does not contain any directory mask matches any directory.
5.0.6: Special characters ;,|<> in file masks can be used as literals by doubling them.
5.0.2: Binary transfer mode is default. 670
5.0.2: With FTP protocol, passive mode is used by default. 165

GUI

5.8.2: Remote custom commands cannot be executed with focus on local panel. Make sure you have the remote panel focused, when executing a remote custom command.
5.8: Interface theme is not configurable anymore. Only single theme is supported.
5.8: Change of language on run-time is not supported anymore.
5.8: Shortcut of command Clear Selection changed to Shift+Ctrl+L.
5.2: Session from command-line and/or from jump list is opened by default using existing WinSCP instance. To revert to the previous behavior, use the Open new externally initiated sessions in existing window. 769
5.0.6: Include/Exclude mask in transfer settings replaced with File mask, what is equivalent of Include mask (as supported already previously, it can contain exclude mask after |).
5.0.6: Session option Remember last used directory is enabled by default.
5.0.3: Synchronized browsing state is stored with stored session, not in preferences. 10
5.0.3: In mouse-only Explorer-style selection mode, single-file implicit mouse-selection is not preserved, when focus/selection is subsequently changed using keyboard.

Scripting and .NET Assembly

5.10: When executing script file or script commands provided on command-line, default reconnect time is set to 120 seconds, if not limited yet by configuration. Previously, WinSCP tried to reconnect indefinitely by default. To revert to the previous behavior, in scripting use option reconnecttime 0, in .NET assembly use Session.ReconnectTime = TimeSpan.MaxValue.
5.10: Change: Deprecating Session.DisableVersionCheck. Always use the same version of WinSCP and WinSCP .NET assembly.
5.9.1: Session.EnumerateRemoteFiles does not throw when reading subdirectory fails. To capture errors, use the Session.Failed event.
5.8.3: A complete remote error message is stored into a single instance of SessionRemoteException, instead of separating error details into an inner exception. This should have any impact only, if your code checks for specific error message in inner exception. This is not recommended though.
5.8.1: Deprecating Session.IniFilePath in favor of Session.AddRawConfiguration. You can generate a code template with the AddRawConfiguration calls.
5.8: Script file has to be in UTF-8 encoding. This matter only if you use non-ASCII characters in filenames and/or credentials. If you are you will get error message No mapping for the Unicode character exists in the target multi-byte code page - The file must be in UTF-8 or UTF-16 encoding.
5.8. The RemoteFileInfo.Name now contains a name only, even for a RemoteFileInfo instance returned by the Session.GetFileInfo.
5.8: Deprecating Session.DefaultConfiguration in favor of Session.AddRawConfiguration. You can generate a code template with the AddRawConfiguration calls.
5.8: SessionOptions.SshPrivateKeyPassphrase renamed to SessionOptions.PrivateKeyPassphrase.
5.6.5: Session.CalculateFileChecksum method returns a byte array instead of a string to match .NET framework cryptography functions.
5.6.3: lls by default only displays a notification that no matching file is found, instead of failing.
5.6.2: A .NET assembly method Session.ExecuteCommand does not throw an exception on error. Instead a CommandExecutionResult now descends from a OperationResultBase. Use the OperationResultBase.Check method to reproduce the previous behavior.
5.6: When executing script file or script commands provided on command-line, default batch mode is abort and confirmations are turned off. Use option batch off and option confirm on at the beginning of your script to revert to the previous defaults. Though the new defaults were always recommended values to be used in the scripts.
5.6: Enabling batch mode in scripting automatically limits reconnect time to 120 seconds, if it is not limited yet. To revert to the previous behavior, in scripting use option reconnecttime 0, in .NET assembly use Session.ReconnectTime = TimeSpan.MaxValue. 1173
5.6: When host key does not match fingerprint specified on command line or in script, user is not prompted to verify the host key and connection is abandoned with meaningful error message. 1186
5.2.5: Symbol ; has special meaning in session URL and has to be URL-encoded to %3B, when used as a literal.
5.2.5: UTF-8 encoded characters in session URL are supported. If you were using non-ASCII URL-encoded characters in the session URL, you need to re-code them to UTF-8. 1062
5.2.3: In .NET assembly, SessionOptions class properties SslHostCertificateFingerprint and GiveUpSecurityAndAcceptAnySslHostCertificate renamed to TlsHostCertificateFingerprint and GiveUpSecurityAndAcceptAnyTlsHostCertificate, respectively.
5.0.9: In .NET assembly SessionOptions class property SshHostKey renamed to SshHostKeyFingerprint, SshPrivateKey to SshPrivateKeyPath and SslCertificate to SslHostCertificateFingerprint (and later to TlsHostCertificateFingerprint).
5.0.8: Scripting command rm and .NET assembly Session.RemoveFiles method can remove directories as well. 887
5.0.6: Script options exclude and include deprecated in favor of -filemask=<mask> switch of get, put, synchronize and keepuptodate commands.
5.0.6: Script option transfer deprecated in favor of -transfer switch of get, put, synchronize and keepuptodate commands.
5.0.6: Escaping new lines in attribute values in XML log (particularly useful for attribute value of output and erroroutput).
5.0.3: All fatal errors (those that cause exit code of WinSCP to be 1) in scripting are recorded in new subtag failure of root tag session in XML log. This includes connection errors, replacing previous recording in result tag.
5.0.3: Value both of synchronize command switch criteria renamed to either to avoid confusion (both is still recognized for backward compatibility). 195
5.0.3: Silently ignoring, when local file mask in put command matches no file. To revert to the previous behavior, use the option failonnomatch on before the put command. 746
5.0.2: Connection error is recorded in XML log in new subtag result of root tag session. 545