SqlConnection Klasse

Definition

Namespace:

System.Data.SqlClient

Assembly:

System.Data.dll

Stellt eine Verbindung zu einer SQL Server-Datenbank dar. Diese Klasse kann nicht vererbt werden.

public ref class SqlConnection sealed : System::Data::Common::DbConnection, ICloneable

public sealed class SqlConnection : System.Data.Common.DbConnection, ICloneable

type SqlConnection = class
    inherit DbConnection
    interface ICloneable

Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable

Vererbung

Object

MarshalByRefObject

Component

DbConnection

SqlConnection

Implementiert

ICloneable

Beispiele

Im folgenden Beispiel werden ein SqlCommand und ein SqlConnectionerstellt. Wird SqlConnection geöffnet und als für ConnectionSqlCommandfestgelegt. Im Beispiel wird dann aufgerufen ExecuteNonQuery. Um dies zu erreichen, wird eine ExecuteNonQuery SqlConnection- und eine Abfragezeichenfolge übergeben, die eine Transact-SQL INSERT-Anweisung ist. Die Verbindung wird automatisch geschlossen, wenn der Code den using-Block beendet.

private static void CreateCommand(string queryString,
    string connectionString)
{
    using (SqlConnection connection = new SqlConnection(
               connectionString))
    {
        SqlCommand command = new SqlCommand(queryString, connection);
        command.Connection.Open();
        command.ExecuteNonQuery();
    }
}

Public Sub CreateCommand(ByVal queryString As String, _
  ByVal connectionString As String)
    Using connection As New SqlConnection(connectionString)
        Dim command As New SqlCommand(queryString, connection)
        command.Connection.Open()
        command.ExecuteNonQuery()
    End Using
End Sub

Hinweise

Ein SqlConnection -Objekt stellt eine eindeutige Sitzung für eine SQL Server-Datenquelle dar. Bei einem Client-/Server-Datenbanksystem entspricht dies einer Netzwerkverbindung mit dem Server. SqlConnection wird zusammen mit SqlDataAdapter und SqlCommand verwendet, um die Leistung beim Herstellen einer Verbindung mit einer Microsoft SQL Server-Datenbank zu erhöhen. Verwenden Sie OleDbConnectionfür alle SQL Server-Produkte von Drittanbietern und andere OLE DB-unterstützte Datenquellen.

Wenn Sie eine Instanz von SqlConnectionerstellen, werden alle Eigenschaften auf ihre Anfangswerte festgelegt. Eine Liste dieser Werte finden Sie im SqlConnection Konstruktor.

Eine Liste der Schlüsselwörter in einer Verbindungszeichenfolge finden Sie ConnectionString unter.

Wenn der SqlConnection außerhalb des Gültigkeitsbereichs liegt, wird es nicht geschlossen. Daher müssen Sie die Verbindung explizit schließen, indem Sie oder DisposeaufrufenClose. Close und Dispose funktional gleichwertig sind. Wenn der Wert Pooling für das Verbindungspooling auf true oder yesfestgelegt ist, wird die zugrunde liegende Verbindung an den Verbindungspool zurückgegeben. Wenn hingegen auf false oder nofestgelegt ist, Pooling wird die zugrunde liegende Verbindung mit dem Server tatsächlich geschlossen.

Hinweis

Wenn eine Verbindung aus dem Verbindungspool abgerufen oder an diesen zurückgegeben wird, werden keine Anmelde- und Abmeldeereignisse auf dem Server ausgelöst, da die Verbindung bei der Rückgabe an den Verbindungspool nicht geschlossen wird. Weitere Informationen finden Sie unter SQL Server-Verbindungspooling (ADO.NET).

Um sicherzustellen, dass Verbindungen immer geschlossen werden, öffnen Sie die Verbindung in einem using Block, wie im folgenden Codefragment gezeigt. Dadurch wird sichergestellt, dass die Verbindung automatisch geschlossen wird, wenn der Code den Block beendet.

Using connection As New SqlConnection(connectionString)
    connection.Open()
    ' Do work here; connection closed on following line.
End Using

using (SqlConnection connection = new SqlConnection(connectionString))
    {
        connection.Open();
        // Do work here; connection closed on following line.
    }

Hinweis

Um hochleistungsfähige Anwendungen bereitzustellen, müssen Sie verbindungspooling verwenden. Wenn Sie den .NET Framework-Datenanbieter für SQL Server verwenden, müssen Sie das Verbindungspooling nicht aktivieren, da der Anbieter dies automatisch verwaltet, obwohl Sie einige Einstellungen ändern können. Weitere Informationen finden Sie unter SQL Server-Verbindungspooling (ADO.NET).

Wenn ein SqlException von der Methode generiert wird, die ein SqlCommandausführt, bleibt geöffnet SqlConnection , wenn der Schweregrad 19 oder weniger beträgt. Wenn der Schweregrad 20 oder höher ist, schließt der Server normalerweise den SqlConnection. Die Benutzer können die Verbindung aber erneut öffnen und fortfahren.

Eine Anwendung, die eine Instanz des SqlConnection -Objekts erstellt, kann erfordern, dass alle direkten und indirekten Aufrufer über ausreichende Berechtigungen für den Code verfügen, indem deklarative oder imperative Sicherheitsanforderungen festgelegt werden. SqlConnection stellt Sicherheitsanforderungen unter Verwendung des SqlClientPermission -Objekts. Benutzer können mithilfe des SqlClientPermissionAttribute -Objekts überprüfen, ob ihr Code über ausreichende Berechtigungen verfügt. Benutzer und Administratoren können auch das Caspol.exe (Code Access Security Policy Tool) verwenden, um die Sicherheitsrichtlinie auf Computer-, Benutzer- und Unternehmensebene zu ändern. Weitere Informationen finden Sie unter Sicherheit in .NET. Ein Beispiel für die Verwendung von Sicherheitsanforderungen finden Sie unter Codezugriffssicherheit und ADO.NET.

Weitere Informationen zum Behandeln von Warnungen und Informationsmeldungen vom Server finden Sie unter Verbindungsereignisse. Weitere Informationen zu Fehlern und Fehlermeldungen der SQL Server-Engine finden Sie unter Ereignisse und Fehler der Datenbank-Engine.

Achtung

Sie können TCP anstelle des freigegebenen Arbeitsspeichers erzwingen. Sie können dies tun, indem Sie tcp: dem Servernamen in der Verbindungszeichenfolge voran stellen, oder Sie können localhost verwenden.

Konstruktoren

SqlConnection()	Initialisiert eine neue Instanz der SqlConnection-Klasse.
SqlConnection(String)	Initialisiert eine neue Instanz der SqlConnection-Klasse, sofern eine Zeichenfolge mit der Verbindungszeichenfolge angegeben wird.
SqlConnection(String, SqlCredential)	Initialisiert eine neue Instanz der SqlConnection-Klasse mit einer Verbindungszeichenfolge, die weder Integrated Security = true noch ein SqlCredential-Objekt verwendet, das die Benutzer-ID und das Kennwort enthält.

Eigenschaften

AccessToken	Ruft das Zugriffstoken für die Verbindung ab oder legt es fest.
CanCreateBatch	Ruft einen Wert ab, der angibt, ob diese DbConnection-Instanz die DbBatch-Klasse unterstützt (Geerbt von DbConnection)
CanRaiseEvents	Ruft einen Wert ab, der angibt, ob die Komponente ein Ereignis auslösen kann. (Geerbt von Component)
ClientConnectionId	Die Verbindungs-ID der letzten Verbindungsversuchs, unabhängig davon, ob der Versuch erfolgreich war oder fehlgeschlagen ist.
ColumnEncryptionKeyCacheTtl	Ruft die Gültigkeitsdauer der Einträge für die Spaltenverschlüsselungsschlüssel im entsprechenden Cache für das Always Encrypted-Feature ab oder legt die Dauer fest. Der Standardwert ist 2 Stunden. 0 bedeutet, dass keine Zwischenspeicherung stattfindet.
ColumnEncryptionQueryMetadataCacheEnabled	Ruft einen Wert ab, der angibt, ob das Zwischenspeichern von Abfragemetadaten für parametrisierte Abfragen in Always Encrypted-fähigen Datenbanken aktiviert (TRUE) oder nicht aktiviert (FALSE) ist, oder legt diesen Wert fest. Der Standardwert ist true.
ColumnEncryptionTrustedMasterKeyPaths	Ermöglicht Ihnen, eine Liste von vertrauenswürdigen Schlüsselpfaden für einen Datenbankserver festzulegen. Wenn der Treiber während der Verarbeitung einer Anwendungsabfrage einen Schlüsselpfad empfängt, der nicht in der Liste enthalten ist, schlägt die Abfrage fehl. Diese Eigenschaft bietet zusätzlichen Schutz vor Angriffen, bei denen ein kompromittierter SQL Server gefälschte Schlüsselpfade bereitstellt, was zu Verlusten von Schlüsselspeicher-Anmeldeinformationen führen kann.
ConnectionString	Ruft die Zeichenfolge ab, mit der eine SQL Server-Datenbank geöffnet wird, oder legt diese fest.
ConnectionTimeout	Ruft die Zeit (in Sekunden) ab, die beim Verbindungsaufbau gewartet werden soll, bis der Versuch beendet und ein Fehler generiert wird.
Container	Ruft die IContainer ab, die in der Component enthalten ist. (Geerbt von Component)
Credential	Ruft das SqlCredential-Objekt für diese Verbindung ab, oder legt es fest.
Database	Ruft den Namen der aktuellen Datenbank oder der nach dem Öffnen einer Verbindung zu verwendenden Datenbank ab.
DataSource	Ruft den Namen der SQL Server-Instanz ab, mit der eine Verbindung hergestellt werden soll.
DbProviderFactory	Ruft den DbProviderFactory für diesen DbConnection ab. (Geerbt von DbConnection)
DesignMode	Ruft einen Wert ab, der angibt, ob sich Component gegenwärtig im Entwurfsmodus befindet. (Geerbt von Component)
Events	Ruft die Liste der Ereignishandler ab, die dieser Component angefügt sind. (Geerbt von Component)
FireInfoMessageEventOnUserErrors	Ruft die FireInfoMessageEventOnUserErrors-Eigenschaft ab oder legt diese fest.
PacketSize	Ruft die Größe der Netzwerkpakete in Bytes ab, die zum Kommunizieren mit einer Instanz von SQL Server verwendet werden.
ServerVersion	Ruft eine Zeichenfolge mit der Version der SQL Server-Instanz ab, mit der der Client verbunden ist.
Site	Ruft den ISite von Component ab oder legt ihn fest. (Geerbt von Component)
State	Gibt den Zustand von SqlConnection während des letzten Netzwerkvorgangs an, der für die Verbindung ausgeführt wurde.
StatisticsEnabled	Wenn true, wird für die aktuelle Verbindung die Statistikdatenerhebung aktiviert.
WorkstationId	Ruft eine Zeichenfolge ab, die den Datenbankclient bezeichnet.

Methoden

BeginDbTransaction(IsolationLevel)	Startet beim Überschreiben in einer abgeleiteten Klasse eine Datenbanktransaktion (Geerbt von DbConnection)
BeginDbTransactionAsync(IsolationLevel, CancellationToken)	Startet asynchron eine Datenbanktransaktion (Geerbt von DbConnection)
BeginTransaction()	Startet eine Datenbanktransaktion.
BeginTransaction(IsolationLevel)	Startet eine Datenbanktransaktion mit dem angegebenen Isolationsgrad.
BeginTransaction(IsolationLevel, String)	Startet eine Datenbanktransaktion mit dem angegebenen Isolationsgrad und Transaktionsnamen.
BeginTransaction(String)	Startet eine Datenbanktransaktion mit dem angegebenen Transaktionsnamen.
BeginTransactionAsync(CancellationToken)	Startet asynchron eine Datenbanktransaktion (Geerbt von DbConnection)
BeginTransactionAsync(IsolationLevel, CancellationToken)	Startet asynchron eine Datenbanktransaktion (Geerbt von DbConnection)
ChangeDatabase(String)	Ändert die aktuelle Datenbank für eine offene SqlConnection.
ChangeDatabaseAsync(String, CancellationToken)	Ändert asynchron die aktuelle Datenbank für eine offene Verbindung (Geerbt von DbConnection)
ChangePassword(String, SqlCredential, SecureString)	Ändert das SQL Server-Kennwort für den Benutzer, der im SqlCredential-Objekt angegeben wird.
ChangePassword(String, String)	Ändert das SQL Server-Kennwort für den Benutzer, der in der Verbindungszeichenfolge zum bereitgestellten neuen Kennwort angegeben ist.
ClearAllPools()	Leert den Verbindungspool.
ClearPool(SqlConnection)	Leert den der angegebenen Verbindung zugeordneten Verbindungspool.
Close()	Schließt die Verbindung mit der Datenbank. Dies ist die bevorzugte Methode zum Schließen offener Verbindungen.
CloseAsync()	Schließt asynchron die Verbindung mit der Datenbank (Geerbt von DbConnection)
CreateBatch()	Gibt eine neue Instanz der Klasse des Anbieters zurück, die die DbBatch-Klasse implementiert. (Geerbt von DbConnection)
CreateCommand()	Erstellt ein SqlCommand-Objekt, das der SqlConnection zugeordnet ist, und gibt es zurück.
CreateDbBatch()	Gibt beim Überschreiben in einer abgeleiteten Klasse eine neue Instanz der Klasse des Anbieters zurück, die die DbBatch -Klasse implementiert. (Geerbt von DbConnection)
CreateDbCommand()	Erstellt beim Überschreiben in einer abgeleiteten Klasse ein DbCommand-Objekt, das der aktuellen Verbindung zugeordnet ist, und gibt es zurück (Geerbt von DbConnection)
CreateObjRef(Type)	Erstellt ein Objekt mit allen relevanten Informationen, die zum Generieren eines Proxys für die Kommunikation mit einem Remoteobjekt erforderlich sind. (Geerbt von MarshalByRefObject)
Dispose()	Führt anwendungsspezifische Aufgaben durch, die mit der Freigabe, der Zurückgabe oder dem Zurücksetzen von nicht verwalteten Ressourcen zusammenhängen. (Geerbt von DbConnection)
Dispose(Boolean)	Gibt die von DbConnection verwendeten nicht verwalteten Ressourcen und optional die verwalteten Ressourcen frei. (Geerbt von DbConnection)
DisposeAsync()	Stellt das Verbindungsobjekt asynchron bereit (Geerbt von DbConnection)
EnlistDistributedTransaction(ITransaction)	Trägt sich in der angegebenen Transaktion als verteilte Transaktion ein.
EnlistTransaction(Transaction)	Trägt sich in der angegebenen Transaktion als verteilte Transaktion ein.
Equals(Object)	Bestimmt, ob das angegebene Objekt gleich dem aktuellen Objekt ist. (Geerbt von Object)
GetHashCode()	Fungiert als Standardhashfunktion. (Geerbt von Object)
GetLifetimeService()	Ruft das aktuelle Lebensdauerdienstobjekt ab, das die Lebensdauerrichtlinien für diese Instanz steuert. (Geerbt von MarshalByRefObject)
GetSchema()	Gibt Schemainformationen für die Datenquelle dieser SqlConnection zurück. Weitere Informationen zu Schemas finden Sie unter SQL Server-Schemaauflistungen.
GetSchema(String)	Gibt Schemainformationen für die Datenquelle dieser SqlConnection mithilfe der angegebenen Zeichenfolge des Schemanamens zurück.
GetSchema(String, String[])	Gibt Schemainformationen für die Datenquelle dieser SqlConnection mithilfe der angegebenen Zeichenfolge des Schemanamens und des angegebenen Zeichenfolgenarrays der Einschränkungswerte zurück.
GetSchemaAsync(CancellationToken)	Dies ist eine asynchrone Version von GetSchema(). Anbieter sollten mit einer entsprechenden Implementierung überschreiben. Das cancellationToken kann optional berücksichtigt werden. Die Standardimplementierung ruft den asynchronen GetSchema()-Aufruf auf und gibt eine abgeschlossene Aufgabe zurück. Die Standardimplementierung gibt eine abgebrochene Aufgabe zurück, wenn sie einen bereits abgebrochenen cancellationToken erhalten wird. Die Ausnahmen, die von GetSchema() ausgelöst werden, werden über die zurückgegebene Task Exception-Eigenschaft übermittelt. (Geerbt von DbConnection)
GetSchemaAsync(String, CancellationToken)	Dies ist die asynchrone Version von GetSchema(String). Anbieter sollten mit einer entsprechenden Implementierung überschreiben. Das cancellationToken kann optional berücksichtigt werden. Die Standardimplementierung ruft den asynchronen GetSchema(String)-Aufruf auf und gibt eine abgeschlossene Aufgabe zurück. Die Standardimplementierung gibt eine abgebrochene Aufgabe zurück, wenn sie einen bereits abgebrochenen cancellationToken erhalten wird. Die Ausnahmen, die von GetSchema(String) ausgelöst werden, werden über die zurückgegebene Task Exception-Eigenschaft übermittelt. (Geerbt von DbConnection)
GetSchemaAsync(String, String[], CancellationToken)	Dies ist die asynchrone Version von GetSchema(String, String[]). Anbieter sollten mit einer entsprechenden Implementierung überschreiben. Das cancellationToken kann optional berücksichtigt werden. Die Standardimplementierung ruft den asynchronen GetSchema(String, String[])-Aufruf auf und gibt eine abgeschlossene Aufgabe zurück. Die Standardimplementierung gibt eine abgebrochene Aufgabe zurück, wenn sie einen bereits abgebrochenen cancellationToken erhalten wird. Die Ausnahmen, die von GetSchema(String, String[]) ausgelöst werden, werden über die zurückgegebene Task Exception-Eigenschaft übermittelt. (Geerbt von DbConnection)
GetService(Type)	Gibt ein Objekt zurück, das einen von der Component oder von deren Container bereitgestellten Dienst darstellt. (Geerbt von Component)
GetType()	Ruft den Type der aktuellen Instanz ab. (Geerbt von Object)
InitializeLifetimeService()	Ruft ein Lebensdauerdienstobjekt zur Steuerung der Lebensdauerrichtlinie für diese Instanz ab. (Geerbt von MarshalByRefObject)
MemberwiseClone()	Erstellt eine flache Kopie des aktuellen Object. (Geerbt von Object)
MemberwiseClone(Boolean)	Erstellt eine flache Kopie des aktuellen MarshalByRefObject-Objekts. (Geerbt von MarshalByRefObject)
OnStateChange(StateChangeEventArgs)	Löst das StateChange-Ereignis aus. (Geerbt von DbConnection)
Open()	Öffnet eine Datenbankverbindung mit den von der ConnectionString angegebenen Eigenschafteneinstellungen.
OpenAsync()	Eine asynchrone Version von Open(), die eine Datenbankverbindung mit den Einstellungen öffnet, die durch ConnectionString angegeben werden. Diese Methode ruft die virtuelle Methode OpenAsync(CancellationToken) mit CancellationToken.None auf. (Geerbt von DbConnection)
OpenAsync(CancellationToken)	Eine asynchrone Version von Open(), die eine Datenbankverbindung mit den Eigenschaftseinstellungen öffnet, die durch ConnectionString angegeben sind. Das Abbruchtoken kann verwendet werden, um anzufordern, dass der Vorgang abgebrochen wird, bevor das Timeout der Verbindung abläuft. Ausnahmen werden über die zurückgegebene Aufgabe weitergegeben. Wenn die Timeout-Zeit für die Verbindung abläuft, ohne die Verbindung erfolgreich herzustellen, wird die zurückgegebene Aufgabe als fehlgeschlagen mit einer Ausnahme markiert. Die Implementierung gibt eine Aufgabe zurück, ohne den aufrufenden Verbindungs-Thread zu blockieren (gilt auch für Pool-Verbindungen).
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Registriert die Schlüsselspeicheranbieter für die Spaltenverschlüsselung.
ResetStatistics()	Wenn die Statistikdatenerhebung aktiviert wird, werden alle Werte auf 0 (null) zurückgesetzt.
RetrieveStatistics()	Gibt eine Auflistung von Name-Wert-Paaren statistischer Daten zum Zeitpunkt des Methodenaufrufs zurück.
ToString()	Gibt einen String zurück, der den Namen der Component enthält (sofern vorhanden). Diese Methode darf nicht überschrieben werden. (Geerbt von Component)

Ereignisse

Disposed	Tritt auf, wenn die Komponente von einem Aufruf der Dispose()-Methode verworfen wird. (Geerbt von Component)
InfoMessage	Tritt ein, wenn SQL Server eine Warn- oder Informationsmeldung zurückgibt.
StateChange	Tritt auf, wenn sich der Status der Verbindung ändert. (Geerbt von DbConnection)

Explizite Schnittstellenimplementierungen

ICloneable.Clone()	Erstellt ein neues Objekt, das eine Kopie der aktuellen Instanz darstellt.
IDbConnection.BeginTransaction()	Beginnt eine Datenbanktransaktion. (Geerbt von DbConnection)
IDbConnection.BeginTransaction(IsolationLevel)	Beginnt eine Datenbanktransaktion mit der angegebenen Isolationsstufe. (Geerbt von DbConnection)
IDbConnection.CreateCommand()	Erstellt ein DbCommand-Objekt, das der aktuellen Verbindung zugeordnet ist, und gibt dieses zurück. (Geerbt von DbConnection)

Weitere Informationen

• Verbinden mit einer Datenquelle in ADO.NET
• SQL Server und ADO.NET
• Übersicht über ADO.NET