This is an old revision of the document!

Documentation » .NET Assembly »

SessionOptions Class

Defines information to allow an automatic connection and authentication of the session. Is used with the Session.Open and Session.ScanFingerprint methods.

You can have WinSCP generate a code template for SessionOptions for you.

Advertisement

Syntax

Namespace: WinSCP

C#
public sealed class SessionOptions
VB.NET
Public NotInheritable Class SessionOptions

Constructors

Name Description
SessionOptions() Default constructor.

Properties

Name Description
FtpMode FtpMode FTP mode. Possible values are FtpMode.Passive (default) and FtpMode.Active.
FtpSecure FtpSecure FTPS mode. Possible values are FtpSecure.None (default), FtpSecure.Implicit and FtpSecure.Explicit.
bool GiveUpSecurityAndAcceptAnySshHostKey Give up security and accept any SSH host key. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. To maintain security, use SshHostKeyFingerprint. Obsoleted, use SshHostKeyPolicy.GiveUpSecurityAndAcceptAny instead.
bool GiveUpSecurityAndAcceptAnyTlsHostCertificate Give up security and accept any FTPS/WebDAVS server TLS/SSL certificate. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. To maintain security, use TlsHostCertificateFingerprint.
string HostName Name or IP of the host to connect to. Mandatory property. In a form of example.com or 192.0.2.0.
string Name Returns a generated name of a session, based on available information – typically UserName@HostName. Read-only.
string NewPassword When set, tries to change password to the new one.
string Password Password for authentication.
int PortNumber Port number to connect to. Keep default 0 to use the default port for the protocol.
string PrivateKeyPassphrase Passphrase for encrypted private keys and client certificates.
Protocol Protocol Protocol to use for the session. Possible values are Protocol.Sftp (default), Protocol.Scp, Protocol.Ftp, Protocol.Webdav and Protocol.S3.
string RootPath WebDAV root path or S3 bucket path. Set, when the HTTP server root or S3 bucket list is not accessible.
bool Secure Use encrypted connection (TLS/SSL) with WebDAV or S3. Default is false for WebDAV and true for S3. This feature is available only in the latest beta release. In the stable release, use WebdavSecure.
SecureString SecureNewPassword When set, tries to change password to the new one. Use instead of NewPassword to reduce a number of unencrypted copies of the password in memory.
SecureString SecurePassword Encrypted password for authentication. Use instead of Password to reduce a number of unencrypted copies of the password in memory.
SecurePrivateKeyPassphrase SecurePrivateKeyPassphrase Encrypted passphrase for encrypted private keys and client certificates. Use instead of PrivateKeyPassphrase to reduce a number of unencrypted copies of the passphrase in memory.
string SshHostKeyFingerprint Fingerprint of SSH server host key (or several alternative fingerprints separated by semicolon). It makes WinSCP automatically accept host key with the fingerprint. Use SHA-256 fingerprint of the host key. Mandatory for SFTP/SCP protocol.1 If multiple host keys are required due to the presence of a load balancer the host keys need to be separated by a semi-colon ; Learn how to obtain host key fingerprint.
SshHostKeyPolicy SshHostKeyPolicy SSH host key policy. Use the default SshHostKeyPolicy.Check to verify the host key against SshHostKeyFingerprint. Use SshHostKeyPolicy.GiveUpSecurityAndAcceptAny to give up a security and accept any SSH host key. To be used in exceptional situations only, when security is not required. When set, log files will include warning about insecure connection. Use SshHostKeyPolicy.AcceptNew to automatically accept host key of new hosts. The known keys are cached in registry.
string SshPrivateKey SSH Private key file contents.
string SshPrivateKeyPath Full path to SSH private key file.
string TlsClientCertificatePath Full path to TLS/SSL client certificate.
string TlsHostCertificateFingerprint Fingerprint of FTPS/WebDAVS server TLS/SSL certificate to be automatically accepted (useful for certificates signed by an untrusted authority). Use SHA-256 fingerprint of the certificate.
TimeSpan Timeout Server response timeout. Defaults to 15 seconds.
int TimeoutInMilliseconds Alternative to Timeout. Particularly useful for COM hosts, that cannot use TimeSpan, such as Visual Basic.
string UserName Username for authentication. Mandatory property.
bool WebdavSecure Obsolete. Use Secure.

Advertisement

Methods

Name Description
AddRawSettings Allows configuring any site settings using raw format as in an INI file.
ParseUrl Parses session URL into its components.
ToString Returns Name. (Overrides Object.ToString().)

Remarks

When using the SessionOptions instance with the Session.Open, you need to fill in all properties required to connect and authenticate your session automatically.

You always need to fill in Protocol, HostName and UserName.2

In most cases you need to fill in Password. Exceptions are:

  • You use different authentication method than a password authentication, such as public key authentication for SSH session;
  • The server does not require password.

For SSH (SFTP/SCP) session you need to fill in the SshHostKeyFingerprint to verify the expected server host key.

Example

See overall example for WinSCP .NET assembly or any other example.

  1. You can leave the property null, if you set SshHostKeyPolicy to a different value than SshHostKeyPolicy.Check.Back
  2. Except for very rare occasions that the server does not require username.Back

Last modified: by 123.3.140.251

Documentation

Support

Associations

Follow Us