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 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
-
SqlConnection
- Implementiert
Beispiele
Im folgenden Beispiel werden eine SqlCommand und eine SqlConnectionerstellt. Wird SqlConnection geöffnet und als für Connection festgelegt SqlCommand. Im Beispiel wird dann aufgerufen ExecuteNonQuery. Um dies zu erreichen, wird ein ExecuteNonQuery Verbindungszeichenfolge und eine Abfragezeichenfolge übergeben, bei der es sich um eine Insert-Anweisung von Transact-SQL handelt. Die Verbindung wird automatisch geschlossen, wenn der Code den using-Block beendet.
using System;
using System.Data;
using Microsoft.Data.SqlClient;
namespace SqlCommandCS
{
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/Server-Datenbanksystem entspricht dies einer Netzwerkverbindung mit dem Server. SqlConnectionwird 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 Produkte von Drittanbietern SQL Server und andere von OLE DB unterstützte Datenquellen.
Wenn Sie eine instance von SqlConnectionerstellen, werden alle Eigenschaften auf ihre Anfangswerte festgelegt. Eine Liste dieser Werte finden Sie im SqlConnection Konstruktor.
Unter finden Sie ConnectionString eine Liste der Schlüsselwörter in einem Verbindungszeichenfolge.
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 Dispose
aufrufenClose
. Close
und Dispose
sind funktional gleichwertig. Wenn der Wert Pooling
für verbindungspooling auf true
oder yes
festgelegt ist, wird die zugrunde liegende Verbindung an den Verbindungspool zurückgegeben. Wenn dagegen auf false
oder no
festgelegt 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 innerhalb eines using
Blocks, 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 Hochleistungsanwendungen 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 von SqlException der Methode generiert wird, die einen 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 .SqlConnection Die Benutzer können die Verbindung aber erneut öffnen und fortfahren.
Eine Anwendung, die eine instance 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 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 die 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 SQL Server Engine-Fehlern und Fehlermeldungen finden Sie unter Ereignisse und Fehler der Datenbank-Engine.
Achtung
Sie können TCP anstelle von freigegebenem Arbeitsspeicher erzwingen. Dazu können Sie tcp: dem Servernamen im Verbindungszeichenfolge vorangestellt oder 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 |
Eigenschaften
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 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. |
CommandTimeout |
Ruft die Standardwartezeit (in Sekunden) ab, bevor der Versuch, einen Befehl auszuführen, beendet und ein Fehler generiert wird. Der Standardwert ist 30 Sekunden. |
ConnectionString |
Ruft die Zeichenfolge ab, mit der eine SQL Server-Datenbank geöffnet wird, oder legt diese fest. |
ConnectionTimeout |
Ruft die Zeit ab, die beim Verbindungsaufbau gewartet werden soll, bis der Versuch beendet und ein Fehler generiert wird. |
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. |
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. |
RetryLogicProvider |
Ruft einen Wert ab, der das SqlRetryLogicBaseProvider-Objekt zu diesem Befehl angibt, oder legt diesen Wert fest. |
ServerProcessId |
Ruft die Serverprozess-ID (SPID) der aktiven Verbindung ab. |
ServerVersion |
Ruft eine Zeichenfolge mit der Version der SQL Server-Instanz ab, mit der der Client verbunden ist. |
State |
Gibt den Zustand von SqlConnection während des letzten Netzwerkvorgangs an, der für die Verbindung ausgeführt wurde. |
StatisticsEnabled |
Wenn |
WorkstationId |
Ruft eine Zeichenfolge ab, die den Datenbankclient bezeichnet. |
Methoden
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. |
ChangeDatabase(String) |
Ändert die aktuelle Datenbank für eine offene SqlConnection. |
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. |
CreateCommand() |
Erstellt ein SqlCommand-Objekt, das der SqlConnection zugeordnet ist, und gibt es zurück. |
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. |
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. |
Open() |
Öffnet eine Datenbankverbindung mit den von der ConnectionString angegebenen Eigenschafteneinstellungen. |
Open(SqlConnectionOverrides) |
Öffnet eine Datenbankverbindung mit den von der ConnectionString angegebenen Eigenschafteneinstellungen. |
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. Diese Funktion sollte in einer App nur einmal aufgerufen werden. Dadurch wird das Wörterbuch flach kopiert, sodass die App die benutzerdefinierte Anbieterliste nach dem Festlegen nicht mehr ändern kann. 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 im SqlConnection instance. Wenn diese Funktion aufgerufen wurde, werden alle Anbieter ignoriert, die mit den statischen RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) Methoden registriert wurden. Diese Funktion kann mehrmals aufgerufen werden. Dadurch wird das Wörterbuch flach kopiert, sodass die App die benutzerdefinierte Anbieterliste nach dem Festlegen nicht mehr ändern kann. |
ResetStatistics() |
Wenn die Statistikdatenerhebung aktiviert wird, werden alle Werte auf 0 (null) zurückgesetzt. |
RetrieveInternalInfo() |
Gibt eine Namenswertpaarauflistung mit internen Eigenschaften zum Zeitpunkt des Aufrufs der Methode zurück. |
RetrieveStatistics() |
Gibt eine Auflistung von Name-Wert-Paaren statistischer Daten zum Zeitpunkt des Methodenaufrufs zurück. |
Ereignisse
InfoMessage |
Tritt ein, wenn SQL Server eine Warn- oder Informationsmeldung zurückgibt. |
Explizite Schnittstellenimplementierungen
ICloneable.Clone() |
Erstellt ein neues Objekt, das eine Kopie der aktuellen Instanz darstellt. |