SqlConnectionStringBuilder Klasse

Definition

Namespace:

System.Data.SqlClient

Assembly:

System.Data.SqlClient.dll

Paket:

System.Data.SqlClient v4.8.6

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

Object

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 System.Data;
using System.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";
        builder.AsynchronousProcessing = true;

        // 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";
    }
}

Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As 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"
        builder.AsynchronousProcessing = True

        ' 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

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine(builder.ConnectionString)

        Console.WriteLine("Press Enter to finish.")
        Console.ReadLine()
    End Sub

    Private Function GetConnectionString() As String
        ' 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"
    End Function
End Module

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 System.Data.SqlClient.SqlConnectionStringBuilder
builder("Data Source") = "(local)"
builder("Integrated Security") = True
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"
Console.WriteLine(builder.ConnectionString)

System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.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.
BrowsableConnectionString	Ruft einen Wert ab, der angibt, ob die ConnectionString-Eigenschaft in Visual Studio-Designern sichtbar ist, oder legt diesen Wert fest. (Geerbt von DbConnectionStringBuilder)
ConnectionString	Ruft die dem DbConnectionStringBuilder zugeordnete Verbindungszeichenfolge ab oder legt sie fest. (Geerbt von DbConnectionStringBuilder)
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 ist 1. 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. Bei Verwendung eines Werts außerhalb des zulässigen Bereichs wird eine ArgumentException ausgelöst.
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.
Count	Ruft die aktuelle Anzahl von Schlüsseln ab, die in der ConnectionString-Eigenschaft enthalten sind. (Geerbt von DbConnectionStringBuilder)
CurrentLanguage	Ruft den Datensatznamen der SQL Server-Sprache ab oder legt ihn 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.
Encrypt	Ruft einen booleschen Wert ab oder legt einen fest, der angibt, ob alle zwischen Client und Server gesendeten Daten von SQL Server eine SSL-Verschlüsselung verwenden, sofern auf dem Server ein Zertifikat installiert ist.
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.
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).
IsFixedSize	Ruft einen Wert ab, der angibt, ob die DbConnectionStringBuilder eine feste Größe hat. (Geerbt von DbConnectionStringBuilder)
IsReadOnly	Ruft einen Wert ab, der angibt, ob die DbConnectionStringBuilder schreibgeschützt ist. (Geerbt von DbConnectionStringBuilder)
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 (Verfügbarkeitsgruppe) oder Always On Failoverclusterinstanz (FCI) in verschiedenen Subnetzen herstellt, ermöglicht das Festlegen von MultiSubnetFailover=true eine schnellere Erkennung und Verbindung mit dem (derzeit) aktiven Server. Weitere Informationen zur SqlClient-Unterstützung für die Always On Features finden Sie unter SqlClient-Unterstützung für Hochverfü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 Wert ab, der angibt, ob sicherheitsrelevante Informationen, z. B. das Kennwort oder zugriffstoken, als Teil der Verbindungszeichenfolge für eine Verbindung zurückgegeben werden sollen, die mit dieser SqlConnectionStringBuilder erstellt wurde, nachdem diese Verbindung jemals geöffnet war.
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.
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

Add(String, Object)	Fügt dem DbConnectionStringBuilder einen Eintrag mit dem angegebenen Schlüssel und Wert hinzu. (Geerbt von DbConnectionStringBuilder)
Clear()	Löscht den Inhalt der SqlConnectionStringBuilder-Instanz.
ClearPropertyDescriptors()	Löscht die Auflistung von PropertyDescriptor-Objekten, die dem DbConnectionStringBuilder zugeordnet sind. (Geerbt von DbConnectionStringBuilder)
ContainsKey(String)	Stellt fest, ob der SqlConnectionStringBuilder einen bestimmten Schlüssel enthält.
Equals(Object)	Bestimmt, ob das angegebene Objekt gleich dem aktuellen Objekt ist. (Geerbt von Object)
EquivalentTo(DbConnectionStringBuilder)	Vergleicht die Verbindungsinformationen in diesem DbConnectionStringBuilder-Objekt mit den Verbindungsinformationen im angegebenen Objekt. (Geerbt von DbConnectionStringBuilder)
GetHashCode()	Fungiert als Standardhashfunktion. (Geerbt von Object)
GetProperties(Hashtable)	Füllt eine angegebene Hashtable mit Informationen zu allen Eigenschaften dieses DbConnectionStringBuilder. (Geerbt von DbConnectionStringBuilder)
GetType()	Ruft den Type der aktuellen Instanz ab. (Geerbt von Object)
MemberwiseClone()	Erstellt eine flache Kopie des aktuellen Object. (Geerbt von Object)
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.
ToString()	Gibt die diesem DbConnectionStringBuilder zugeordnete Verbindungszeichenfolge zurück. (Geerbt von DbConnectionStringBuilder)
TryGetValue(String, Object)	Ruft einen Wert ab, der dem von diesem SqlConnectionStringBuilder bereitgestellten Schlüssel entspricht.

Erweiterungsmethoden

Weitere Informationen

• Verbindungszeichenfolgen (ADO.NET)
• Übersicht über ADO.NET