SqlConnectionStringBuilder Klasse

Definition

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Paket:

Microsoft.Data.SqlClient v5.2.0

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

public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Vererbung

DbConnectionStringBuilder

SqlConnectionStringBuilder

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.
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.
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.
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.
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.
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.