Builder für Verbindungszeichenfolgen in Microsoft.Data.SqlClient

Verwenden Sie SqlConnectionStringBuilder, um Verbindungsstrings über typisierte Eigenschaften zu erstellen und zu bearbeiten. Es erbt von DbConnectionStringBuilder. Nutze es, wann immer dein Code einen Wert hinzufügt oder ändert, anstatt Strings zu verknüpfen.

Der Erbauer:

  • Stellt jedes Schlüsselwort als typisierte Eigenschaft bereit, wie z. B. ConnectTimeout als int und Encrypt als SqlConnectionEncryptOption.
  • Lehnt unbekannte Schlüsselwörter und viele außerhalb des Bereichs liegende Werte mit ArgumentException ab, wenn man sie einsetzt.
  • Bildet Synonyme wie Server und uid auf kanonische Schlüsselwörter wie Data Source und User ID zu.
  • Setzt Werte in Anführungszeichen, die Semikolons, Anführungszeichen oder führende oder nachgestellte Leerzeichen enthalten.

Für die Schlüsselwortliste siehe Verbindungsoptionen. Informationen zum Textformat finden Sie unter Parsingregeln.

Jede Probe ist ein vollständiges Programm. Die .NET Framework-Tabs verwenden C# 7.3. Um ein Projekt zu erstellen, das die Beispiele ausführt, siehe Das Projekt erstellen.

Verhindern Sie die Verbindungszeichenfolgeninjektion

Wenn dein Code nicht vertrauenswürdigen Text in eine Verbindungszeichenfolge einfügt, kann ein Semikolon in diesem Text ein Schlüsselwort hinzufügen oder ein früheres ersetzen, weil der letzte Wert gewinnt. Der Builder speichert den gesamten Wert in einer Eigenschaft und setzt ihn in Anführungszeichen, sodass der Text nicht zu einem weiteren Schlüsselwort werden kann.

Dieses Programm setzt InitialCatalog auf einen Wert, der versucht, das Pooling auszuschalten:

using Microsoft.Data.SqlClient;

// Simulates a value that came from a user or another untrusted source.
string databaseFromUser = "Orders;Pooling=false";

var builder = new SqlConnectionStringBuilder
{
    DataSource = "tcp:sql.example.com,1433",
    InitialCatalog = databaseFromUser,
    IntegratedSecurity = true,
    Encrypt = SqlConnectionEncryptOption.Strict,
};

Console.WriteLine(builder.ConnectionString);
Console.WriteLine($"Pooling: {builder.Pooling}");

Die Ausgabe lautet:

Data Source=tcp:sql.example.com,1433;Initial Catalog="Orders;Pooling=false";Integrated Security=True;Encrypt=Strict
Pooling: True

Der Bauunternehmer gibt den Wert an, und Pooling bleibt True. Der Treiber sendet Orders;Pooling=false als Datenbanknamen an den Server.

Das Setzen von Anführungszeichen verhindert die Schlüsselwort-Injektion. Es entscheidet nicht, ob ein Wert erlaubt ist. Überprüfen Sie nicht vertrauenswürdige Eingaben gegen eine Liste erlaubter Server oder Datenbanken, bevor Sie sie verwenden.

Vervollständige eine Basisverbindungszeichenfolge

Speichere die Teile einer Verbindungszeichenfolge, die sich nicht ändern, wie Server und Datenbank, in der Konfiguration. Fügen Sie zur Laufzeit die geheimen und workload-spezifischen Werte hinzu. Geben Sie die Basis-Zeichenkette an den Builder-Konstruktor und setzen Sie dann Eigenschaften.

Dieses Programm liest eine Basisfolge und ein Passwort aus separaten Umgebungsvariablen, verbindet sich mit SQL-Authentifizierung und bestätigt, dass das Passwort nach Verbindungsöffnung nicht sichtbar ist.

using Microsoft.Data.SqlClient;

// The base string holds no secret. The password comes from a separate secret source.
string baseConnectionString =
    Environment.GetEnvironmentVariable("SQL_BASE_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_BASE_CONNECTION_STRING environment variable.");
string password =
    Environment.GetEnvironmentVariable("SQL_PASSWORD")
    ?? throw new InvalidOperationException(
        "Set the SQL_PASSWORD environment variable.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    Password = password,
    ApplicationName = "Orders.Worker",
};

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()}");

var opened = new SqlConnectionStringBuilder(connection.ConnectionString);
Console.WriteLine($"Password visible after open: {opened.ContainsKey("Password") && opened.Password.Length > 0}");

Setzen Sie SQL_BASE_CONNECTION_STRING auf einen Wert wie Server=tcp:<server>,1433;Database=<database>;User ID=<user>;Encrypt=true. Die Ausgabe lautet:

APP_NAME(): Orders.Worker
Password visible after open: False

Persist Security Info ist standardmäßig auf false eingestellt, sodass der Treiber das Passwort von SqlConnection.ConnectionString entfernt, nachdem die Verbindung geöffnet ist. Behalte die Standardeinstellung bei.

Bevorzugen Sie eine Authentifizierungsmethode, die kein Passwort benötigt, wie Windows-integrierte Authentifizierung oder eine Microsoft Entra ID verwaltete Identität. Weitere Informationen finden Sie unter Microsoft Entra ID-Authentifizierung und Verbindungsinformationen schützen.

Werte lesen und ändern

Der Builder dient auch als Wörterbuch. Der Indexierer, ContainsKey, Remove und TryGetValue akzeptiert ein Schlüsselwort oder eines seiner Synonyme.

using Microsoft.Data.SqlClient;

var b = new SqlConnectionStringBuilder("Server=sql.example.com;Database=Orders;uid=app_user;pwd=x");
b["server"] = "tcp:sql2.example.com,1433";
Console.WriteLine($"DataSource: {b.DataSource}");
Console.WriteLine($"ContainsKey(\"uid\"): {b.ContainsKey("uid")}");
Console.WriteLine($"Remove(\"pwd\"): {b.Remove("pwd")}");
Console.WriteLine($"TryGetValue: {b.TryGetValue("Database", out object? db)} {db}");
Console.WriteLine($"ShouldSerialize(\"Pooling\"): {b.ShouldSerialize("Pooling")}");
Console.WriteLine(b.ConnectionString);
try { b["Bogus"] = 1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }
try { b.ConnectTimeout = -1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }

Die Ausgabe lautet:

DataSource: tcp:sql2.example.com,1433
ContainsKey("uid"): True
Remove("pwd"): True
TryGetValue: True Orders
ShouldSerialize("Pooling"): False
Data Source=tcp:sql2.example.com,1433;Initial Catalog=Orders;User ID=app_user
ArgumentException: Keyword not supported: 'Bogus'.
ArgumentException: Invalid value for key 'Connect Timeout'.

ShouldSerialize gibt false für ein Schlüsselwort zurück, das nicht in der Zeichenkette enthalten ist. ContainsKey gibt true für jedes unterstützte Schlüsselwort zurück, unabhängig davon, ob der String es setzt oder nicht. Die Eigenschaft ConnectionString umfasst nur die von Ihnen festgelegten Schlüsselwörter.

Verstehen Sie, was der Builder nicht prüft

Der Builder lehnt unbekannte Schlüsselwörter und viele ungültige Werte ab, prüft aber nicht jeden Wert. Zum Beispiel akzeptiert es jeglichen Text für Type System Version und Transaction Binding, und prüft keine Zeichenkettenlängen. Es überprüft auch keine Kombinationen von Schlüsselwörtern, daher akzeptiert es Authentication=Active Directory Default zusammen mit Integrated Security=true. SqlConnection lehnt diese Kombination ab, wenn du ArgumentException die Zeichenfolge übergibst. Für die vollständige Liste der Regeln siehe Validierungsregeln.

Der Builder schreibt Authentication Werte ohne Leerzeichen, wie zum Beispiel Authentication=ActiveDirectoryDefault. Der Treiber akzeptiert beide Formate.

Der Builder schützt auch kein Passwort, nachdem es in den Prozessspeicher gelangt ist, und entscheidet nicht, ob eine Server-, Identitäts- oder Zertifikatseinstellung sicher ist.

Behalte eine kanonische Verbindungszeichenfolge

Jede einzelne Verbindungszeichenfolge erhält ihren eigenen Verbindungspool. Zwei handgeschriebene Zeichenketten, die sich nur in der Reihenfolge der Schlüsselwörter oder in den verwendeten Synonymen unterscheiden, bilden zwei Pools. Der Builder schreibt kanonische Schlüsselwörter in einer konsistenten Reihenfolge, sodass Server=a;Database=d und Database=d;Server=a beide zu Data Source=a;Initial Catalog=d werden. Baue die Verbindungszeichenfolge einmal beim Start auf und verwende builder.ConnectionStringsie wieder. Füge keine Werte pro Anfrage hinzu, wie Benutzernamen oder Anfrage-IDs. Weitere Hinweise zum Pooling finden Sie unter Verwenden Sie Verbindungspooling.

Verwandte Inhalte

  • Zuletzt aktualisiert um