TdsServerOptions Class

Configuration options for the TDS server.

public sealed class TdsServerOptions

Constructors

NameDescription
TdsServerOptions()

TdsServerOptions()

TdsServerOptions.cs
public TdsServerOptions()

No documentation is available.

Properties

NameDescription
BulkLoadHandlerGets or sets the handler of the bulk loads sent by SqlBulkCopy.
DefaultServerVersionGets the default value of TdsServerOptions.ServerVersion, the version of SQL Server 2022 (16.0.1000.6).
MaxMessageSizeGets or sets the maximum size, in bytes, of a single inbound TDS message.
PacketSizeGets or sets the packet size used when writing TDS packets.
ProgramNameGets or sets the program name the server sends to the clients when they log in.
RequireEncryptionGets or sets a value indicating whether encryption is required by the server.
ServerVersionGets or sets the version the server reports to the clients.
SqlServerBrowserGets or sets the SQL Server Browser responder options, or null to disable the responder.
TlsPemCertificatePathGets or sets the path to a PEM certificate file used for TLS.
TlsPemPrivateKeyPathGets or sets the path to a PEM private key file used for TLS.
TlsPfxPasswordGets or sets the password used to open the PFX certificate file.
TlsPfxPathGets or sets the path to a PFX certificate file used for TLS.
TransactionHandlerGets or sets the callback invoked when a client begins, commits or rolls back a transaction, or creates a savepoint.

BulkLoadHandler

TdsServerOptions.cs

Gets or sets the handler of the bulk loads sent by SqlBulkCopy.

public TdsBulkLoadHandler? BulkLoadHandler { get; set; }

Property value

TdsBulkLoadHandler?

Remarks

When this is null, the requests that SqlBulkCopy sends to read the destination table go to the query handler, and its rows are rejected with the error 50001.

DefaultServerVersion

TdsServerOptions.cs

Gets the default value of TdsServerOptions.ServerVersion, the version of SQL Server 2022 (16.0.1000.6).

public static Version DefaultServerVersion { get; }

Property value

Version

MaxMessageSize

TdsServerOptions.cs

Gets or sets the maximum size, in bytes, of a single inbound TDS message.

public int MaxMessageSize { get; set; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is smaller than TdsServerOptions.MaximumPacketSize.

Remarks

A TDS message is made of as many packets as the client decides to send, and the server has to buffer the whole message before it can be parsed. This limit bounds that buffer. It applies from the very first packet of a connection, so it also bounds what an unauthenticated client can make the server allocate. Raise it when clients legitimately send large parameters or SQL batches. Must be at least TdsServerOptions.MaximumPacketSize so that a single full packet always fits.

Gets or sets the packet size used when writing TDS packets.

public int PacketSize { get; set; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is outside the supported range.

Remarks

Must be between TdsServerOptions.MinimumPacketSize and TdsServerOptions.MaximumPacketSize. The TDS packet header stores the packet length in 16 bits, so a larger value cannot be represented on the wire.

Gets or sets the program name the server sends to the clients when they log in.

public string ProgramName { get; set; }

Property value

string

Exceptions

ArgumentException
The value is empty.
ArgumentNullException
The value is null.
ArgumentOutOfRangeException
The value is longer than 255 characters.

Remarks

Must contain between 1 and 255 characters.

RequireEncryption

TdsServerOptions.cs

Gets or sets a value indicating whether encryption is required by the server.

public bool RequireEncryption { get; set; }

Property value

bool

Remarks

When this is false and no TLS certificate is configured, the server answers PRELOGIN with NOT_SUPPORTED, and clients that allow it (for example Encrypt=Optional) log in over an unencrypted connection. The LOGIN7 password is then protected only by the TDS nibble-swap and XOR obfuscation, which is trivially reversible by anyone on the network path. Configure TdsServerOptions.TlsPfxPath or the PEM options for any deployment that is not loopback-only.

ServerVersion

TdsServerOptions.cs

Gets or sets the version the server reports to the clients.

public Version ServerVersion { get; set; }

Property value

Version

Exceptions

ArgumentNullException
The value is null.
ArgumentOutOfRangeException
A part of the version is too large to be sent to the clients.

Remarks

Clients and tools read this version to know which features the server supports, and some of them reject servers that report an old version. The default value is the version of SQL Server 2022.

The login response only contains the major, minor and build numbers, so SqlConnection.ServerVersion reports 16.00.1000 for the default value. The SQL Server Browser responder reports the full version. The major and minor numbers must be at most 255, and the build number at most 65535.

SqlServerBrowser

TdsServerOptions.cs

Gets or sets the SQL Server Browser responder options, or null to disable the responder.

public TdsSqlServerBrowserOptions? SqlServerBrowser { get; set; }

Property value

TdsSqlServerBrowserOptions?

Remarks

The responder answers the SQL Server Resolution Protocol on UDP, so clients can connect with an instance name (host\INSTANCE) instead of host,port. It advertises the port of the first TCP listener.

TlsPemCertificatePath

TdsServerOptions.cs

Gets or sets the path to a PEM certificate file used for TLS.

public string? TlsPemCertificatePath { get; set; }

Property value

string?

TlsPemPrivateKeyPath

TdsServerOptions.cs

Gets or sets the path to a PEM private key file used for TLS.

public string? TlsPemPrivateKeyPath { get; set; }

Property value

string?

TlsPfxPassword

TdsServerOptions.cs

Gets or sets the password used to open the PFX certificate file.

public string? TlsPfxPassword { get; set; }

Property value

string?

Gets or sets the path to a PFX certificate file used for TLS.

public string? TlsPfxPath { get; set; }

Property value

string?

TransactionHandler

TdsServerOptions.cs

Gets or sets the callback invoked when a client begins, commits or rolls back a transaction, or creates a savepoint.

public TdsTransactionDelegate? TransactionHandler { get; set; }

Property value

TdsTransactionDelegate?

Remarks

The server accepts transaction requests without a handler, so SqlConnection.BeginTransaction works even when nothing tracks transactions. Set it to observe the transactions, or to reject a request by returning an error. When a connection closes with an active transaction, the handler is called with a rollback request whose TdsTransactionContext.IsConnectionClosing is true.

Methods

NameDescription
AddTcpListener(int, IPAddress?)Adds a TCP listener.
EnableSqlServerBrowser(string, int, IPAddress?)Enables the SQL Server Browser responder, so clients can connect with an instance name (host\INSTANCE).

AddTcpListener(int, IPAddress?)

TdsServerOptions.cs

Adds a TCP listener.

public TdsServerOptions AddTcpListener(int port = 1433, IPAddress? bindAddress = null)

Parameters

port int
TCP port to listen on.
bindAddress IPAddress?
Address to bind to. Defaults to loopback.

Returns

TdsServerOptions The current options instance.

EnableSqlServerBrowser(string, int, IPAddress?)

TdsServerOptions.cs

Enables the SQL Server Browser responder, so clients can connect with an instance name (host\INSTANCE).

public TdsServerOptions EnableSqlServerBrowser(string instanceName, int port = 1434, IPAddress? bindAddress = null)

Parameters

instanceName string
The instance name to advertise.
port int
UDP port to listen on. Clients only query TdsSqlServerBrowserOptions.DefaultPort.
bindAddress IPAddress?
Address to bind to. Defaults to loopback.

Returns

TdsServerOptions The current options instance.

Constants

NameDescription
DefaultMaxMessageSizeThe default value of TdsServerOptions.MaxMessageSize.
DefaultProgramNameThe default value of TdsServerOptions.ProgramName, the name SQL Server reports.
MaximumPacketSizeThe largest packet size a TDS packet header can describe, since it stores the length in 16 bits.
MinimumPacketSizeThe smallest packet size a TDS client is required to support.

DefaultMaxMessageSize

The default value of TdsServerOptions.MaxMessageSize.

public const int DefaultMaxMessageSize = 16777216

DefaultProgramName

The default value of TdsServerOptions.ProgramName, the name SQL Server reports.

public const string DefaultProgramName = "Microsoft SQL Server"

MaximumPacketSize

The largest packet size a TDS packet header can describe, since it stores the length in 16 bits.

public const int MaximumPacketSize = 65535

MinimumPacketSize

The smallest packet size a TDS client is required to support.

public const int MinimumPacketSize = 512