Verbindungszeichenfolgen für Microsoft.Data.SqlClient

Eine Microsoft.Data.SqlClient-Verbindungszeichenfolge ist eine Liste von keyword=value Paaren, die durch Semikolons getrennt sind. Geben Sie es an SqlConnection oder SqlConnectionStringBuilder:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

Ein Verbindungszeichenfolge beantwortet vier Fragen:

1. Welchen Server und welche Datenbank verwendet die Anwendung?
2. Mit welcher Identität läuft die Anwendung?
3. Wie validiert der Client das Serverzertifikat?
4. Welches Verbindungsverhalten benötigt die Arbeitslast?

Dieser Artikel behandelt diese Entscheidungen und die Regeln, die der Treiber zum Lesen des Textes verwendet. Für jedes Schlüsselwort, seine Synonyme und seinen Standard siehe Verbindungsoptionen. Um Verbindungsstrings im Code zu erstellen und zu ändern, siehe Connection string builders.

Wählen Sie ein Authentifizierungsmuster

Verwenden Sie das Muster, das zum Einsatz passt. Ersetzen Sie jeden Platzhalter, wie <server>, durch Ihren Wert.

Die integrierte Windows-Authentifizierung stellt die Verbindung unter der Identität des Prozesses her. Bei einer Desktop- oder Konsolenanwendung ist das meist der angemeldete Nutzer. Bei einer Webanwendung oder einem Windows-Dienst ist es der Anwendungspool oder das Servicekonto. Identitätsübernahme kann die Identität verändern. Gewähren Sie der Identität, die Ihre Anwendung tatsächlich verwendet, eine Anmeldung und Datenbankberechtigungen.

Diese drei Formen der integrierten Windows-Authentifizierung sind äquivalent:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Wenn in einer Zeichenfolge Integrated Security=true sowie User ID und Password festgelegt sind, verwendet der Treiber die Windows-Authentifizierung und ignoriert den Benutzernamen und das Passwort.

Microsoft. Data.SqlClient 7.0 und spätere Versionen benötigen das versionsangepasste Microsoft.Data.SqlClient.Extensions.Azure Paket für die vom Treiber bereitgestellten Microsoft Entra ID-Authentifizierungsmethoden. Du brauchst dieses Paket nicht, wenn der Anwendungscode ein Zugangstoken oder einen Access-Token-Callback liefert.

Für die akzeptierten Authentication Werte siehe Authentifizierungsoptionen. Die Authentifizierung erfordert außerdem Datenbankbenutzer, Berechtigungen und Identitätskonfiguration auf dem Server. Für die Einrichtungsschritte siehe Microsoft Entra ID-Authentifizierung und SQL Server-Authentifizierung.

Spezifizieren Sie Server und Datenbank

Server und Database sind die am besten lesbaren Schlüsselwortnamen. Der Erbauer schreibt sie als ihre kanonischen Entsprechungen, Data Source und Initial Catalog. Alle vier Namen funktionieren in einem Verbindungszeichenfolge.

Setzen Sie Server auf eine dieser Formen:

Verwenden Sie tcp:, einen vollständig qualifizierten Hostnamen und einen expliziten Port in der Produktion. Verwenden Sie einen DNS-Namen, der mit dem Serverzertifikat übereinstimmt, nicht mit einer IP-Adresse, da die Zertifikatsvalidierung den Servernamen in der Verbindungszeichenfolge mit den Namen im Zertifikat vergleicht.

Wenn Sie sich mit der Azure SQL-Datenbank mit SQL-Authentifizierung und einem Benutzernamen im Formular user@servernameverbinden, muss das servername Teil mit dem Server in Serverübereinstimmen.

Für einen Verfügbarkeitsgruppen-Listener oder eine Failoverclusterinstanz sollten Sie auch in Multi Subnet Failover überprüfen.

Verschlüsselung und Zertifikatsvalidierung konfigurieren

Das Schlüsselwort Encrypt akzeptiert unabhängig von der Groß-/Kleinschreibung folgende Werte:

Verwenden Strict Sie, wenn der Server TDS 8.0 unterstützt und ein Zertifikat hat, das der Client validieren kann. Azure SQL-Datenbank und SQL Database in Microsoft Fabric unterstützen dies. Eine LocalDB-Verbindung ist nicht verschlüsselt, selbst mit Mandatory, und Strict schlägt fehl.

Die Werte Encrypt und Trust Server Certificate werden wie folgt kombiniert:

Setze Trust Server Certificate=true nicht, um einen Verbindungsfehler in der Produktion zu beheben. Er verschlüsselt den Kanal, bestätigt aber nicht die Identität des Servers. Beschränke es auf Entwicklungsumgebungen, in denen kein vertrauenswürdiges Zertifikat verfügbar ist.

Wenn der Servername in Data Source nicht mit dem Zertifikat übereinstimmt, setze Host Name In Certificate auf den Namen im Zertifikat. SqlClient prüft es nur, wenn der Servername nicht übereinstimmt, und es pinnt kein Zertifikat. Um nur ein bestimmtes Zertifikat zu akzeptieren, setzen Sie Server Certificate auf den Pfad zu einer PEM-, DER- oder CER-Datei:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

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

Verbindungspooling verwenden

Pooling ist standardmäßig aktiviert. Wenn Sie ein SqlConnection öffnen, nimmt der Treiber eine physische Verbindung aus einem Pool, der der Verbindungskonfiguration entspricht. Wenn du die Verbindung schließt oder freigibst, kehrt die physische Verbindung zum Pool zurück, anstatt geschlossen zu werden. Ein Pooled Open überspringt die Netzwerkverbindung, den TLS-Handshake und den Login.

Folgen Sie diesen Regeln:

• Eröffne eine Verbindung kurz bevor du sie brauchst und gib sie frei, sobald du fertig bist, mit using oder await using. Eine Verbindung, die nicht freigegeben wird, bleibt reserviert, und dem Pool können die Verbindungen ausgehen.

• Erstellen Sie die Verbindungszeichenfolge einmal beim Start und verwenden Sie sie erneut. Der Poolschlüssel enthält den exakten Text der Verbindungszeichenfolge, sodass eine andere Schlüsselwortreihenfolge, ein Synonym oder ein Wert pro Anfrage wie eine Anfrage-ID oder ein Benutzername einen separaten Pool erzeugt. Der Builder schreibt eine kanonische Form. Für weitere Informationen siehe Eine kanonische Verbindungszeichenfolge beibehalten.

• Erwarten Sie einen separaten Pool für jede Windows-Identität unter integrierter Authentifizierung, jede SqlCredential Instanz und jeden AccessToken Wert. Verwenden Sie eine vom Treiber bereitgestellte Authentication Methode oder eine wiederverwendete AccessTokenCallback Methode, anstatt AccessToken für jede Verbindung festzulegen.

• Suchen Sie nach Verbindungen, die nicht freigegeben sind, bevor Sie Max Pool Size erhöhen, was standardmäßig auf 100 gesetzt ist. Wenn jede Verbindung in einem Pool genutzt wird, wartet Open bis zu Connect Timeout und wirft dann InvalidOperationException:

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• Plane die Serverkapazität für jeden Pool. Jeder Prozess oder jede Anwendungsdomäne im .NET Framework hat eigene Pools. Die Verbindungen zum Server können Max Pool Size multipliziert mit den Pools in jedem Prozess und mit der Anzahl der Anwendungsinstanzen erreichen.

• Setze Pooling=false nicht, um ein Pooling-Problem zu umgehen. Jedes Öffnen führt dann einen vollständigen Login durch.

Um gepoolte Verbindungen zu schließen, die zu lange im Leerlauf bleiben, siehe Leerlaufzeit für Verbindungen begrenzen. Informationen zu Poolschlüsseln, Größe, Leeren und Transaktionen finden Sie unter SQL Server-Verbindungspooling.

Separate Verbindungs- und Befehlseinstellungen

Ein Verbindungszeichenfolge steuert die Verbindungseinrichtung und das Verhalten der Sitzungen. Ein Befehl steuert eine SQL-Operation.

Ein längerer Timeout ist keine Wiederholungslogik. Eine Auszeit begrenzt eine Wartezeit. Ein erneuter Versuch startet einen weiteren Versuch, und er muss begrenzt und sicher wiederholt werden können.

Melde die Anwendungsidentität

Application Name setzt den Namen, den der Server über APP_NAME()meldet. Verwenden Sie für jede bereitgestellte Workload einen stabilen Namen. Frameworks und Tools, die Verbindungen für eine Anwendung öffnen, können sich ebenfalls über die Eigenschaft RegisteredApplication selbst melden, die kein Verbindungszeichenfolge-Schlüsselwort hat. Weitere Informationen finden Sie unter Melden der Anwendungsidentität.

Verbindende Strings sicher aufbauen

Verwenden Sie SqlConnectionStringBuilder , wenn Code einen Wert hinzufügt oder ändert. Fügen Sie nicht vertrauenswürdigen Text nicht in eine Verbindungszeichenfolge ein, da ein Semikolon in diesem Text ein Schlüsselwort hinzufügen oder ersetzen kann. Der Builder validiert Werte, mappt Synonyme auf kanonische Schlüsselwörter und setzt jeden Wert in Anführungszeichen, damit der Wert keine Schlüsselwörter hinzufügen kann. Beispiele finden Sie unter Connection string builders.

Verbindungsinformationen außerhalb des Codes speichern

Laden Sie Verbindungsstrings aus dem Konfigurationssystem der Anwendung. .NET-Anwendungen verwenden häufig Umgebungsvariablen, Benutzergeheimnisse für lokale Entwicklung, Azure App Configuration und Azure Key Vault.

Folgen Sie diesen Regeln:

• Verbinde keine Passwörter, Client-Geheimnisse, Zugriffstoken oder Produktionsverbindungsstrings.
• Bevorzuge eine Authentifizierungsmethode, die kein Passwort in der Verbindungszeichenfolge benötigt.
• Beschränke den Zugriff auf die Konfigurationsquelle.
• Rotiere gespeicherte Secrets und starte oder aktualisiere Anwendungen, die sie cachen.
• Schreiben Sie keine Verbindungszeichenfolgen in Protokolle, Ausnahmen, Ablaufverfolgungen oder Telemetriedaten.
• Lass Persist Security Info=false, als Standard, damit eine geöffnete Verbindung das Passwort nicht über ihre ConnectionString Eigenschaft offenlegt.

Für .NET-Konfigurationsanbieter siehe Konfiguration in .NET. Weitere Optionen finden Sie unter Verbindungsinformationen schützen.

Parsing-Regeln

Der Fahrer wendet folgende Regeln an:

• Bei Schlüsselwörtern muss die Groß-/Kleinschreibung nicht beachtet werden. DATABASE, Database, und database sind dasselbe Schlüsselwort.
• Viele Schlüsselwörter haben Synonyme. Server und Data Source setzen denselben Wert. Der Artikel über Verbindungsoptionen listet die Synonyme für jedes Schlüsselwort auf.
• Wenn ein Schlüsselwort mehrmals erscheint, gewinnt der letzte Wert. Synonyme zählen als dasselbe Schlüsselwort.
• Der Treiber ignoriert Leerzeichen um Schlüsselwörter und um nicht angeführte Werte.
• Ein nachlaufendes Semikolon ist optional.
• Ein Schlüsselwort, das der Treiber nicht erkennt, wirft ArgumentException mit der Nachricht Keyword not supported.

Werte können je nach Schlüsselwort groß- und kleinschreibungssensitiv sein. Ein Passwort ist groß- und kleinschreibungsabhängig. Encrypt=STRICT und Encrypt=strict sind dieselben.

Dieses Programm zeigt, wie der Generator Schlüsselwörter normalisiert, ein Duplikat auflöst und Sonderzeichen maskiert. Der Tab .NET Framework verwendet C# 7.3. Um ein Projekt zu erstellen, das die Beispiele ausführt, siehe Das Projekt erstellen.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

Die Ausgabe lautet:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

Die erste Zeile zeigt, dass jedes Synonym durch sein kanonisches Schlüsselwort ersetzt wird: server durch Data Source, DATABASE durch uid, Initial Catalog durch User ID, und timeout durch Connect Timeout.

Werte in Anführungszeichen setzen

Setzen Sie einen Wert in doppelte Anführungszeichen (") oder einfache Anführungszeichen ('), wenn er ein Semikolon enthält, mit einem Leerzeichen beginnt oder endet oder mit einem Anführungszeichen beginnt oder endet. Innerhalb eines in Anführungszeichen gesetzten Werts schreiben Sie das umschließende Anführungszeichen zweimal.

Zitatregeln sind leicht falsch zu verstehen. Setze Werte über SqlConnectionStringBuilder Immobilien und lass den Bauträger sie kostenvoranlegen. Weitere Informationen finden Sie unter Verbindungsstrings sicher bauen.

Spezifizieren Sie boolesche Werte

Schlüsselwörter, die einen booleschen Wert annehmen, akzeptieren true, false, yes und no, unabhängig von der Groß-/Kleinschreibung. Integrated Security akzeptiert auch sspi, was bedeutet true. Der Builder schreibt True oder False.

Verwenden Sie Schlüsselwörter von anderen Treibern

Microsoft. Data.SqlClient akzeptiert keine ODBC- oder OLE-Datenbank-Schlüsselwörter wie Driver und Provider. Entferne diese Schlüsselwörter, wenn du eine Verbindungszeichenfolge von einem anderen Treiber verschiebst. System.Data.SqlClientVerbindungszeichenfolgen funktionieren in Microsoft.Data.SqlClient, mit folgenden Unterschieden:

• Encrypt wird in Microsoft.Data.SqlClient standardmäßig auf Mandatory festgelegt. Ein Server ohne ein vertrauenswürdiges Zertifikat scheitert bei der Zertifikatsvalidierung. Installiere ein vertrauenswürdiges Zertifikat auf dem Server.
• In .NET werden Network Library, Connection Reset und Transparent Network IP Resolution nicht unterstützt. Entfernen Sie sie.
• Context Connection=true wird nicht unterstützt.
• Asynchronous Processing ist kein unterstütztes Schlüsselwort und wirft ArgumentException. Entfernen Sie es. Asynchrone Methoden funktionieren auch ohne dies.
• Type System Version=SQL Server 2000 wird nicht unterstützt. Beim Herstellen der Verbindung tritt ArgumentException auf. Verwenden Sie Latest, SQL Server 2012, SQL Server 2008, oder SQL Server 2005.

Verwandte Inhalte

• Verwenden Sie Microsoft. Data.SqlClient in einer .NET-App
• Verbindungsoptionen
• Verbindungszeichenfolgen-Generatoren
• Mit einer Datenquelle verbinden
• SQL Server-Verbindungspooling
• Microsoft Entra ID-Authentifizierung
• Verschlüsselung und Zertifikatüberprüfung
• SQL Server Express-Benutzerinstanzen
• Lebenszyklus der SqlClient-Treiberunterstützung