Verbindungsoptionen für Microsoft. Data.SqlClient

Dieser Artikel listet alle Verbindungszeichenfolge-Schlüsselwörter auf, die Microsoft. Data.SqlClient akzeptiert. Jedes Schlüsselwort hat außerdem eine passende SqlConnectionStringBuilder Eigenschaft. Eine Einleitung, gängige Muster und Parsing-Regeln finden Sie unter Connection strings.

Schlüsselwörter und Aliase sind nicht großschreibungssensitiv. Wenn Sie einen Wert über eine Builder-Eigenschaft festlegen, schreibt der Builder das kanonische Schlüsselwort in die Rubrik Keyword .

Setze Optionen mit SqlConnectionStringBuilder

Beginnen Sie mit einer Basis-Verbindungszeichenfolge, die die Server-, Datenbank- und Authentifizierungseinstellungen enthält. Dann setze arbeitsbezogene Optionen über die Builder-Eigenschaften. Die .NET Framework-Tabs verwenden C# 7.3. Um ein Projekt zu erstellen, das die Beispiele ausführt, siehe Das Projekt erstellen.

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

using System;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task Main()
    {
        string connectionString =
            Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
            ?? throw new InvalidOperationException(
                "Set the SQL_CONNECTION_STRING environment variable.");

        var builder = new SqlConnectionStringBuilder(connectionString)
        {
            ApplicationName = "Orders.Worker",
            ConnectTimeout = 30,
            CommandTimeout = 60,
            MaxPoolSize = 50,
        };

        using (var connection = new SqlConnection(builder.ConnectionString))
        {
            await connection.OpenAsync();

            using (var command = new SqlCommand("SELECT APP_NAME();", connection))
            {
                Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
                Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
                Console.WriteLine($"Command timeout: {command.CommandTimeout}");
            }
        }
    }
}

Die Ausgabe lautet:

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

Ein neuer SqlCommand nimmt seinen Standard-Timeout aus dem Command Timeout Schlüsselwort seiner Verbindung.

Überprüfen Sie die Standardwerte

Ein neues SqlConnectionStringBuilder meldet den Standard für jede Option. Dieses Programm druckt die Standardwerte aus, die die meisten Anwendungen überprüfen:

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        var defaults = new SqlConnectionStringBuilder();

        Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
        Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
        Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
        Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
        Console.WriteLine($"Encrypt: {defaults.Encrypt}");
        Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
        Console.WriteLine($"Pooling: {defaults.Pooling}");
        Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
        Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
        Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
        Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
        Console.WriteLine($"Packet Size: {defaults.PacketSize}");
        Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
        Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
        Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
        Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
        Console.WriteLine($"Application Name: {defaults.ApplicationName}");
        Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
        Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");
    }
}

Auf .NET lautet die Ausgabe:

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True ist die Option Mandatory . Im .NET Framework lautet Framework Microsoft SqlClient Datenanbieterder Standardname der Anwendung .

Server- und Datenbankoptionen

Anwendungsidentitätsoptionen

Um zu melden, welches Framework oder Tool eine Verbindung eröffnet hat, verwenden Sie die Eigenschaft RegisteredApplication . Es gibt kein Verbindungszeichenfolge-Stichwort. Weitere Informationen finden Sie unter Meldung der Anwendungsidentität.

Authentifizierungsoptionen

Authentication akzeptiert diese Werte. Der Bauer schreibt sie ohne Leerzeichen, wie ActiveDirectoryDefault, und der Parser akzeptiert beide Formen.

Microsoft Entra ID-Methoden benötigen das PaketMicrosoft.Data.SqlClient.Extensions.Azure. Für Einrichtung und Beispiele siehe Microsoft Entra ID Authentication und SQL Server authentication.

Verschlüsselungsoptionen

Für die vollständigen Validierungsregeln siehe Verschlüsselung und Zertifikatsvalidierung.

Immer verschlüsselte Optionen

Netzwerkoptionen

Ein prozessweiter AppContext-Wechsel kann den Multi Subnet Failover Standard auf true. Weitere Informationen finden Sie unter AppContext switches in SqlClient.

Auszeitoptionen

Connect Timeout schränkt die Abfrageausführung nicht ein. Command Timeout Es schränkt das Login oder das Warten auf eine Pool-Verbindung nicht ein. Leite a CancellationToken an asynchrone Anrufe weiter, damit der Anrufer nicht mehr warten kann, bevor eine der Timeouts abläuft.

Verbindungswiederherstellungsoptionen

Wenn Connect Retry Count , 1der Standard ist, verwendet 2 der Treiber für Azure SQL-Endpunkte und 5 für Azure Synapse Analytics serverlose SQL-Pool-Endpunkte, wenn er eine unterbrochene Idle-Verbindung wiederherstellt. Die erste Öffnung verwendet den Wert als festgelegt, sodass standardmäßig ein erneuter Versuch an jedem Endpunkt erlaubt. Der Treiber verwendet in beiden Fällen jeden anderen Wert als gesetzt.

Diese Schlüsselwörter versuchen keinen Befehl erneut, der während der Ausführung fehlschlägt. Um den eingebauten Versuch für eine Öffnung zu überspringen, ruft man eine Open Überlastung mit OpenWithoutRetryauf. Für benutzerdefinierte Richtlinien siehe Konfigurierbare Wiederholungslogik. Versuche einen Befehl nur, wenn es sicher ist, ihn zu wiederholen.

Optionen für das Pooling

Jeder einzelne Verbindungszeichenfolge erhält seinen eigenen Pool. Für Poolschlüssel, Löschen und Leerlaufzeit siehe SQL Server Connection Pooling.

Transaktions- und Sitzungsoptionen

.NET Framework nur Optionen

Diese Schlüsselwörter werden nur im .NET Framework akzeptiert. Auf .NET wirft NotSupportedException der Builder und SqlConnection wirft ArgumentException.

Nicht unterstützte Schlüsselwörter

Validierungsregeln

SqlConnectionStringBuilder Lehnt unbekannte Schlüsselwörter und viele ungültige Werte ab, wenn man sie setzt. SqlConnectionführt weitere Prüfungen durch, wenn man seine Verbindungszeichenfolge einstellt, einschließlich einzelner Werte, die der Builder akzeptiert, und Kombinationen von Schlüsselwörtern. Ein String, den der Builder akzeptiert, kann trotzdem ausfallen, wenn du die Verbindung aufbaust.

Der Erbauer und die Verbindung verwerfen diese Werte mit ArgumentException:

• Connect Timeout, Command Timeout, , , Connection Idle Timeout, oder Min Pool SizeLoad Balance Timeoutweniger als 0.
• Max Pool Size weniger als 1.
• Packet Size außerhalb von 512 bis 32.768.
• Connect Retry Count Draußen 0 bis 255.
• Connect Retry Interval Außerhalb von 1 bis 60.
• Ein Schlüsselwort, das in diesem Artikel nicht vorkommt.

SqlConnection lehnt diese Werte auch mit ArgumentExceptionab, obwohl der Erbauer sie akzeptiert:

• Type System Versionaußer Latest, , , SQL Server 2008, oder SQL Server 2005SQL Server 2012.
• Transaction Binding außer oder Implicit UnbindExplicit Unbind.
• Ein Wert, der länger ist als das TDS-Limit für Application Name, Current Language, , Data SourceFailover Partner, Initial Catalog, PasswordUser ID, Workstation ID, , oder AttachDBFilename.

SqlConnectionLehnt diese Kombinationen außerdem mit ab :ArgumentException

• Min Pool Size größer als Max Pool Size.
• Failover Partner ohne Initial Catalog.
• Failover Partner mit Multi Subnet Failover=true, User Instance=trueoder Application Intent=ReadOnly.
• Authentication durch Integrated Security=true.
• Passwordmit Active Directory Integrated, , , Active Directory Managed Identity, Active Directory MSI, Active Directory Default, oder Active Directory Workload IdentityActive Directory Interactive.
• User ID oder Password mit Active Directory Device Code Flow.

Optionsänderungen überprüfen

Bevor Sie eine Option in der Produktion ändern:

1. Notiere den aktuellen Verbindungszeichenfolge, die Treiberversion, den Endpunkttyp und das Problem, das du lösen möchtest.
2. Ändere eine Option nach der anderen.
3. Testen Sie den Verbindungsaufbau, die Authentifizierung, die Zertifikatsvalidierung, das Pooling, das Failover, den Abbruch und die Abfrageausführung.
4. Messen Sie die Verbindungslatenz, Pool-Wartezeiten und Fehlerzahlen.
5. Bestätigen Sie die Einstellung auf jeder bereitgestellten Instanz.

Ein geänderter Verbindungszeichenfolge erzeugt einen neuen Pool. Während eines gestuften Rollouts existieren alte und neue Pools gleichzeitig, sodass die Gesamtzahl der physischen Verbindungen zum Server steigen kann.

Verwandte Inhalte

• Verbindungszeichenfolgen
• Verbindungszeichenfolgen-Generatoren
• Mit einer Datenquelle verbinden
• SQL Server-Verbindungspooling
• Verschlüsselung und Zertifikatüberprüfung