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.
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.
RequireEncryptionGets or sets a value indicating whether encryption is required by the server.
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.

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.

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.

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.
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

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