SqlConnection Klasse

Definition

Namespace:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Paket:

Microsoft.Data.SqlClient v5.2.0

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

DbConnection

SqlConnection

Implementiert

ICloneable

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 DisposeaufrufenClose. Close und Dispose sind funktional gleichwertig. Wenn der Wert Pooling für verbindungspooling auf true oder yesfestgelegt ist, wird die zugrunde liegende Verbindung an den Verbindungspool zurückgegeben. Wenn dagegen 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 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 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.
AccessTokenCallback	Ruft den Zugriffstokenrückruf für die Verbindung ab oder legt ihn fest.
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 true, wird für die aktuelle Verbindung die Statistikdatenerhebung aktiviert.
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.
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.