SqlConnectionStringBuilder Klasse

Definition

Namespace:

System.Data.SqlClient

Assembly:

System.Data.dll

Bietet eine einfache Möglichkeit zum Erstellen und Verwalten des Inhalts von Verbindungszeichenfolgen, die von der SqlConnection Klasse verwendet werden.

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

[System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

[<System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Vererbung

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

Attribute

TypeConverterAttribute

Beispiele

Die folgende Konsolenanwendung erstellt Verbindungszeichenfolgen für eine SQL Server-Datenbank. Der Code verwendet die SqlConnectionStringBuilder Klasse, um die Verbindungszeichenfolge zu erstellen. Anschließend analysiert das Beispiel die Verbindungszeichenfolge und veranschaulicht verschiedene Methoden zum Bearbeiten des Inhalts.

// Create a new SqlConnectionStringBuilder and
// initialize it with a few name/value pairs.
SqlConnectionStringBuilder builder = new(
    "Server=(local);Integrated Security=true;" +
    "Initial Catalog=AdventureWorks"
    );

// The input connection string used the
// Server key, but the new connection string uses
// the well-known Data Source key instead.
Console.WriteLine($"Original connection string: '{builder.ConnectionString}'");

// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine($"Initial catalog: '{builder.InitialCatalog}'");
builder.InitialCatalog = "Northwind";
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($"Modified connection string: '{builder.ConnectionString}'");

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(
            "Server=(local);Integrated Security=true;" &
            "Initial Catalog=AdventureWorks"
            )

        ' The input connection string used the 
        ' Server key, but the new connection string uses
        ' the well-known Data Source key instead.
        Console.WriteLine("Original connection string: " + builder.ConnectionString)

        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine("Initial catalog: " + builder.InitialCatalog)
        builder.InitialCatalog = "Northwind"
        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("Modified connection string: " + builder.ConnectionString)
    End Sub
End Module

Hinweise

Mit dem Verbindungszeichenfolgen-Generator können Entwickler syntaktisch korrekte Verbindungszeichenfolgen erstellen und vorhandene Verbindungszeichenfolgen mithilfe von Eigenschaften und Methoden der Klasse analysieren und neu erstellen. Der Verbindungszeichenfolgen-Generator stellt stark typierte Eigenschaften bereit, die den bekannten Schlüssel-Wert-Paaren entsprechen, die von SQL Server zulässig sind. Wenn Sie Verbindungszeichenfolgen als Teil Ihrer App erstellen müssen, können Sie die SqlConnectionStringBuilder Klasse verwenden, um Verbindungszeichenfolgen zu erstellen und zu ändern. Die Klasse erleichtert auch die Verwaltung von Verbindungszeichenfolgen, die in einer Anwendungskonfigurationsdatei gespeichert sind.

SqlConnectionStringBuilder führt Überprüfungen auf gültige Schlüssel-Wert-Paare durch. Daher können Sie diese Klasse nicht verwenden, um ungültige Verbindungszeichenfolgen zu erstellen. Wenn Sie versuchen, ungültige Paare hinzuzufügen, wird eine Ausnahme ausgelöst. Die Klasse verwaltet eine feste Sammlung von Synonymen und kann von einem Synonym in den entsprechenden bekannten Schlüsselnamen übersetzt werden.

Wenn Sie beispielsweise die eigenschaft Item verwenden, um einen Wert abzurufen, können Sie eine Zeichenfolge angeben, die ein beliebiges Synonym für den benötigten Schlüssel enthält. Sie können z. B. "Netzwerkadresse", "addr" oder ein anderes akzeptables Synonym für diesen Schlüssel innerhalb einer Verbindungszeichenfolge angeben, wenn Sie ein Element verwenden, das eine Zeichenfolge mit dem Schlüsselnamen benötigt, z. B. die Item[String]-Eigenschaft oder die Remove-Methode. Eine vollständige Liste zulässiger Synonyme finden Sie in der ConnectionString-Eigenschaft.

Die Item[String]-Eigenschaft behandelt Versuche, bösartige Einträge einzufügen. Mit dem folgenden Code wird z. B. mit der Standardeigenschaft Item (indexer, in C#) das geschachtelte Schlüssel-Wert-Paar korrekt escapet:

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 auf sichere Weise 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 Anwendungsauslastungstyp beim Herstellen einer Verbindung mit einer Datenbank in einer SQL Server-Verfügbarkeitsgruppe. Sie können den Wert dieser Eigenschaft mit ApplicationIntentfestlegen. Weitere Informationen zur SqlClient-Unterstützung für AlwaysOn-Verfügbarkeitsgruppen finden Sie unter SqlClient-Unterstützung für hohe Verfügbarkeit, Notfallwiederherstellung.
ApplicationName	Dient zum Abrufen oder Festlegen des Namens der Anwendung, die der Verbindungszeichenfolge zugeordnet ist.
AsynchronousProcessing	Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob die asynchrone Verarbeitung von der mithilfe dieser Verbindungszeichenfolge erstellten Verbindung zulässig ist.
AttachDBFilename	Dient zum Abrufen oder Festlegen einer Zeichenfolge, die den Namen der primären Datendatei enthält. Dies schließt den vollständigen Pfadnamen einer anfügenden Datenbank ein.
Authentication	Ruft die Authentifizierung der Verbindungszeichenfolge ab.
BrowsableConnectionString	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob die ConnectionString -Eigenschaft in Visual Studio-Designern sichtbar ist. (Geerbt von DbConnectionStringBuilder)
ColumnEncryptionSetting	Dient zum Abrufen oder Festlegen der Spaltenverschlüsselungseinstellungen für den Verbindungszeichenfolgen-Generator.
ConnectionReset	Veraltet. Obsolet. Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob die Verbindung zurückgesetzt wird, wenn sie aus dem Verbindungspool gezeichnet wird.
ConnectionString	Dient zum Abrufen oder Festlegen der Verbindungszeichenfolge, die dem DbConnectionStringBuilderzugeordnet ist. (Geerbt von DbConnectionStringBuilder)
ConnectRetryCount	Die Anzahl der erneuten Verbindungen, die versucht wurden, nachdem ermittelt wurde, dass ein Leerlaufverbindungsfehler aufgetreten ist. Dies muss eine ganze Zahl zwischen 0 und 255 sein. Der Standardwert ist 1. Legen Sie auf 0 fest, um die erneute Verbindung bei Verbindungsfehlern im Leerlauf zu deaktivieren. Ein ArgumentException wird ausgelöst, wenn er auf einen Wert außerhalb des zulässigen Bereichs festgelegt ist.
ConnectRetryInterval	Zeitraum (in Sekunden) zwischen jedem erneuten Verbindungsversuch, nachdem ermittelt wurde, dass ein Leerlaufverbindungsfehler aufgetreten ist. Dies muss eine ganze Zahl zwischen 1 und 60 sein. Der Standardwert ist 10 Sekunden. Ein ArgumentException wird ausgelöst, wenn er auf einen Wert außerhalb des zulässigen Bereichs festgelegt ist.
ConnectTimeout	Ruft die Dauer (in Sekunden) ab, die auf eine Verbindung mit dem Server wartet, bevor der Versuch beendet und ein Fehler generiert wird, oder legt diese fest.
ContextConnection	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob eine Client-/Server- oder In-Process-Verbindung mit SQL Server hergestellt werden soll.
Count	Ruft die aktuelle Anzahl der Schlüssel ab, die in der eigenschaft ConnectionString enthalten sind. (Geerbt von DbConnectionStringBuilder)
CurrentLanguage	Dient zum Abrufen oder Festlegen des SQL Server Language-Datensatznamens.
DataSource	Ruft den Namen oder die Netzwerkadresse der Sql Server-Instanz ab, mit der eine Verbindung hergestellt werden soll, oder legt diese fest.
EnclaveAttestationUrl	Dient zum Abrufen oder Festlegen der Enklavennachweis-URL, die mit Enklave basiert Always Encrypted verwendet werden soll.
Encrypt	Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob SQL Server SSL-Verschlüsselung für alle Daten verwendet, die zwischen dem Client und dem Server gesendet werden, wenn der Server ein Zertifikat installiert hat.
Enlist	Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob der SQL Server-Verbindungspooler die Verbindung automatisch im aktuellen Transaktionskontext des Erstellungsthreads auflistet.
FailoverPartner	Ruft den Namen oder die Adresse des Partnerservers ab, mit dem eine Verbindung hergestellt werden soll, wenn der primäre Server ausgefallen ist, oder legt diesen fest.
InitialCatalog	Dient zum Abrufen oder Festlegen des Namens der Datenbank, die der Verbindung zugeordnet ist.
IntegratedSecurity	Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob Benutzer-ID und Kennwort in der Verbindung angegeben werden (wenn false) oder ob die aktuellen Windows-Kontoanmeldeinformationen für die Authentifizierung verwendet werden (wenn true).
IsFixedSize	Ruft einen Wert ab, der angibt, ob die SqlConnectionStringBuilder eine feste Größe aufweist.
IsReadOnly	Ruft einen Wert ab, der angibt, ob die DbConnectionStringBuilder schreibgeschützt ist. (Geerbt von DbConnectionStringBuilder)
Item[String]	Dient zum Abrufen oder Festlegen des Werts, der dem angegebenen Schlüssel zugeordnet ist. In C# ist diese Eigenschaft der Indexer.
Keys	Ruft eine ICollection ab, die die Schlüssel in der SqlConnectionStringBuilderenthält.
LoadBalanceTimeout	Ruft die Mindestzeit in Sekunden ab, damit die Verbindung im Verbindungspool lebt, bevor sie zerstört wird, oder legt diese fest.
MaxPoolSize	Dient zum Abrufen oder Festlegen der maximalen Anzahl von Verbindungen, die im Verbindungspool für diese bestimmte Verbindungszeichenfolge zulässig sind.
MinPoolSize	Ruft die mindestanzahl der im Verbindungspool zulässigen Verbindungen für diese bestimmte Verbindungszeichenfolge ab, oder legt diese fest.
MultipleActiveResultSets	Wenn true, kann eine Anwendung mehrere aktive Resultsets (MARS) verwalten. Wenn false, muss eine Anwendung alle Resultsets aus einem Batch verarbeiten oder abbrechen, bevor sie einen anderen Batch für diese Verbindung ausführen kann. Weitere Informationen finden Sie unter Mehrere aktive Resultsets (MARS).
MultiSubnetFailover	Wenn Ihre Anwendung eine Verbindung mit einer Always On-Verfügbarkeitsgruppe (ALWAYS On Availability Group, AG) oder Always On Failover Cluster Instance (FCI) in verschiedenen Subnetzen herstellt, bietet das Festlegen von MultiSubnetFailover=true eine schnellere Erkennung und Verbindung mit dem (derzeit) aktiven Server. Weitere Informationen zur SqlClient-Unterstützung für die AlwaysOn-Features finden Sie unter SqlClient-Unterstützung für hohe Verfügbarkeit, Notfallwiederherstellung.
NetworkLibrary	Dient zum Abrufen oder Festlegen einer Zeichenfolge, die den Namen der Netzwerkbibliothek enthält, die zum Herstellen einer Verbindung mit sql Server verwendet wird.
PacketSize	Ruft die Größe in Byte der Netzwerkpakete ab, die für die Kommunikation mit einer Instanz von SQL Server verwendet werden, oder legt diese fest.
Password	Ruft das Kennwort für das SQL Server-Konto ab oder legt es fest.
PersistSecurityInfo	Dient zum Abrufen oder Festlegen eines Werts, 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 sich diese Verbindung jemals in einem geöffneten Zustand befunden hat.
PoolBlockingPeriod	Das Blockierungszeitraumsverhalten für einen Verbindungspool.
Pooling	Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob die Verbindung jedes Mal, wenn die Verbindung angefordert wird, pooliert oder explizit geöffnet wird.
Replication	Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob die Replikation mithilfe der Verbindung unterstützt wird.
TransactionBinding	Dient zum Abrufen oder Festlegen eines Zeichenfolgenwerts, der angibt, wie die Verbindung ihre Zuordnung mit einer in der Liste aufgeführten System.Transactions Transaktion verwaltet.
TransparentNetworkIPResolution	Wenn der Wert dieses Schlüssels auf truefestgelegt ist, muss die Anwendung alle IP-Adressen für einen bestimmten DNS-Eintrag abrufen und versuchen, eine Verbindung mit dem ersten in der Liste herzustellen. Wenn die Verbindung nicht innerhalb von 0,5 Sekunden hergestellt wird, versucht die Anwendung, parallel eine Verbindung mit allen anderen herzustellen. Wenn die ersten Antworten beantwortet werden, stellt die Anwendung die Verbindung mit der ip-Adresse des Befragten her.
TrustServerCertificate	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob der Kanal verschlüsselt wird, während die Zertifikatkette umgangen wird, um die Vertrauensstellung zu überprüfen.
TypeSystemVersion	Dient zum Abrufen oder Festlegen eines Zeichenfolgenwerts, der das Typsystem angibt, das die Anwendung erwartet.
UserID	Ruft die Benutzer-ID ab, die beim Herstellen einer Verbindung mit SQL Server verwendet werden soll, oder legt diese fest.
UserInstance	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob die Verbindung von der standardmäßigen SQL Server Express-Instanz zu einer laufzeitinitiierte Instanz umgeleitet werden soll, die unter dem Konto des Aufrufers ausgeführt wird.
Values	Ruft eine ICollection ab, die die Werte in der SqlConnectionStringBuilderenthält.
WorkstationID	Ruft den Namen der Arbeitsstation ab, die eine Verbindung mit SQL Server herstellt, oder legt diesen fest.

Methoden

Add(String, Object)	Fügt dem DbConnectionStringBuildereinen 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 für die zugeordnete DbConnectionStringBuilder. (Geerbt von DbConnectionStringBuilder)
ContainsKey(String)	Bestimmt, ob die SqlConnectionStringBuilder einen bestimmten Schlüssel enthält.
Equals(Object)	Bestimmt, ob das angegebene Objekt dem aktuellen Objekt entspricht. (Geerbt von Object)
EquivalentTo(DbConnectionStringBuilder)	Vergleicht die Verbindungsinformationen in diesem DbConnectionStringBuilder -Objekt mit den Verbindungsinformationen im angegebenen Objekt. (Geerbt von DbConnectionStringBuilder)
GetHashCode()	Dient als Standardhashfunktion. (Geerbt von Object)
GetProperties(Hashtable)	Füllt eine bereitgestellte Hashtable mit Informationen zu allen Eigenschaften dieses DbConnectionStringBuilder. (Geerbt von DbConnectionStringBuilder)
GetType()	Ruft die Type der aktuellen Instanz ab. (Geerbt von Object)
MemberwiseClone()	Erstellt eine flache Kopie der 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 dieser DbConnectionStringBuilderzugeordnete Verbindungszeichenfolge zurück. (Geerbt von DbConnectionStringBuilder)
TryGetValue(String, Object)	Ruft einen Wert ab, der dem bereitgestellten Schlüssel aus diesem SqlConnectionStringBuilderentspricht.

Explizite Schnittstellenimplementierungen

ICollection.CopyTo(Array, Int32)	Kopiert die Elemente des ICollection in einen Array, beginnend bei einem bestimmten Array Index. (Geerbt von DbConnectionStringBuilder)
ICollection.IsSynchronized	Ruft einen Wert ab, der angibt, ob der Zugriff auf die ICollection synchronisiert wird (Threadsicher). (Geerbt von DbConnectionStringBuilder)
ICollection.SyncRoot	Ruft ein Objekt ab, das zum Synchronisieren des Zugriffs auf die ICollectionverwendet werden kann. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetAttributes()	Gibt eine Auflistung von benutzerdefinierten Attributen für diese Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetClassName()	Gibt den Klassennamen dieser Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()	Gibt den Namen dieser Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetConverter()	Gibt einen Typkonverter für diese Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultEvent()	Gibt das Standardereignis für diese Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultProperty()	Gibt die Standardeigenschaft für diese Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEditor(Type)	Gibt einen Editor des angegebenen Typs für diese Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents()	Gibt die Ereignisse für diese Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])	Gibt die Ereignisse für diese Instanz einer Komponente zurück, die das angegebene Attributarray als Filter verwendet. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()	Gibt die Eigenschaften für diese Instanz einer Komponente zurück. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])	Gibt die Eigenschaften für diese Instanz einer Komponente zurück, die das Attributarray als Filter verwendet. (Geerbt von DbConnectionStringBuilder)
ICustomTypeDescriptor.GetPropertyOwner(PropertyDescriptor)	Gibt ein Objekt zurück, das die durch den angegebenen Eigenschaftsdeskriptor beschriebene Eigenschaft enthält. (Geerbt von DbConnectionStringBuilder)
IDictionary.Add(Object, Object)	Fügt dem IDictionary-Objekt ein Element mit dem bereitgestellten Schlüssel und Wert hinzu. (Geerbt von DbConnectionStringBuilder)
IDictionary.Contains(Object)	Bestimmt, ob das IDictionary -Objekt ein Element mit dem angegebenen Schlüssel enthält. (Geerbt von DbConnectionStringBuilder)
IDictionary.GetEnumerator()	Gibt ein IDictionaryEnumerator -Objekt für das IDictionary -Objekt zurück. (Geerbt von DbConnectionStringBuilder)
IDictionary.Item[Object]	Ruft das Element mit dem angegebenen Schlüssel ab oder legt es fest. (Geerbt von DbConnectionStringBuilder)
IDictionary.Remove(Object)	Entfernt das Element mit dem angegebenen Schlüssel aus dem IDictionary -Objekt. (Geerbt von DbConnectionStringBuilder)
IEnumerable.GetEnumerator()	Gibt einen Enumerator zurück, der eine Auflistung durchläuft. (Geerbt von DbConnectionStringBuilder)

Erweiterungsmethoden

Cast<TResult>(IEnumerable)	Wandelt die Elemente eines IEnumerable in den angegebenen Typ um.
OfType<TResult>(IEnumerable)	Filtert die Elemente einer IEnumerable basierend auf einem angegebenen Typ.
AsParallel(IEnumerable)	Aktiviert die Parallelisierung einer Abfrage.
AsQueryable(IEnumerable)	Wandelt eine IEnumerable in eine IQueryableum.

Weitere Informationen

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