TdsServerOptions Class
Configuration options for the TDS server.
public sealed class TdsServerOptionsConstructors
| Name | Description |
|---|---|
| TdsServerOptions() |
TdsServerOptions()
TdsServerOptions.cspublic TdsServerOptions()No documentation is available.
Properties
| Name | Description |
|---|---|
| BulkLoadHandler | Gets or sets the handler of the bulk loads sent by SqlBulkCopy. |
| DefaultServerVersion | Gets the default value of TdsServerOptions.ServerVersion, the version of SQL Server 2022 (16.0.1000.6). |
| MaxMessageSize | Gets or sets the maximum size, in bytes, of a single inbound TDS message. |
| PacketSize | Gets or sets the packet size used when writing TDS packets. |
| ProgramName | Gets or sets the program name the server sends to the clients when they log in. |
| RequireEncryption | Gets or sets a value indicating whether encryption is required by the server. |
| ServerVersion | Gets or sets the version the server reports to the clients. |
| SqlServerBrowser | Gets or sets the SQL Server Browser responder options, or null to disable the responder. |
| TlsPemCertificatePath | Gets or sets the path to a PEM certificate file used for TLS. |
| TlsPemPrivateKeyPath | Gets or sets the path to a PEM private key file used for TLS. |
| TlsPfxPassword | Gets or sets the password used to open the PFX certificate file. |
| TlsPfxPath | Gets or sets the path to a PFX certificate file used for TLS. |
| TransactionHandler | Gets or sets the callback invoked when a client begins, commits or rolls back a transaction, or creates a savepoint. |
BulkLoadHandler
TdsServerOptions.csGets or sets the handler of the bulk loads sent by SqlBulkCopy.
public TdsBulkLoadHandler? BulkLoadHandler { get; set; }Property value
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.csGets the default value of TdsServerOptions.ServerVersion, the version of SQL Server 2022 (16.0.1000.6).
public static Version DefaultServerVersion { get; }Property value
MaxMessageSize
TdsServerOptions.csGets or sets the maximum size, in bytes, of a single inbound TDS message.
public int MaxMessageSize { get; set; }Property value
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.
PacketSize
TdsServerOptions.csGets or sets the packet size used when writing TDS packets.
public int PacketSize { get; set; }Property value
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.
ProgramName
TdsServerOptions.csGets or sets the program name the server sends to the clients when they log in.
public string ProgramName { get; set; }Property value
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.csGets or sets a value indicating whether encryption is required by the server.
public bool RequireEncryption { get; set; }Property value
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.csGets or sets the version the server reports to the clients.
public Version ServerVersion { get; set; }Property value
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.csGets or sets the SQL Server Browser responder options, or null to disable the responder.
public TdsSqlServerBrowserOptions? SqlServerBrowser { get; set; }Property value
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.csTlsPemPrivateKeyPath
TdsServerOptions.csTlsPfxPassword
TdsServerOptions.csTlsPfxPath
TdsServerOptions.csTransactionHandler
TdsServerOptions.csGets 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
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
| Name | Description |
|---|---|
| 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.csAdds a TCP listener.
public TdsServerOptions AddTcpListener(int port = 1433, IPAddress? bindAddress = null)Parameters
portint- TCP port to listen on.
bindAddressIPAddress?- Address to bind to. Defaults to loopback.
Returns
TdsServerOptions The current options instance.
EnableSqlServerBrowser(string, int, IPAddress?)
TdsServerOptions.csEnables 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
instanceNamestring- The instance name to advertise.
portint- UDP port to listen on. Clients only query
TdsSqlServerBrowserOptions.DefaultPort. bindAddressIPAddress?- Address to bind to. Defaults to loopback.
Returns
TdsServerOptions The current options instance.
Constants
| Name | Description |
|---|---|
| DefaultMaxMessageSize | The default value of TdsServerOptions.MaxMessageSize. |
| DefaultProgramName | The default value of TdsServerOptions.ProgramName, the name SQL Server reports. |
| MaximumPacketSize | The largest packet size a TDS packet header can describe, since it stores the length in 16 bits. |
| MinimumPacketSize | The smallest packet size a TDS client is required to support. |
DefaultMaxMessageSize
The default value of TdsServerOptions.MaxMessageSize.
public const int DefaultMaxMessageSize = 16777216DefaultProgramName
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 = 65535MinimumPacketSize
The smallest packet size a TDS client is required to support.
public const int MinimumPacketSize = 512