Freigeben über


SqlConnectionStringBuilder Klasse

Definition

Bietet eine einfache Möglichkeit, den Inhalt von Verbindungszeichenfolgen, die von der SqlConnection-Klasse verwendet werden, zu erstellen und zu verwalten.

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder
[System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder
Vererbung
SqlConnectionStringBuilder
Attribute

Beispiele

Die folgende Konsolenanwendung erstellt Verbindungszeichenfolgen für eine SQL Server Datenbank. Der Code verwendet eine SqlConnectionStringBuilder-Klasse zum Erstellen der Verbindungszeichenfolge und übergibt anschließend die ConnectionString-Eigenschaft der SqlConnectionStringBuilder-Instanz an den Konstruktor der Verbindungsklasse. In dem Beispiel wird auch eine vorhandene Verbindungszeichenfolge analysiert, und es werden verschiedene Methoden zur Bearbeitung des Inhalts der Verbindungszeichenfolge veranschaulicht.

Hinweis

Das Beispiel umfasst ein Kennwort zur Veranschaulichung der Funktion von SqlConnectionStringBuilder mit Verbindungszeichenfolgen. In den Anwendungen wird die Verwendung der Windows-Authentifizierung empfohlen. Wenn Sie ein Kennwort verwenden müssen, schließen Sie kein hartcodiertes Kennwort in die Anwendung ein.

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Create a new SqlConnectionStringBuilder and
        // initialize it with a few name/value pairs.
        SqlConnectionStringBuilder builder =
            new SqlConnectionStringBuilder(GetConnectionString());

        // The input connection string used the 
        // Server key, but the new connection string uses
        // the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString);

        // Pass the SqlConnectionStringBuilder an existing 
        // connection string, and you can retrieve and
        // modify any of the elements.
        builder.ConnectionString = "server=(local);user id=ab;" +
            "password= a!Pass113;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "new@1Password";

        // You can refer to connection keys using strings, 
        // as well. When you use this technique (the default
        // Item property in Visual Basic, or the indexer in C#),
        // you can specify any synonym for the connection string key
        // name.
        builder["Server"] = ".";
        builder["Connect Timeout"] = 1000;
        builder["Trusted_Connection"] = true;
        Console.WriteLine(builder.ConnectionString);

        Console.WriteLine("Press Enter to finish.");
        Console.ReadLine();
    }

    private static string GetConnectionString()
    {
        // To avoid storing the connection string in your code,
        // you can retrieve it from a configuration file. 
        return "Server=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}

Hinweise

Mithilfe des Verbindungszeichenfolgen-Generators können Entwickler syntaktisch korrekte Verbindungszeichenfolgen programmgesteuert erstellen sowie vorhandene Verbindungszeichenfolgen analysieren und neu erstellen, indem sie Eigenschaften und Methoden der Klasse verwenden. Der Verbindungszeichenfolgen-Generator stellt stark typisierte Eigenschaften mit strikter Typbindung bereit, die den bekannten Schlüssel-Wert-Paaren entsprechen, die von SQL Server zugelassen werden. Entwickler, die Verbindungszeichenfolgen als Teil von Anwendungen erstellen müssen, können die SqlConnectionStringBuilder-Klasse verwenden, um Verbindungszeichenfolgen zu erstellen und zu ändern. Die Klasse vereinfacht auch die Verwaltung von Verbindungszeichenfolgen, die in einer Anwendungskonfigurationsdatei gespeichert sind.

Der SqlConnectionStringBuilder führt Überprüfungen auf gültige Schlüssel-Wert-Paare aus. Daher können mit dieser Klasse keine ungültigen Verbindungszeichenfolgen erstellt werden. Wenn Sie versuchen, ungültige Paare hinzuzufügen, wird eine Ausnahme ausgelöst. Die Klasse verwaltet eine feste Sammlung von Synonymen und ist in der Lage, ein Synonym in den entsprechenden bekannten Schlüsselnamen zu übersetzen.

Wenn Sie beispielsweise die Item-Eigenschaft zum Abrufen eines Werts verwenden, können Sie eine Zeichenfolge angeben, die ein beliebiges Synonym für den benötigten Schlüssel enthält. Beispielsweise können Sie "Netzwerkadresse", "addr" oder ein anderes zulässiges Synonym für diesen Schlüssel in einer Verbindungszeichenfolge angeben, wenn Sie einen Beliebigen Member verwenden, der eine Zeichenfolge erfordert, die den Schlüsselnamen enthält, z. B. die Item-Eigenschaft oder die Remove -Methode. In der ConnectionString-Eigenschaft finden Sie eine vollständige Liste der akzeptablen Synonyme.

Die Item-Eigenschaft handles versucht, schädliche Einträge einzufügen. Beispiel: Der folgende Code, in dem die standardmäßige Item-Eigenschaft verwendet wird (der Indexer in C#) versieht das geschachtelte Schlüssel-Wert-Paar ordnungsgemäß mit Escapezeichen:

Dim builder As New Microsoft.Data.SqlClient.SqlConnectionStringBuilder  
builder("Data Source") = "(local)"  
builder("Integrated Security") = True  
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"  
Console.WriteLine(builder.ConnectionString)  
Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =  
  new Microsoft.Data.SqlClient.SqlConnectionStringBuilder();  
builder["Data Source"] = "(local)";  
builder["Integrated Security"] = true;  
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";  
Console.WriteLine(builder.ConnectionString);  

Das Ergebnis ist die folgende Verbindungszeichenfolge, die den ungültigen Wert sicher behandelt:

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";  
Integrated Security=True  

Konstruktoren

SqlConnectionStringBuilder()

Initialisiert eine neue Instanz der SqlConnectionStringBuilder-Klasse.

SqlConnectionStringBuilder(String)

Initialisiert eine neue Instanz der SqlConnectionStringBuilder-Klasse. Die bereitgestellte Verbindungszeichenfolge stellt die Daten für die internen Verbindungsinformationen der Instanz bereit.

Eigenschaften

ApplicationIntent

Deklariert den Arbeitsauslastungstyp für die Anwendung, wenn eine Verbindung mit einer Datenbank in einer SQL Server-Verfügbarkeitsgruppe hergestellt wird. Sie können den Wert der Eigenschaft mit ApplicationIntent festlegen. Weitere Informationen zur SqlClient-Unterstützung für AlwaysOn-Verfügbarkeitsgruppen finden Sie unter SqlClient-Unterstützung für hohe Verfügbarkeit, Notfallwiederherstellung.

ApplicationName

Ruft den Namen der Verbindungszeichenfolge zugeordneten Anwendung ab oder legt einen Namen fest.

AsynchronousProcessing
Veraltet.

Veraltet. Ruft einen booleschen Wert ab, der angibt, ob die mit dieser Verbindungszeichenfolge erstellte Verbindung eine asynchrone Verarbeitung zulässt.

AttachDBFilename

Ruft eine Zeichenfolge ab, die den Namen der Primärdatendatei enthält, oder legt diese Zeichenfolge fest. Dazu gehört der vollständige Pfadname einer anfügbaren Datenbank.

AttestationProtocol

Ruft den Wert des Nachweisprotokolls ab oder legt den Wert fest.

Authentication

Ruft die Authentifizierungsmethode ab, die für die Verbindung mit SQL-Datenbank Mithilfe der Azure Active Directory-Authentifizierung verwendet wird, oder legt sie fest.

ColumnEncryptionSetting

Ruft die Spaltenverschlüsselungseinstellungen für den Verbindungszeichenfolgen-Generator ab oder legt diese fest.

CommandTimeout

Die Standardwartezeit (in Sekunden), bevor der Versuch, einen Befehl auszuführen, beendet wird und ein Fehler generiert wird. Der Standardwert ist 30 Sekunden.

ConnectionReset
Veraltet.
Veraltet.

Veraltet. Ruft einen booleschen Wert ab, der angibt, ob die Verbindung bei der Entnahme aus dem Verbindungspool zurückgesetzt wird, oder legt diesen Wert fest.

ConnectRetryCount

Die Anzahl der erneuten Verbindungsversuche, nachdem ermittelt wurde, dass ein Fehler aufgrund einer Leerlaufverbindung erkannt wurde. Dieser muss einer ganzen Zahl zwischen 0 und 255 entsprechen. Der Standardwert für Nicht-Azure-Endpunkte ist 1. Für Azure SQL Endpunkte ist der Standardwert 2. Ab Version 5.x ist der Standardwert für Azure SQL serverlosen oder bedarfsgesteuerten Endpunkten 5, um den Verbindungserfolg für Verbindungen mit einem im Leerlauf befindlichen oder angehaltenen instance zu verbessern. Legen Sie den Wert auf 0 fest, um das Herstellen einer erneuten Verbindung bei Fehlern aufgrund einer Leerlaufverbindung zu deaktivieren. Bei Verwendung eines Werts außerhalb des zulässigen Bereichs wird eine ArgumentException ausgelöst.

ConnectRetryInterval

Zeitraum zwischen erneuten Verbindungsversuchen (in Sekunden), nachdem ein Fehler aufgrund einer Leerlaufverbindung erkannt wurde. Dieser muss einer ganzen Zahl zwischen 1 und 60 entsprechen. Die Standardeinstellung beträgt 10 Sekunden.

ConnectTimeout

Ruft die Zeit in Sekunden ab, die auf eine Verbindung zum Server gewartet werden soll, bevor der Versuch abgebrochen und ein Fehler generiert wird, oder legt diesen Wert fest.

ContextConnection
Veraltet.

Veraltet. Ruft einen Wert ab oder legt einen Wert fest, der angibt, ob eine Client-/Server-Verbindung oder eine prozessinterne Verbindung zu SQL Server hergestellt werden soll.

CurrentLanguage

Ruft die Sprache ab, die für Datenbankserverwarnungen oder Fehlermeldungen verwendet wird, oder legt diese fest.

DataSource

Ruft den Namen oder die Netzwerkadresse der Instanz von SQL Server ab, mit der eine Verbindung hergestellt werden soll, oder legt einen Namen bzw. eine Adresse fest.

EnclaveAttestationUrl

Ruft die Enclave-Nachweis-URL ab, die mit Enclave-basierten Always Encrypted verwendet werden soll, oder legt diese fest.

Encrypt

Ruft einen SqlConnectionEncryptOption Wert ab Version 5.0 oder einen Wert für die früheren Versionen ab, der angibt, ob die TLS-Verschlüsselung für alle zwischen Client und Server gesendeten Daten erforderlich ist, oder legt diesen Boolean fest.

Enlist

Ruft einen booleschen Wert ab oder legt einen fest, der angibt, ob der Verbindungspooler in SQL Server die Verbindung automatisch in den aktuellen Transaktionskontext des Erstellungsthreads einträgt.

FailoverPartner

Ruft den Namen oder die Adresse des Partnerservers ab (bzw. legt diese Angaben fest), mit dem eine Verbindung hergestellt werden soll, wenn der primäre Server ausgefallen ist.

FailoverPartnerSPN

Ruft den Dienstprinzipalnamen (SPN) des Failoverpartners für die Verbindung ab oder legt diese fest.

HostNameInCertificate

Ruft den Hostnamen ab, der beim Überprüfen des Serverzertifikats für die Verbindung verwendet werden soll, oder legt diesen fest. Wenn nicht angegeben, wird der Servername von für die Data Source Zertifikatüberprüfung verwendet. (Nur verfügbar in v5.0+)

InitialCatalog

Ruft den Namen der Datenbank ab, die der Verbindung zugeordnet ist, oder legt ihn fest.

IntegratedSecurity

Ruft einen booleschen Wert ab oder legt einen fest, der angibt, ob in der Verbindung eine Benutzer-ID und ein Kennwort angegeben wurden (dann false) oder ob zur Authentifizierung die aktuellen Anmeldeinformationen des Windows-Kontos verwendet werden (dann true).

IPAddressPreference

Ruft beim Einrichten von TCP-Verbindungen die EINSTELLUNG der IP-Adressfamilie ab oder legt diese fest.

IsFixedSize

Ruft einen Wert ab, der angibt, ob die SqlConnectionStringBuilder eine feste Größe hat.

Item[String]

Ruft den Wert ab, der dem angegebenen Schlüssel zugeordnet ist, oder legt diesen fest. In C# ist diese Eigenschaft der Indexer.

Keys

Ruft eine ICollection ab, die die Schlüssel im SqlConnectionStringBuilder enthält.

LoadBalanceTimeout

Ruft für die Verbindung die minimale Zeitdauer in Sekunden ab, die sie im Verbindungspool verbleiben soll, oder legt diese Zeitdauer fest, bevor sie zerstört wird.

MaxPoolSize

Ruft die maximale Anzahl von Verbindungen ab, die im Verbindungspool für diese bestimmte Verbindungszeichenfolge zulässig sind, oder legt diese fest.

MinPoolSize

Ruft die minimale Anzahl von Verbindungen ab, die im Verbindungspool für diese bestimmte Verbindungszeichenfolge zulässig sind, oder legt diese fest.

MultipleActiveResultSets

Bei „true“ kann eine Anwendung mehrere aktive Resultsets (Multiple Active Result Sets, MARS) verwalten. Ist diese Option auf „false“ festgelegt, muss eine Anwendung alle Resultsets aus einem Batch verarbeiten oder abbrechen, bevor der nächste Batch für diese Verbindung ausgeführt werden kann. Weitere Informationen finden Sie unter Multiple Active Result Sets (MARS).

MultiSubnetFailover

Wenn Ihre Anwendung eine Verbindung mit einer Always On-Verfügbarkeitsgruppe in unterschiedlichen Subnetzen herstellt, ermöglicht die Festlegung von „MultiSubnetFailover“ auf TRUE eine schnellere Erkennung des (derzeit) aktiven Servers und eine schnellere Verbindung mit diesem. Weitere Informationen zur SqlClient-Unterstützung für AlwaysOn-Verfügbarkeitsgruppen finden Sie unter SqlClient-Unterstützung für hohe Verfügbarkeit, Notfallwiederherstellung.

NetworkLibrary

Ruft eine Zeichenfolge ab oder legt eine fest, die den Namen der Netzwerkbibliothek enthält, mit der die Verbindung zu SQL Server hergestellt wird.

PacketSize

Ruft die Größe der Netzwerkpakete in Bytes ab, die zum Kommunizieren mit einer Instanz von SQL Server verwendet werden, oder legt die Größe fest.

Password

Ruft das Kennwort für das SQL Server-Konto ab oder legt es fest.

PersistSecurityInfo

Ruft einen booleschen Wert ab, der angibt, ob sicherheitsrelevante Informationen, z. B. das Kennwort oder das Zugriffstoken, als Teil des Verbindungszeichenfolge für eine verbindung zurückgegeben werden sollen, die mit dieser SqlConnectionStringBuilder erstellt wurde, nachdem sich die Verbindung jemals in einem geöffneten Zustand befunden hat. Diese Eigenschaft sollte nur dann auf true festgelegt werden, wenn Ihre Anwendung das Kennwort aus einer bereits geöffneten Datenbankverbindung lesen muss. Der Standardwert von false ist die sicherere Einstellung. Die Verwendung true für diese Eigenschaft öffnet Ihre Anwendung für Sicherheitsrisiken, z. B. versehentliches Protokollieren oder Nachverfolgen des Datenbankkennworts.

PoolBlockingPeriod

Das Verhalten im Blockierungszeitraum für einen Verbindungspool.

Pooling

Ruft einen booleschen Wert ab oder legt einen fest, der angibt, ob die Verbindung bei jedem Aufruf in den Verbindungspool gestellt oder explizit geöffnet wird.

Replication

Ruft einen booleschen Wert ab oder legt einen fest, der angibt, ob mit der Verbindung Replikationsvorgänge unterstützt werden.

ServerCertificate

Ruft den Pfad zu einer Zertifikatdatei ab, die mit dem SQL Server TLS/SSL-Zertifikats für die Verbindung übereinstimmt, oder legt diesen fest. Die akzeptierten Zertifikatformate sind PEM, DER und CER. Wenn angegeben, wird das SQL Server Zertifikats überprüft, indem überprüft wird, ob das ServerCertificate bereitgestellte eine genaue Übereinstimmung ist. (Nur verfügbar in v5.1+)

ServerSPN

Ruft den Dienstprinzipalnamen (Service Principal Name, SPN) der Datenquelle ab oder legt diese fest.

TransactionBinding

Ruft einen Zeichenfolgenwert ab, der angibt, wie die Verbindung ihre Zuordnung zu einer eingetragenen System.Transactions-Transaktion beibehält, oder legt diesen Wert fest.

TransparentNetworkIPResolution

Wenn der Wert dieses Schlüssels auf true festgelegt wird, muss die Anwendung alle IP-Adressen für einen bestimmten DNS-Eintrag abrufen und versuchen, mit der ersten Adresse auf der Liste eine Verbindung herzustellen. Wenn die Verbindung nicht innerhalb von 0,5 Sekunden hergestellt wird, versucht die Verbindung, parallel mit allen anderen Adressen eine Verbindung herzustellen. Wenn die erste Adresse antwortet, stellt die Anwendung eine Verbindung mit der antwortenden IP-Adresse her.

TrustServerCertificate

Ruft einen Wert ab, der angibt, ob der Channel verschlüsselt wird, während das Durchlaufen der Zertifikatskette zum Überprüfen der Vertrauensstellung übergangen wird.

TypeSystemVersion

Ruft einen Zeichenfolgenwert ab, der das Typensystem angibt, dass die Anwendung erwartet, oder legt diesen fest.

UserID

Ruft die Benutzer-ID ab, die zum Herstellen einer SQL Server-Verbindung verwendet wird, oder legt diese fest.

UserInstance

Ruft einen Wert ab oder legt einen Wert fest, der angibt, ob die Verbindung von der Standardinstanz von SQL Server Express auf eine von der Laufzeit initiierte Instanz umgeleitet werden soll, die unter dem Konto des Aufrufers ausgeführt wird.

Values

Ruft ein ICollection ab, das die Werte im SqlConnectionStringBuilder enthält.

WorkstationID

Ruft den Namen der Workstation fest, die eine Verbindung zu SQL Server herstellt, oder legt den Namen fest.

Methoden

Clear()

Löscht den Inhalt der SqlConnectionStringBuilder-Instanz.

ContainsKey(String)

Stellt fest, ob der SqlConnectionStringBuilder einen bestimmten Schlüssel enthält.

Remove(String)

Entfernt den Eintrag mit dem angegebenen Schlüssel aus der SqlConnectionStringBuilder-Instanz.

ShouldSerialize(String)

Gibt an, ob der angegebene Schlüssel in dieser SqlConnectionStringBuilder-Instanz vorhanden ist.

TryGetValue(String, Object)

Ruft einen Wert ab, der dem von diesem SqlConnectionStringBuilder bereitgestellten Schlüssel entspricht.

Gilt für: