SqlConnectionStringBuilder Klasse
Definition
Wichtig
Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.
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(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilderpublic sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
inherit DbConnectionStringBuildertype SqlConnectionStringBuilder = class
inherit DbConnectionStringBuilderPublic 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 des Verbindungszeichenfolge und übergibt dann die ConnectionString Eigenschaft der SqlConnectionStringBuilder Instanz an den Konstruktor der Verbindungsklasse. Im Beispiel wird auch eine vorhandene Verbindungszeichenfolge analysiert und verschiedene Möglichkeiten zum Bearbeiten des Inhalts der Verbindungszeichenfolge veranschaulicht.
Hinweis
Dieses Beispiel enthält ein Kennwort, um die Funktionsweise mit Verbindungszeichenfolgen zu veranschaulichen SqlConnectionStringBuilder . In Ihren Anwendungen wird empfohlen, die Windows-Authentifizierung zu verwenden. Wenn Sie ein Kennwort verwenden müssen, fügen Sie kein hartcodiertes Kennwort in Ihre 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=********;initial catalog=AdventureWorks";
// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine(builder.Password);
builder.Password = "********";
// 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
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. 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 erleichtert auch die Verwaltung von Verbindungszeichenfolgen, die in einer Anwendungskonfigurationsdatei gespeichert sind.
Die SqlConnectionStringBuilder Durchführung 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 Item-Eigenschaft 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 zulässiges Synonym für diesen Schlüssel innerhalb eines Verbindungszeichenfolge angeben, wenn Sie ein Element verwenden, das eine Zeichenfolge erfordert, die den Schlüsselnamen enthält, z. B. die Item-Eigenschaft oder die Remove Methode. Eine vollständige Liste zulässiger Synonyme finden Sie in der ConnectionString-Eigenschaft.
Die Item-Eigenschaft behandelt versuche, schädliche Einträge einzufügen. Mit dem folgenden Code wird z. B. mithilfe der Standardeigenschaft "Item" (der Indexer in C#) das geschachtelte Schlüssel-Wert-Paar ordnungsgemäß escapet:
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 auf sichere Weise behandelt:
Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";
Integrated Security=True
Konstruktoren
| Name | Beschreibung |
|---|---|
| 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
| Name | Beschreibung |
|---|---|
| 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 Always On-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 |
Veraltet.
Obsolete. 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. |
| AttestationProtocol |
Dient zum Abrufen oder Festlegen des Werts des Nachweisprotokolls. |
| Authentication |
Dient zum Abrufen oder Festlegen der Authentifizierungsmethode, die für Connect mit Microsoft Entra verwendet wird, um Ressourcen zu Azure SQL. |
| ColumnEncryptionSetting |
Dient zum Abrufen oder Festlegen der Spaltenverschlüsselungseinstellungen für den Verbindungszeichenfolgen-Generator. |
| CommandTimeout |
Standardwartezeit (in Sekunden), die gewartet werden soll, bis der Versuch einer Befehlsausführung beendet und ein Fehler generiert wird Der Standardwert ist 30 Sekunden. |
| ConnectionReset |
Veraltet.
Veraltet.
Obsolete. Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob die Verbindung zurückgesetzt wird, wenn sie aus dem Verbindungspool gezeichnet wird. |
| 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 für nicht Azure Endpunkte ist 1. Für Azure SQL Endpunkte ist der Standardwert 2. Ab Version 5.x ist für Azure SQL serverlosen oder bei Bedarfsendpunkten der Standardwert 5, um den Verbindungserfolg für Verbindungen mit einer leerlauf- oder angehaltenen Instanz zu verbessern. Legen Sie auf 0 fest, um die erneute Verbindung bei Verbindungsfehlern im Leerlauf zu deaktivieren. Wird ArgumentException 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. |
| 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 |
Veraltet.
Obsolete. Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob eine Client-/Server- oder In-Process-Verbindung mit SQL Server hergestellt werden soll. |
| CurrentLanguage |
Dient zum Abrufen oder Festlegen der Sprache, die für Datenbankserverwarnungen oder Fehlermeldungen verwendet wird. |
| DataSource |
Ruft den Namen oder die Netzwerkadresse der Sql Server-Instanz ab, mit der eine Verbindung hergestellt werden soll, oder legt diese fest. |
| EnclaveAttestationUrl |
Ruft die Enklavennachweis-URL ab, die mit Enklave basiert Always Encrypted verwendet werden soll, oder legt diese fest. |
| Encrypt |
Dient zum Abrufen oder Festlegen eines SqlConnectionEncryptOption Werts seit Version 5.0 oder einem Boolean Wert für die früheren Versionen, der angibt, ob tls-Verschlüsselung für alle Daten erforderlich ist, die zwischen dem Client und dem Server gesendet werden. |
| Enlist |
Dient zum Abrufen oder Festlegen eines booleschen Werts, der angibt, ob der SQL Server Verbindungspool 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. |
| FailoverPartnerSPN |
Dient zum Abrufen oder Festlegen des Dienstprinzipalnamens (SPN) des Failoverpartners für die Verbindung. |
| 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 aus der |
| IdleTimeout |
Ruft ab oder legt die maximale Zeit in Sekunden, dass eine Verbindung nicht verwendet (im Leerlauf) im Verbindungspool sitzen kann, bevor sie verworfen wird. Der Standardwert ist 300 (5 Minuten). |
| 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 |
| IPAddressPreference |
Ruft die IP-Adressfamilieneinstellung beim Einrichten von TCP-Verbindungen ab oder legt diese fest. |
| IsFixedSize |
Ruft einen Wert ab, der angibt, ob die SqlConnectionStringBuilder eine feste Größe aufweist. |
| 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 Multiple Active Result Sets (MARS). |
| MultiSubnetFailover |
Wenn Ihre Anwendung eine Verbindung mit einer AlwaysOn-Verfügbarkeitsgruppe (ALWAYSOn Availability Group, AG) in verschiedenen Subnetzen herstellt, bietet die Einstellung |
| 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 booleschen 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 Verbindung erstellt wurde, nachdem sich diese Verbindung jemals in einem geöffneten Zustand befindet. Diese Eigenschaft sollte nur festgelegt |
| 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. |
| ServerCertificate |
Dient zum Abrufen oder Festlegen des Pfads zu einer Zertifikatdatei, die mit dem SQL Server TLS/SSL-Zertifikat für die Verbindung übereinstimmen soll. Die akzeptierten Zertifikatformate sind PEM, DER und CER. Wenn angegeben, wird das SQL Server Zertifikat überprüft, indem überprüft wird, ob es sich bei der |
| ServerSPN |
Dient zum Abrufen oder Festlegen des Dienstprinzipalnamens (SPN) der Datenquelle. |
| TransactionBinding |
Dient zum Abrufen oder Festlegen eines Zeichenfolgenwerts, der angibt, wie die Verbindung ihre Zuordnung mit einer in der Liste aufgeführten |
| TransparentNetworkIPResolution |
Veraltet.
Wenn der Wert dieses Schlüssels auf .NET Framework festgelegt |
| 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 , die die Werte in der SqlConnectionStringBuilder . |
| WorkstationID |
Ruft den Namen der Arbeitsstation ab, die eine Verbindung mit SQL Server herstellt, oder legt diesen fest. |
Methoden
| Name | Beschreibung |
|---|---|
| Clear() |
Löscht den Inhalt der SqlConnectionStringBuilder Instanz. |
| ContainsKey(String) |
Bestimmt, ob der SqlConnectionStringBuilder Schlüssel 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 angegebenen Schlüssel entspricht SqlConnectionStringBuilder . |