SqlConnection 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.
Stellt eine Verbindung mit einer SQL Server-Datenbank dar. Diese Klasse kann nicht vererbt werden.
public ref class SqlConnection sealed : System::Data::Common::DbConnection, ICloneablepublic sealed class SqlConnection : System.Data.Common.DbConnection, ICloneabletype SqlConnection = class
inherit DbConnection
interface ICloneablePublic NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable- Vererbung
-
SqlConnection
- Implementiert
Beispiele
Im folgenden Beispiel wird eine SqlCommand und eine SqlConnection. Die SqlConnection Wird geöffnet und als für die ConnectionSqlCommand. Anschließend wird das Beispiel aufgerufen ExecuteNonQuery. Hierzu 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.
using System;
using System.Data;
using Microsoft.Data.SqlClient;
namespace SqlCommand_ExecuteNonQuery
{
class Program
{
static void Main()
{
string str = "Data Source=(local);Initial Catalog=Northwind;"
+ "Integrated Security=SSPI";
string qs = "SELECT OrderID, CustomerID FROM dbo.Orders;";
CreateCommand(qs, str);
}
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();
}
}
}
}
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 einem Microsoft SQL Server-Datenbank zu erhöhen. Verwenden Sie für alle Drittanbieter-SQL Server-Produkte und andere ole DB-unterstützte Datenquellen OleDbConnection.
Wenn Sie eine Instanz von
Eine Liste der Schlüsselwörter in einem Verbindungszeichenfolge finden Sie unter ConnectionString.
Wenn der SqlConnection Bereich nicht mehr vorhanden ist, wird er nicht geschlossen. Daher müssen Sie die Verbindung explizit durch Aufrufen oder Dispose.Close
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. Auf der anderen Seite ist die zugrunde liegende Verbindung mit dem Server tatsächlich geschlossen, wenn Pooling sie auf oder nodiese festgelegt false ist.
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 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.
}
Hinweis
Um leistungsstarke Anwendungen bereitzustellen, müssen Sie verbindungspooling verwenden. Wenn Sie das .NET Framework-Datenanbieter für SQL Server verwenden, müssen Sie die 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 von der 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 SqlConnectionder Server die . 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 die Sicherheitsrichtlinie auf Computer-, Benutzer- und Unternehmensebene zu ändern. Weitere Informationen finden Sie unter Sicherheit in .NET. Ein Beispiel zur Verwendung von Sicherheitsanforderungen finden Sie unter Code Access Security und ADO.NET.
Weitere Informationen zum Behandeln von Warnungen und Informationsmeldungen vom Server finden Sie unter "Verbindungsereignisse". Weitere Informationen zu SQL Server Modulfehlern und Fehlermeldungen finden Sie unter Datenbank-Engine Events and Errors.
Vorsicht
Sie können TCP anstelle des freigegebenen Speichers erzwingen. Dazu können Sie tcp: dem Servernamen im Verbindungszeichenfolge voranstellen oder localhost verwenden.
Konstruktoren
| Name | Beschreibung |
|---|---|
| SqlConnection() |
Initialisiert eine neue Instanz der SqlConnection-Klasse. |
| SqlConnection(String, SqlCredential) |
Initialisiert eine neue Instanz der SqlConnection Klasse mit einer Verbindungszeichenfolge, die nicht verwendet |
| SqlConnection(String) |
Initialisiert eine neue Instanz der SqlConnection Klasse, wenn eine Zeichenfolge angegeben wird, die die Verbindungszeichenfolge enthält. |
Eigenschaften
| Name | Beschreibung |
|---|---|
| AccessToken |
Ruft das Zugriffstoken für die Verbindung ab oder legt es fest. |
| AccessTokenCallback |
Ruft den Zugriffstokenrückruf für die Verbindung ab oder legt ihn fest. |
| CanCreateBatch |
Ruft einen Wert ab, der angibt, ob diese SqlConnection Instanz die DbBatch Klasse unterstützt. |
| 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 "Immer verschlüsselt ". 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, die für Always Encrypted-aktivierte Datenbanken ausgeführt werden, aktiviert ist (true) oder nicht (false) aktiviert ist. Der Standardwert lautet „true“. |
| ColumnEncryptionTrustedMasterKeyPaths |
Ermöglicht Ihnen, eine Liste von vertrauenswürdigen Schlüsselpfaden für einen Datenbankserver festzulegen. 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 eine kompromittierte SQL Server bereitstellen gefälschte Schlüsselpfade, die zu einem Verlust von Schlüsselspeicheranmeldeinformationen führen können. |
| CommandTimeout |
Ruft die Standardwartezeit (in Sekunden) ab, bevor der Versuch beendet wird, einen Befehl auszuführen und einen Fehler zu generieren. Der Standardwert ist 30 Sekunden. |
| ConnectionString |
Dient zum Abrufen oder Festlegen der Zeichenfolge, die zum Öffnen einer SQL Server-Datenbank verwendet wird. |
| ConnectionTimeout |
Ruft die Zeit zum Warten ab, während versucht wird, eine Verbindung herzustellen, bevor der Versuch beendet und ein Fehler generiert wird. |
| Credential |
Ruft ab oder legt das SqlCredential Objekt für diese Verbindung fest. |
| 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. |
| 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. |
| RetryLogicProvider |
Dient zum Abrufen oder Festlegen eines Werts, der das SqlRetryLogicBaseProvider an diesen Befehl gebundene Objekt angibt. |
| ServerProcessId |
Ruft die Serverprozess-ID (SPID) der aktiven Verbindung ab. |
| ServerVersion |
Ruft eine Zeichenfolge ab, die die Version der Instanz von SQL Server enthält, mit der der Client verbunden ist. |
| SspiContextProvider |
Dient zum Abrufen oder Festlegen der SspiContextProvider Instanz zum Anpassen des SSPI-Kontexts. Wenn sie nicht festgelegt ist, wird der Standardwert für die Plattform verwendet. |
| State |
Gibt den Status des SqlConnection während des letzten Netzwerkvorgangs an, der für die Verbindung ausgeführt wurde. |
| StatisticsEnabled |
Bei Festlegung auf |
| WorkstationId |
Ruft eine Zeichenfolge ab, die den Datenbankclient identifiziert. |
Methoden
| Name | Beschreibung |
|---|---|
| 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. |
| ChangeDatabase(String) |
Ändert die aktuelle Datenbank für eine geöffnete SqlConnectionDatenbank. |
| 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 im Verbindungszeichenfolge angegebenen Benutzer 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. |
| CreateCommand() |
Erstellt und gibt ein SqlCommand Objekt zurück, das der SqlConnection. |
| EnlistDistributedTransaction(ITransaction) |
Enlists in der angegebenen Transaktion als verteilte Transaktion. |
| EnlistTransaction(Transaction) |
Enlists in der angegebenen Transaktion als verteilte Transaktion. |
| GetSchema() |
Gibt Schemainformationen für die Datenquelle dieses Werts SqlConnectionzurück. Weitere Informationen zum Schema finden Sie unter SQL Server Schemasammlungen. |
| GetSchema(String, String[]) |
Gibt Schemainformationen für die Datenquelle zurück SqlConnection , die die angegebene Zeichenfolge für den Schemanamen und das angegebene Zeichenfolgenarray für die Einschränkungswerte verwendet. |
| GetSchema(String) |
Gibt Schemainformationen für die Datenquelle zurück SqlConnection , die die angegebene Zeichenfolge für den Schemanamen verwendet. |
| Open() |
Öffnet eine Datenbankverbindung mit den eigenschafteneinstellungen, die durch die ConnectionString. |
| Open(SqlConnectionOverrides) |
Öffnet eine Datenbankverbindung mit den eigenschafteneinstellungen, die durch die ConnectionString. |
| OpenAsync(CancellationToken) |
Eine asynchrone Version von Open(), die eine Datenbankverbindung mit den eigenschafteneinstellungen öffnet, die durch die ConnectionString. 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. |
| OpenAsync(SqlConnectionOverrides, CancellationToken) |
Eine asynchrone Version von Open(), die eine Datenbankverbindung mit den eigenschafteneinstellungen öffnet, die durch die ConnectionString. 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. Diese Funktion sollte nur einmal in einer App aufgerufen werden. Dadurch wird das Kopieren des Wörterbuchs flach ausgeführt, sodass die App die Liste der benutzerdefinierten Anbieter nicht mehr ändern kann, nachdem sie festgelegt wurde. Die integrierten Anbieter von Speicher für Spaltenhauptschlüssel, die für Windows-Zertifikatspeicher, CNG Store und CSP verfügbar sind, sind bereits vorab registriert. |
| RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) |
Registriert die Anbieter des Verschlüsselungsschlüsselspeichers für die SqlConnection Instanz. Wenn diese Funktion aufgerufen wurde, werden alle Anbieter, die mit den statischen RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) Methoden registriert sind, ignoriert. Diese Funktion kann mehrmals aufgerufen werden. Dadurch wird das Kopieren des Wörterbuchs flach ausgeführt, sodass die App die Liste der benutzerdefinierten Anbieter nicht mehr ändern kann, nachdem sie festgelegt wurde. |
| ResetStatistics() |
Wenn das Sammeln von Statistiken aktiviert ist, werden alle Werte auf Null zurückgesetzt. |
| RetrieveInternalInfo() |
Gibt eine Name-Wert-Paarauflistung interner Eigenschaften zum Zeitpunkt des Aufrufs der Methode zurück. |
| RetrieveStatistics() |
Gibt eine Name value pair collection of statistics at the point in time the method is called. |
Ereignisse
| Name | Beschreibung |
|---|---|
| InfoMessage |
Tritt auf, wenn SQL Server eine Warnung oder Informationsmeldung zurückgibt. |
Explizite Schnittstellenimplementierungen
| Name | Beschreibung |
|---|---|
| ICloneable.Clone() |
Erstellt ein neues Objekt, das eine Kopie der aktuellen Instanz ist. |