SqlConnection Klasse

Definition

Namespace:

System.Data.SqlClient

Assembly:

System.Data.dll

Stellt eine Verbindung mit einer SQL Server-Datenbank dar. Diese Klasse kann nicht geerbt 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 wird ein SqlCommand und ein SqlConnectionerstellt. Die SqlConnection wird geöffnet und als Connection für die SqlCommandfestgelegt. Anschließend wird ExecuteNonQueryaufgerufen. Dazu wird die ExecuteNonQuery eine SqlConnection und eine Abfragezeichenfolge übergeben, die eine Transact-SQL INSERT-Anweisung ist. Die Verbindung wird automatisch geschlossen, wenn der Code den using-Block verlässt.

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-/Serverdatenbanksystem entspricht es 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 für alle SQL Server-Produkte von Drittanbietern und andere ole DB-unterstützte Datenquellen OleDbConnection.

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 unter ConnectionString.

Wenn die SqlConnection nicht mehr gültig ist, wird sie nicht geschlossen. Daher müssen Sie die Verbindung explizit schließen, indem Sie Close oder Disposeaufrufen. Close und Dispose sind funktional gleichwertig. Wenn der Wert für den Verbindungspooling Pooling auf true oder yesfestgelegt ist, wird die zugrunde liegende Verbindung zurück an den Verbindungspool zurückgegeben. Wenn Pooling andererseits auf false oder nofestgelegt ist, wird die zugrunde liegende Verbindung mit dem Server tatsächlich geschlossen.

Anmerkung

Anmelde- und Abmeldeereignisse werden nicht auf dem Server ausgelöst, wenn eine Verbindung aus dem Verbindungspool abgerufen oder zurückgegeben wird, da die Verbindung nicht tatsächlich geschlossen wird, wenn sie an den Verbindungspool zurückgegeben wird. Weitere Informationen finden Sie unter SQL Server Connection Pooling (ADO.NET).

Um sicherzustellen, dass Verbindungen immer geschlossen sind, öffnen Sie die Verbindung innerhalb eines using Blocks, wie im folgenden Codefragment gezeigt. Dadurch wird sichergestellt, dass die Verbindung automatisch geschlossen wird, wenn der Code den Block verlässt.

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.
    }

Anmerkung

Um leistungsstarke 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 Connection Pooling (ADO.NET).

Wenn eine SqlException durch die Methode generiert wird, die eine SqlCommandausführt, bleibt die SqlConnection geöffnet, wenn der Schweregrad 19 oder weniger beträgt. Wenn der Schweregrad 20 oder höher ist, schließt der Server die SqlConnection. Der Benutzer kann die Verbindung jedoch 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 sie deklarative oder imperative Sicherheitsanforderungen festlegen. SqlConnection stellt Sicherheitsanforderungen mithilfe des SqlClientPermission Objekts. Benutzer können überprüfen, ob ihr Code über ausreichende Berechtigungen verfügt, indem sie das SqlClientPermissionAttribute-Objekt verwenden. Benutzer und Administratoren können auch das Caspol.exe (Code Access Security Policy Tool) verwenden, um sicherheitsrichtlinien auf Computer-, Benutzer- und Unternehmensebene zu ändern. Weitere Informationen finden Sie unter Security in .NET. Ein Beispiel für die Verwendung von Sicherheitsanforderungen finden Sie unter Codezugriffssicherheit und ADO.NET.

Weitere Informationen zum Behandeln von Warnungs- und Informationsmeldungen vom Server finden Sie unter Verbindungsereignisse. Weitere Informationen zu SQL Server-Modulfehlern und Fehlermeldungen finden Sie unter Datenbankmodulereignisse und -fehler.

Vorsicht

Sie können TCP anstelle des freigegebenen Speichers erzwingen. Dazu können Sie tcp: dem Servernamen in der Verbindungszeichenfolge voranstellen oder localhost verwenden.

Konstruktoren

SqlConnection()	Initialisiert eine neue Instanz der SqlConnection Klasse.
SqlConnection(String, SqlCredential)	Initialisiert eine neue Instanz der SqlConnection Klasse mit einer Verbindungszeichenfolge, die nicht Integrated Security = true und ein SqlCredential -Objekt verwendet, das die Benutzer-ID und das Kennwort enthält.
SqlConnection(String)	Initialisiert eine neue Instanz der SqlConnection Klasse, wenn eine Zeichenfolge angegeben wird, die die Verbindungszeichenfolge 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 des letzten Verbindungsversuchs, unabhängig davon, ob der Versuch erfolgreich war oder fehlgeschlagen ist.
ColumnEncryptionKeyCacheTtl	Dient zum Abrufen oder Festlegen der Zeit-zu-Live für Spaltenverschlüsselungsschlüsseleinträge im Spaltenverschlüsselungsschlüsselcache für das Feature Always Encrypted. Der Standardwert beträgt 2 Stunden. 0 bedeutet überhaupt keine Zwischenspeicherung.
ColumnEncryptionQueryMetadataCacheEnabled	Dient zum Abrufen oder Festlegen eines Werts, der angibt, ob die Zwischenspeicherung von Abfragemetadaten für parametrisierte Abfragen aktiviert ist, die für Always Encrypted aktivierten Datenbanken ausgeführt werden. Der Standardwert ist true.
ColumnEncryptionTrustedMasterKeyPaths	Ermöglicht das Festlegen einer Liste der vertrauenswürdigen Schlüsselpfade für einen Datenbankserver. Wenn beim Verarbeiten einer Anwendungsabfrage der Treiber einen Schlüsselpfad empfängt, der nicht in der Liste enthalten ist, schlägt die Abfrage fehl. Diese Eigenschaft bietet zusätzlichen Schutz vor Sicherheitsangriffen, die einen kompromittierten SQL Server umfassen, der gefälschte Schlüsselpfade bereitstellt, was zu einem Verlust von Schlüsselspeicheranmeldeinformationen führen kann.
ConnectionString	Dient zum Abrufen oder Festlegen der Zeichenfolge, die zum Öffnen einer SQL Server-Datenbank verwendet wird.
ConnectionTimeout	Ruft die Wartezeit (in Sekunden) ab, während versucht wird, eine Verbindung herzustellen, bevor der Versuch beendet und ein Fehler generiert wird.
Container	Ruft die IContainer ab, die den Componententhält. (Geerbt von Component)
Credential	Dient zum Abrufen oder Festlegen des SqlCredential-Objekts für diese Verbindung.
Database	Ruft den Namen der aktuellen Datenbank oder der Datenbank ab, die nach dem Öffnen einer Verbindung verwendet werden soll.
DataSource	Ruft den Namen der Instanz von SQL Server ab, mit der eine Verbindung hergestellt werden soll.
DbProviderFactory	Ruft die DbProviderFactory für diese DbConnectionab. (Geerbt von DbConnection)
DesignMode	Ruft einen Wert ab, der angibt, ob sich die Component derzeit im Entwurfsmodus befindet. (Geerbt von Component)
Events	Ruft die Liste der Ereignishandler ab, die an diese Componentangefügt sind. (Geerbt von Component)
FireInfoMessageEventOnUserErrors	Dient zum Abrufen oder Festlegen der FireInfoMessageEventOnUserErrors-Eigenschaft.
PacketSize	Ruft die Größe (in Byte) von Netzwerkpaketen ab, die für die Kommunikation mit einer Instanz von SQL Server verwendet werden.
ServerVersion	Ruft eine Zeichenfolge ab, die die Version der Instanz von SQL Server enthält, mit der der Client verbunden ist.
Site	Dient zum Abrufen oder Festlegen des ISite des Component. (Geerbt von Component)
State	Gibt den Status des SqlConnection während des letzten Netzwerkvorgangs an, der für die Verbindung ausgeführt wurde.
StatisticsEnabled	Wenn diese Einstellung auf truefestgelegt ist, können Statistiken für die aktuelle Verbindung erfasst werden.
WorkstationId	Ruft eine Zeichenfolge ab, die den Datenbankclient identifiziert.

Methoden

BeginDbTransaction(IsolationLevel)	Wenn eine abgeleitete Klasse überschrieben wird, wird eine Datenbanktransaktion gestartet. (Geerbt von DbConnection)
BeginDbTransactionAsync(IsolationLevel, CancellationToken)	Startet asynchron eine Datenbanktransaktion. (Geerbt von DbConnection)
BeginTransaction()	Startet eine Datenbanktransaktion.
BeginTransaction(IsolationLevel, String)	Startet eine Datenbanktransaktion mit der angegebenen Isolationsstufe und dem Transaktionsnamen.
BeginTransaction(IsolationLevel)	Startet eine Datenbanktransaktion mit der angegebenen Isolationsstufe.
BeginTransaction(String)	Startet eine Datenbanktransaktion mit dem angegebenen Transaktionsnamen.
BeginTransactionAsync(CancellationToken)	Beginnt asynchron eine Datenbanktransaktion. (Geerbt von DbConnection)
BeginTransactionAsync(IsolationLevel, CancellationToken)	Beginnt asynchron eine Datenbanktransaktion. (Geerbt von DbConnection)
ChangeDatabase(String)	Ändert die aktuelle Datenbank für eine geöffnete SqlConnection.
ChangeDatabaseAsync(String, CancellationToken)	Ändert asynchron die aktuelle Datenbank für eine geöffnete Verbindung. (Geerbt von DbConnection)
ChangePassword(String, SqlCredential, SecureString)	Ändert das SQL Server-Kennwort für den im SqlCredential-Objekt angegebenen Benutzer.
ChangePassword(String, String)	Ändert das SQL Server-Kennwort für den Benutzer, der in der Verbindungszeichenfolge angegeben ist, in das angegebene neue Kennwort.
ClearAllPools()	Leert den Verbindungspool.
ClearPool(SqlConnection)	Leert den Verbindungspool, der der angegebenen Verbindung zugeordnet ist.
Close()	Schließt die Verbindung mit der Datenbank. Dies ist die bevorzugte Methode zum Schließen einer geöffneten Verbindung.
CloseAsync()	Schließt die Verbindung mit der Datenbank asynchron. (Geerbt von DbConnection)
CreateBatch()	Gibt eine neue Instanz der Anbieterklasse zurück, die die DbBatch Klasse implementiert. (Geerbt von DbConnection)
CreateCommand()	Erstellt und gibt ein SqlCommand-Objekt zurück, das dem SqlConnectionzugeordnet ist.
CreateDbBatch()	Wenn eine abgeleitete Klasse überschrieben wird, wird eine neue Instanz der Klasse des Anbieters zurückgegeben, die die DbBatch Klasse implementiert. (Geerbt von DbConnection)
CreateDbCommand()	Wenn eine abgeleitete Klasse überschrieben wird, wird ein DbCommand Objekt erstellt und zurückgegeben, das der aktuellen Verbindung zugeordnet ist. (Geerbt von DbConnection)
CreateObjRef(Type)	Erstellt ein Objekt, das alle relevanten Informationen enthält, die zum Generieren eines Proxys erforderlich sind, der für die Kommunikation mit einem Remoteobjekt verwendet wird. (Geerbt von MarshalByRefObject)
Dispose()	Führt anwendungsdefinierte Aufgaben aus, die mit dem Freigeben, Freigeben oder Zurücksetzen nicht verwalteter Ressourcen verknüpft sind. (Geerbt von DbConnection)
Dispose(Boolean)	Gibt die nicht verwalteten Ressourcen frei, die vom DbConnection verwendet werden, und gibt optional die verwalteten Ressourcen frei. (Geerbt von DbConnection)
DisposeAsync()	Das Verbindungsobjekt wird asynchron eingetaucht. (Geerbt von DbConnection)
EnlistDistributedTransaction(ITransaction)	Enlists in der angegebenen Transaktion als verteilte Transaktion.
EnlistTransaction(Transaction)	Enlists in der angegebenen Transaktion als verteilte Transaktion.
Equals(Object)	Bestimmt, ob das angegebene Objekt dem aktuellen Objekt entspricht. (Geerbt von Object)
GetHashCode()	Dient als Standardhashfunktion. (Geerbt von Object)
GetLifetimeService()	Ruft das aktuelle Lebensdauerdienstobjekt ab, das die Lebensdauerrichtlinie für diese Instanz steuert. (Geerbt von MarshalByRefObject)
GetSchema()	Gibt Schemainformationen für die Datenquelle dieses SqlConnectionzurück. Weitere Informationen zum Schema finden Sie unter SQL Server Schema Collections.
GetSchema(String, String[])	Gibt Schemainformationen für die Datenquelle dieses SqlConnection zurück, wobei die angegebene Zeichenfolge für den Schemanamen und das angegebene Zeichenfolgenarray für die Einschränkungswerte verwendet wird.
GetSchema(String)	Gibt Schemainformationen für die Datenquelle dieses SqlConnection mithilfe der angegebenen Zeichenfolge für den Schemanamen zurück.
GetSchemaAsync(CancellationToken)	Dies ist eine asynchrone Version von GetSchema(). Anbieter sollten mit einer geeigneten Implementierung außer Kraft setzen. Die cancellationToken können optional berücksichtigt werden. Die Standardimplementierung ruft den synchronen GetSchema() Aufruf auf und gibt eine abgeschlossene Aufgabe zurück. Die Standardimplementierung gibt eine abgebrochene Aufgabe zurück, wenn eine bereits abgebrochene cancellationTokenübergeben wurde. Ausnahmen, die von GetSchema() ausgelöst werden, werden über die zurückgegebene Task Exception-Eigenschaft kommuniziert. (Geerbt von DbConnection)
GetSchemaAsync(String, CancellationToken)	Dies ist die asynchrone Version von GetSchema(String). Anbieter sollten mit einer geeigneten Implementierung außer Kraft setzen. Die cancellationToken können optional berücksichtigt werden. Die Standardimplementierung ruft den synchronen GetSchema(String) Aufruf auf und gibt eine abgeschlossene Aufgabe zurück. Die Standardimplementierung gibt eine abgebrochene Aufgabe zurück, wenn eine bereits abgebrochene cancellationTokenübergeben wurde. Ausnahmen, die von GetSchema(String) ausgelöst werden, werden über die zurückgegebene Task Exception-Eigenschaft kommuniziert. (Geerbt von DbConnection)
GetSchemaAsync(String, String[], CancellationToken)	Dies ist die asynchrone Version von GetSchema(String, String[]). Anbieter sollten mit einer geeigneten Implementierung außer Kraft setzen. Die cancellationToken können optional berücksichtigt werden. Die Standardimplementierung ruft den synchronen GetSchema(String, String[]) Aufruf auf und gibt eine abgeschlossene Aufgabe zurück. Die Standardimplementierung gibt eine abgebrochene Aufgabe zurück, wenn eine bereits abgebrochene cancellationTokenübergeben wurde. Ausnahmen, die von GetSchema(String, String[]) ausgelöst werden, werden über die zurückgegebene Task Exception-Eigenschaft kommuniziert. (Geerbt von DbConnection)
GetService(Type)	Gibt ein Objekt zurück, das einen Dienst darstellt, der vom Component oder von seinem Containerbereitgestellt wird. (Geerbt von Component)
GetType()	Ruft die Type der aktuellen Instanz ab. (Geerbt von Object)
InitializeLifetimeService()	Ruft ein Lebensdauerdienstobjekt ab, um die Lebensdauerrichtlinie für diese Instanz zu steuern. (Geerbt von MarshalByRefObject)
MemberwiseClone()	Erstellt eine flache Kopie der 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 eigenschafteneinstellungen, die durch die ConnectionStringangegeben werden.
OpenAsync()	Eine asynchrone Version von Open(), die eine Datenbankverbindung mit den durch die ConnectionStringangegebenen Einstellungen öffnet. 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 eigenschafteneinstellungen öffnet, die durch die ConnectionStringangegeben werden. Das Abbruchtoken kann verwendet werden, um anzufordern, dass der Vorgang abgebrochen wird, bevor das Verbindungstimeout verstrichen ist. Ausnahmen werden über den zurückgegebenen Vorgang weitergegeben. Wenn die Zeitüberschreitung der Verbindung ohne erfolgreiche Verbindung verstrichen ist, wird der zurückgegebene Vorgang mit einer Ausnahme als fehlerhaft markiert. Die Implementierung gibt eine Aufgabe zurück, ohne den aufrufenden Thread für poolierte und nicht poolierte Verbindungen zu blockieren.
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Registriert die Anbieter des Spaltenverschlüsselungsschlüsselspeichers.
ResetStatistics()	Wenn das Sammeln von Statistiken aktiviert ist, werden alle Werte auf Null zurückgesetzt.
RetrieveStatistics()	Gibt eine Name value pair collection of statistics at the point in time the method is called.
ToString()	Gibt einen String zurück, der den Namen der Componententhält, falls vorhanden. Diese Methode sollte nicht außer Kraft gesetzt werden. (Geerbt von Component)

Ereignisse

Disposed	Tritt auf, wenn die Komponente durch einen Aufruf der Dispose() -Methode verworfen wird. (Geerbt von Component)
InfoMessage	Tritt auf, wenn SQL Server eine Warnung oder Eine 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 ist.
IDbConnection.BeginTransaction()	Beginnt eine Datenbanktransaktion. (Geerbt von DbConnection)
IDbConnection.BeginTransaction(IsolationLevel)	Beginnt eine Datenbanktransaktion mit der angegebenen Isolationsstufe. (Geerbt von DbConnection)
IDbConnection.CreateCommand()	Erstellt und gibt ein DbCommand -Objekt zurück, das der aktuellen Verbindung zugeordnet ist. (Geerbt von DbConnection)

Weitere Informationen

• Herstellen einer Verbindung mit einer Datenquelle in ADO.NET
• SQL Server und ADO.NET
• ADO.NET Übersicht