SqlConnection.ConnectionString-Eigenschaft

Artikel
08/20/2007

Ruft die Zeichenfolge ab, mit der eine SQL Server-Datenbank geöffnet wird, oder legt diese fest.

Namespace: System.Data.SqlClient
Assembly: System.Data (in system.data.dll)

Syntax

'Declaration
Public Overrides Property ConnectionString As String
'Usage
Dim instance As SqlConnection
Dim value As String

value = instance.ConnectionString

instance.ConnectionString = value

public override string ConnectionString { get; set; }

public:
virtual property String^ ConnectionString {
    String^ get () override;
    void set (String^ value) override;
}

/** @property */
public String get_ConnectionString ()

/** @property */
public void set_ConnectionString (String value)

public override function get ConnectionString () : String

public override function set ConnectionString (value : String)

Eigenschaftenwert

Die Verbindungszeichenfolge, die den Namen der Quelldatenbank und weitere für das Herstellen der Anfangsverbindung erforderliche Parameter enthält. Der Standardwert ist eine leere Zeichenfolge.

Ausnahmen

Ausnahmetyp	Bedingung
ArgumentException	Es wurde ein ungültiges Argument für eine Verbindungszeichenfolge bereitgestellt, oder ein erforderliches Argument für eine Verbindungszeichenfolge wurde nicht bereitgestellt.

Hinweise

ConnectionString ähnelt einer OLE DB-Verbindungszeichenfolge, ist aber nicht mit dieser identisch. Im Gegensatz zu OLE DB oder ADO ist die zurückgegebene Verbindungszeichenfolge mit dem vom Benutzer festgelegten ConnectionString identisch. Es werden jedoch keine Sicherheitsinformationen übergeben, wenn der Wert für Persistente Sicherheitsinformationen auf false (Standard) festgelegt ist. Der .NET Framework-Datenanbieter für SQL Server behält das Kennwort in einer Verbindungszeichenfolge nur bei oder gibt dieses zurück, wenn Sie Persistente Sicherheitsinformationen auf true festlegen.

Mithilfe der ConnectionString-Eigenschaft können Sie eine Verbindung mit einer Datenbank herstellen. Das folgende Beispiel enthält eine typische Verbindungszeichenfolge.

"Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=Northwind;server=(local)"

Verwenden Sie den neuen SqlConnectionStringBuilder, um zur Laufzeit gültige Verbindungszeichenfolgen zu erstellen. Weitere Informationen finden Sie unter Building Connection Strings.

Die ConnectionString-Eigenschaft kann nur festgelegt werden, wenn die Verbindung geschlossen ist. Viele Verbindungszeichenfolgenwerte verfügen über entsprechende schreibgeschützte Eigenschaften. Wenn die Verbindungszeichenfolge festgelegt ist, werden diese Eigenschaften aktualisiert, sofern kein Fehler aufgetreten ist. In diesem Fall wird keine der Eigenschaften aktualisiert. SqlConnection-Eigenschaften geben nur die im ConnectionString enthaltenen Einstellungen zurück.

Zum Herstellen einer Verbindung mit einem lokalen Computer geben Sie als Server "(local)" an. (Sie müssen immer einen Server angeben.)

Mit dem Zurücksetzen von ConnectionString für eine geschlossene Verbindung werden alle Werte der Verbindungszeichenfolge (und die zugeordneten Eigenschaften) einschließlich des Kennworts zurückgesetzt. Wenn Sie z. B. eine Verbindungszeichenfolge festlegen, die "Database= AdventureWorks" enthält, und dann die Verbindungszeichenfolge auf "Data Source=myserver;Integrated Security=SSPI" zurücksetzen, ist auch die Database-Eigenschaft nicht mehr auf "AdventureWorks" festgelegt.

Die Verbindungszeichenfolge wird direkt nach dem Festlegen analysiert. Wenn bei der Analyse Fehler in der Syntax gefunden werden, wird eine Laufzeitausnahme generiert, z. B. ArgumentException. Andere Fehler können erst gefunden werden, wenn versucht wird, die Verbindung herzustellen.

Das Grundformat einer Verbindungszeichenfolge besteht aus einer Reihe von Schlüsselwort-Wert-Paaren, die durch Semikolons getrennt sind. Ein Gleichheitszeichen (=) verbindet jedes Schlüsselwort mit seinem Wert. Werte, die ein Semikolon, ein einfaches oder ein doppeltes Anführungszeichen enthalten, müssen in doppelte Anführungszeichen eingeschlossen werden. Wenn der Wert sowohl ein Semikolon als auch ein doppeltes Anführungszeichen enthält, muss er in einfache Anführungszeichen eingeschlossen werden. Einfache Anführungszeichen sind auch sinnvoll, wenn der Wert mit einem doppelten Anführungszeichen beginnt. Genauso können doppelte Anführungszeichen verwendet werden, wenn der Wert mit einem einfachen Anführungszeichen beginnt. Wenn der Wert sowohl einfache als auch doppelte Anführungszeichen enthält, müssen die Anführungszeichen, die den Wert umschließen, innerhalb des Werts immer doppelt verwendet werden.

Wenn führende oder nachstehende Leerzeichen in einen Zeichenfolgenwert eingeschlossen werden sollen, muss der Wert in einfachen oder doppelten Anführungszeichen angegeben werden. Führende oder nachstehende Leerzeichen vor bzw. nach ganzzahligen, booleschen oder Enumerationswerten werden nicht berücksichtigt. Das gilt auch für den Fall, dass sie in Anführungszeichen eingeschlossen sind. Leerzeichen in einem Schlüsselwort oder Wert für Zeichenfolgenliterale werden jedoch beibehalten. In .NET Framework, Version 1.1, können einfache oder doppelte Anführungszeichen in einer Verbindungszeichenfolge ohne Trennzeichen verwendet werden (z. B. Data Source= my'Server oder Data Source= my"Server), sofern es sich weder beim ersten noch beim letzten Zeichen des Werts um ein Anführungszeichen handelt.

Wenn ein Schlüsselwort oder ein Wert ein Gleichheitszeichen (=) enthalten soll, muss diesem ein weiteres Gleichheitszeichen vorangestellt werden. Beispielsweise lautet in der hypothetischen Verbindungszeichenfolge

"key==word=value"

das Schlüsselwort "key=word", und der Wert lautet "value".

Wenn ein bestimmtes Schlüsselwort in einem Schlüsselwort-Wert-Paar mehrfach in einer Verbindungszeichenfolge auftritt, wird das zuletzt aufgelistete Auftreten im Wertesatz verwendet.

Bei Schlüsselwörtern wird die Groß- und Kleinschreibung nicht berücksichtigt.

Die folgende Tabelle enthält die gültigen Namen für die Schlüsselwortwerte im ConnectionString.

Schlüsselwort	Standardwert	Beschreibung
Application Name	N/V	Der Name der Anwendung oder '.NET SQLClient Data Provider', wenn kein Anwendungsname bereitgestellt wird.
Asynch	'false'	Wenn true, wird die Unterstützung für asynchrone Operationen aktiviert. Gültige Werte sind true, false, yes und no.
AttachDBFilename – oder – Erweiterte Eigenschaften – oder – Initial File Name	N/V	Der Name der Primärdatenbank einschließlich des vollständigen Pfadnamens einer anfügbaren Datenbank. Der Pfad kann bei Verwendung einer Ersatzzeichenfolge für DataDirectory absolut oder relativ sein. Wenn DataDirectory verwendet wird, muss die Datenbankdatei in einem Unterverzeichnis des Verzeichnisses vorhanden sein, auf das die Ersatzzeichenfolge verweist. Hinweis HTTP- und UNC-Pfadnamen für Remoteserver werden nicht unterstützt. Der Datenbankname muss mit dem Schlüsselwort 'database' (oder einem Alias) wie folgt angegeben werden: `"AttachDbFileName=\|DataDirectory\|\data\YourDB.mdf;integrated security=true;database=YourDatabase"`
Connect Timeout – oder – Connection Timeout	15	Die Zeitdauer in Sekunden, die auf eine Verbindung zum Server gewartet werden soll, bevor der Versuch abgebrochen und ein Fehler generiert wird.
Context Connection	'false'	true, wenn eine prozessinterne Verbindung zu SQL Server hergestellt werden soll.
Current Language	N/V	Der Datensatzname der SQL Server-Sprache.
Data Source – oder – Server – oder – Address – oder – Addr – oder – Network Address	N/V	Der Name oder die Netzwerkadresse der Instanz von SQL Server, mit der eine Verbindung hergestellt werden soll. Die Anschlussnummer kann nach dem Servernamen angegeben werden: `server=tcp:servername, portnumber` Wenn Sie eine lokale Instanz angeben, verwenden Sie immer (local). Um ein Protokoll zu erzwingen, fügen Sie eines der folgenden Präfixe hinzu: `np:(local), tcp:(local), lpc:(local)`
Encrypt	'false'	Wenn true, erhalten alle zwischen dem Client und dem Server gesendeten Daten von SQL Server eine SSL-Verschlüsselung, sofern auf dem Server ein Zertifikat installiert ist. Gültige Werte sind true, false, yes und no.
Enlist	'false'	true gibt an, das der Pooler die SQL Server-Verbindung automatisch in den aktuellen Transaktionskontext des Erstellungsthreads einträgt.
Failover Partner	N/V	Der Name des Failoverpartnerservers, auf dem Datenbankspiegelungen konfiguriert werden. Das Failoverpartnerschlüsselwort wird in .NET Framework, Version 1.0 oder 1.1, nicht unterstützt.
Initial Catalog – oder – Database	N/V	Der Name der Datenbank.
Integrated Security – oder – Trusted_Connection	'false'	Bei false werden die Benutzer-ID und das Kennwort für die Verbindung angegeben. Bei true werden die aktuellen Anmeldeinformationen des Windows-Kontos für die Authentifizierung verwendet. Gültige Werte sind true, false, yes, no und sspi (dringend empfohlen), wobei letzterer äquivalent zu true ist.
MultipleActiveResultSets	'true'	Bei true ist die MARS-Verarbeitung (Multiple Active Result Sets) in Anwendungen aktiviert. Bei false müssen in der Anwendung alle Resultsets eines Batchs verarbeitet oder ignoriert werden, bevor der nächste Batch in der Verbindung ausgeführt werden kann. Gültige Werte sind true und false. Das Schlüsselwort wird in .NET Framework, Version 1.0 oder 1.1, nicht unterstützt.
Network Library – oder – Net	'dbmssocn'	Die Netzwerkbibliothek, die für das Herstellen einer Verbindung zu einer Instanz von SQL Server verwendet wird. Gültige Werte sind u. a. dbnmpntw (Named Pipes), dbmsrpcn (Multiprotokoll), dbmsadsn (AppleTalk), dbmsgnet (VIA), dbmslpcn (Freigegebener Speicher), dbmsspxn (IPX/SPX) und dbmssocn (TCP/IP). Die entsprechende Netzwerk-DLL muss in dem System, mit dem Sie eine Verbindung herstellen, installiert sein. Wenn Sie kein Netzwerk angeben und einen lokalen Server verwenden (z. B. "." oder "(local)"), wird der freigegebene Speicher verwendet.
Packet Size	8192	Die Größe der Netzwerkpakete in Bytes, die zum Kommunizieren mit einer Instanz von SQL Server verwendet werden.
Password – oder – Pwd	N/V	Das Kennwort für die Anmeldung am SQL Server-Konto. Nicht empfohlen. Zur Gewährleistung einer hohen Sicherheit wird dringend empfohlen, stattdessen das Schlüsselwort Integrated Security oder Trusted_Connection zu verwenden.
Persistente Sicherheitsinformationen	'false'	Wenn der Wert auf false oder no festgelegt ist (dringend empfohlen) und die Verbindung geöffnet ist oder sich jemals im geöffneten Zustand befunden hat, werden sicherheitsrelevante Informationen, z. B. das Kennwort, nicht als Teil der Verbindung zurückgegeben. Das Zurücksetzen der Verbindungszeichenfolge setzt alle Werte der Verbindungszeichenfolge einschließlich des Kennworts zurück. Gültige Werte sind true, false, yes und no.
Replication	'false'	true, wenn Replikation mit der Verbindung unterstützt wird.
TrustServerCertificate	'false'	Wenn der Wert auf true festgelegt ist, wird SSL zum Verschlüsseln des Channels verwendet, während die Zertifikatskette für das Überprüfen der Vertrauensstellung umgangen wird. Wenn TrustServerCertificate auf true und Encrypt auf false festgelegt ist, wird der Channel nicht verschlüsselt. Gültige Werte sind true, false, yes und no. Weitere Informationen finden Sie in SQL Server 2005 Books Online unter "Encryption Hierarchy" und "Using Encryption Without Validation" (nur auf Englisch verfügbar).
Type System Version	N/V	Ein Zeichenfolgenwert, der das Typensystem angibt, dass die Anwendung erwartet. Mögliche Werte lauten: `Type System Version=SQL Server 2000;` `Type System Version=SQL Server 2005;` `Type System Version=Latest;` Bei dem Wert SQL Server 2000 wird das SQL Server 2000-Typensystem verwendet. Die folgenden Konvertierungen werden ausgeführt, wenn Sie eine Verbindung mit einer SQL Server 2005-Instanz herstellen: XML mit NTEXT UDT mit VARBINARY VARCHAR(MAX), NVARCHAR(MAX) und VARBINARY(MAX) mit TEXT, NEXT bzw. IMAGE. Bei dem Wert SQL Server 2005 wird das SQL Server 2005-Typensystem verwendet. Für die aktuelle Version von ADO.NET werden keine Konvertierungen durchgeführt. Bei dem Wert Latest wird die aktuellste Version verwendet, die dieser Client und dieser Server behandeln können. Diese wird automatisch erhöht, wenn Client- und Serverkomponente aktualisiert werden.
User ID	N/V	Das SQL Server-Anmeldekonto. Nicht empfohlen. Zur Gewährleistung einer hohen Sicherheit wird dringend empfohlen, stattdessen das Schlüsselwort Integrated Security oder Trusted_Connection zu verwenden.
User Instance	'false'	Ein Wert, 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.
Workstation ID	Der Name des lokalen Computers.	Der Name der Workstation, die eine Verbindung mit SQL Server herstellt.

In der folgenden Tabelle werden die gültigen Namen für Verbindungspoolingwerte in der ConnectionString aufgelistet. Weitere Informationen finden Sie unter Verwenden von Verbindungspooling.

Name	Standardwert	Beschreibung
Connection Lifetime	0	Wenn eine Verbindung an den Pool zurückgegeben wird, wird die Erstellungszeit mit der aktuellen Zeit verglichen. Wenn diese Zeitspanne (in Sekunden) größer ist als der für die Connection Lifetime angegebene Wert, wird die Verbindung getrennt. Dies ist hilfreich bei Gruppenkonfigurationen, um einen Lastenausgleich zwischen einem bereits aktiven Server und einem Server zu erzwingen, der gerade erst online gegangen ist. Der Wert 0 bewirkt, dass für Verbindungen in einem Pool der maximale Verbindungstimeout festgelegt wird.
Connection Reset	'true'	Legt fest, ob die Datenbankverbindung zurückgesetzt wird, wenn sie aus dem Pool entnommen wird. Wenn Sie diesen Wert für SQL Server, Version 7.0, auf false festlegen, werden zusätzliche Serverschleifen beim Abrufen einer Verbindung verhindert. Dabei dürfen Sie jedoch nicht vergessen, dass der Verbindungszustand, z. B. der Datenbankkontext, nicht zurückgesetzt wird. Der Verbindungspooler wird von ChangeDatabase nicht beeinflusst, solange Connection Reset nicht auf false festgelegt wird. Beim Abruf der Verbindung aus dem Pool wird sie wiederhergestellt, wobei der Server erneut eine Verbindung zu der zur Anmeldezeit aktiven Datenbank herstellt. Es werden keine neuen Verbindungen erstellt oder erneute Authentifizierungen durchgeführt. Wenn Sie Connection Reset auf false festlegen, können sich im Pool Verbindungen zu anderen Datenbanken ergeben.
Enlist	'true'	Wenn true, trägt der Pooler die Verbindung automatisch in den aktuellen Transaktionskontext des Erstellungsthreads ein. Gültige Werte sind true, false, yes und no.
Load Balance Timeout	0	Die minimale Zeitdauer in Sekunden, die die Verbindung im Verbindungspool verbleiben soll, bevor sie zerstört wird.
Max Pool Size	100	Die maximale Anzahl von Verbindungen, die für diesen Pool zulässig sind.
Min Pool Size	0	Die Mindestanzahl von Verbindungen, die für diesen Pool zulässig sind.
Pooling	'true'	Wenn true, wird das SQLConnection-Objekt aus dem entsprechenden Pool entnommen, oder es wird ggf. erstellt und dem entsprechenden Pool hinzugefügt. Gültige Werte sind true, false, yes und no.

Beim Festlegen von Schlüsselwort- oder Verbindungspoolingwerten, die einen booleschen Wert erfordern, können Sie 'yes' anstelle von 'true' und 'no' anstelle von 'false' verwenden. Ganzzahlwerte werden als Zeichenfolgen dargestellt.

Hinweis

Der .NET Framework-Datenprovider für SQL Server verwendet ein eigenes Protokoll für die Kommunikation mit SQL Server. Da keine ODBC-Ebene hinzugefügt wird, unterstützt er bei Verbindungen mit SQL Server keine ODBC-Datenquellennamen (DSN).

Warnung

In dieser Version ist Vorsicht geboten, wenn in der Anwendung für das Erstellen einer Verbindungszeichenfolge Benutzereingaben zugrunde gelegt werden, d. h., wenn z. B. Daten zur Benutzer-ID und zum Kennwort aus einem Dialogfeld abgerufen und an die Verbindungszeichenfolge angefügt werden. In der Anwendung muss sichergestellt sein, dass Benutzer keine zusätzlichen Parameter für die Verbindungszeichenfolge in diese Werte einbetten können, (z. B. durch Eingabe eines Kennworts als "validpassword;database=somedb", um so eine Verbindung mit einer anderen Datenbank herzustellen).

Beispiel

Im folgenden Beispiel wird eine SqlConnection erstellt und die ConnectionString-Eigenschaft vor dem Öffnen der Verbindung festgelegt.

Private Sub OpenSqlConnection()
    Dim connectionString As String = GetConnectionString()

    Using connection As New SqlConnection()

        connection.ConnectionString = connectionString

        connection.Open()

        Console.WriteLine("State: {0}", connection.State)
        Console.WriteLine("ConnectionString: {0}", _
            connection.ConnectionString)
    End Using
End Sub

Private Function GetConnectionString() As String
    ' To avoid storing the connection string in your code,  
    ' you can retrieve it from a configuration file, using the
    ' System.Configuration.ConfigurationSettings.AppSettings property
    Return "Data Source=(local);Database=AdventureWorks;" _
      & "Integrated Security=SSPI;"
End Function

private static void OpenSqlConnection()
{
    string connectionString = GetConnectionString();

    using (SqlConnection connection = new SqlConnection())
    {
        connection.ConnectionString = connectionString;

        connection.Open();

        Console.WriteLine("State: {0}", connection.State);
        Console.WriteLine("ConnectionString: {0}",
            connection.ConnectionString);
    }
}

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

Plattformen

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile für Pocket PC, Windows Mobile für Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

.NET Framework unterstützt nicht alle Versionen sämtlicher Plattformen. Eine Liste der unterstützten Versionen finden Sie unter Systemanforderungen.

Versionsinformationen

.NET Framework

Unterstützt in: 2.0, 1.1, 1.0

.NET Compact Framework

Unterstützt in: 2.0, 1.0

Siehe auch

Referenz

SqlConnection-Klasse
SqlConnection-Member
System.Data.SqlClient-Namespace

Weitere Ressourcen

Verbinden und Abrufen von Daten mit ADO.NET
Verwenden des .NET Framework-Datenanbieters für SQL Server
Arbeiten mit Verbindungszeichenfolgen
Sichern von Verbindungszeichenfolgen

Freigeben über