SqlConnection Klasse

Definition

Stellt eine Verbindung zu einer SQL Server-Datenbank dar.Represents a connection to a SQL Server database. Diese Klasse kann nicht vererbt werden.This class cannot be inherited.

public ref class SqlConnection sealed : System::Data::Common::DbConnection, ICloneable, IDisposable
public sealed class SqlConnection : System.Data.Common.DbConnection, ICloneable, IDisposable
type SqlConnection = class
    inherit DbConnection
    interface IDbConnection
    interface ICloneable
    interface IDisposable
Public NotInheritable Class SqlConnection
Inherits DbConnection
Implements ICloneable, IDisposable
Vererbung
Implementiert

Beispiele

Im folgenden Beispiel werden eine-SqlCommand und eine-SqlConnectionerstellt.The following example creates a SqlCommand and a SqlConnection. Der SqlConnection wird geöffnet und als Connection für die SqlCommandfestgelegt.The SqlConnection is opened and set as the Connection for the SqlCommand. Im Beispiel wird dann ExecuteNonQueryaufgerufen.The example then calls ExecuteNonQuery. Zu diesem Zweck wird dem ExecuteNonQuery eine Verbindungs Zeichenfolge und eine Abfrage Zeichenfolge, die eine Transact-SQLTransact-SQL INSERT-Anweisung ist, übermittelt.To accomplish this, the ExecuteNonQuery is passed a connection string and a query string that is a Transact-SQLTransact-SQL INSERT statement. Die Verbindung wird automatisch geschlossen, wenn der Code den Using-Block verlässt.The connection is closed automatically when the code exits the using block.

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.A SqlConnection object represents a unique session to a SQL Server data source. Bei einem Client/Server-Datenbanksystem entspricht dies einer Netzwerkverbindung mit dem Server.With a client/server database system, it is equivalent to a network connection to the server. SqlConnection wird in Verbindung mit SqlDataAdapter und SqlCommand verwendet, um die Leistung beim Herstellen einer Verbindung mit einer Microsoft SQL Server Datenbank zu steigern.SqlConnection is used together with SqlDataAdapter and SqlCommand to increase performance when connecting to a Microsoft SQL Server database. Verwenden Sie für alle SQL Server Produkte von Drittanbietern und andere OLE DB unterstützte Datenquellen OleDbConnection.For all third-party SQL Server products and other OLE DB-supported data sources, use OleDbConnection.

Wenn Sie eine Instanz von SqlConnectionerstellen, werden alle Eigenschaften auf die Anfangswerte festgelegt.When you create an instance of SqlConnection, all properties are set to their initial values. Eine Liste dieser Werte finden Sie im SqlConnection-Konstruktor.For a list of these values, see the SqlConnection constructor.

Eine Liste der Schlüsselwörter in einer Verbindungs Zeichenfolge finden Sie unter ConnectionString.See ConnectionString for a list of the keywords in a connection string.

Wenn das SqlConnection den Gültigkeitsbereich verlässt, wird es nicht geschlossen.If the SqlConnection goes out of scope, it won't be closed. Daher müssen Sie die Verbindung explizit schließen, indem Sie Close oder Disposeaufrufen.Therefore, you must explicitly close the connection by calling Close or Dispose. Close und Dispose sind funktional äquivalent.Close and Dispose are functionally equivalent. Wenn der Wert für das Verbindungspooling Pooling auf true oder yesfestgelegt ist, wird die zugrunde liegende Verbindung an den Verbindungspool zurückgegeben.If the connection pooling value Pooling is set to true or yes, the underlying connection is returned back to the connection pool. Wenn Pooling dagegen auf false oder nofestgelegt ist, wird die zugrunde liegende Verbindung mit dem Server tatsächlich geschlossen.On the other hand, if Pooling is set to false or no, the underlying connection to the server is actually closed.

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.Login and logout events will not be raised on the server when a connection is fetched from or returned to the connection pool, because the connection is not actually closed when it is returned to the connection pool. Weitere Informationen finden Sie unter SQL Server-Verbindungspooling (ADO.NET).For more information, see SQL Server Connection Pooling (ADO.NET).

Um sicherzustellen, dass Verbindungen immer geschlossen werden, öffnen Sie die Verbindung in einem using Block, wie im folgenden Code Fragment dargestellt.To ensure that connections are always closed, open the connection inside of a using block, as shown in the following code fragment. Dadurch wird sichergestellt, dass die Verbindung automatisch geschlossen wird, wenn der Code den Block verlässt.Doing so ensures that the connection is automatically closed when the code exits the block.

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

Zum Bereitstellen von Hochleistungsanwendungen müssen Sie das Verbindungspooling verwenden.To deploy high-performance applications, you must use connection pooling. Wenn Sie die .NET Framework Datenanbieter für SQL Server verwenden, müssen Sie das Verbindungspooling nicht aktivieren, da der Anbieter dies automatisch verwaltet, auch wenn Sie einige Einstellungen ändern können.When you use the .NET Framework Data Provider for SQL Server, you do not have to enable connection pooling because the provider manages this automatically, although you can modify some settings. Weitere Informationen finden Sie unter SQL Server-Verbindungspooling (ADO.NET).For more information, see SQL Server Connection Pooling (ADO.NET).

Wenn ein SqlException von der Methode generiert wird, die eine SqlCommandausführt, bleibt der SqlConnection geöffnet, wenn der Schweregrad 19 oder kleiner ist.If a SqlException is generated by the method executing a SqlCommand, the SqlConnection remains open when the severity level is 19 or less. Wenn der Schweregrad 20 oder größer ist, schließt der Server normalerweise den SqlConnection.When the severity level is 20 or greater, the server ordinarily closes the SqlConnection. Die Benutzer können die Verbindung aber erneut öffnen und fortfahren.However, the user can reopen the connection and continue.

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.An application that creates an instance of the SqlConnection object can require all direct and indirect callers to have sufficient permission to the code by setting declarative or imperative security demands. SqlConnection nimmt Sicherheitsanforderungen mithilfe des SqlClientPermission Objekts an.SqlConnection makes security demands using the SqlClientPermission object. Benutzer können überprüfen, ob Ihr Code über ausreichende Berechtigungen verfügt, indem Sie das SqlClientPermissionAttribute-Objekt verwenden.Users can verify that their code has sufficient permissions by using the SqlClientPermissionAttribute object. Benutzer und Administratoren können auch das Caspol. exe (Code Access Security Policy-Tool) verwenden, um die Sicherheitsrichtlinien auf Computer-, Benutzer-und Unternehmensebene zu ändern.Users and administrators can also use the Caspol.exe (Code Access Security Policy Tool) to modify security policy at the machine, user, and enterprise levels. Weitere Informationen finden Sie unter Sicherheit in .NET.For more information, see Security in .NET. Ein Beispiel für die Verwendung von Sicherheitsanforderungen finden Sie unter Code Zugriffssicherheit und ADO.net.For an example demonstrating how to use security demands, see Code Access Security and ADO.NET.

Weitere Informationen zur Behandlung von Warn-und Informationsmeldungen vom Server finden Sie unter Verbindungs Ereignisse.For more information about handling warning and informational messages from the server, see Connection Events. Weitere Informationen zu SQL Server Engine-Fehlern und-Fehlermeldungen finden Sie unter Datenbank-Engine Ereignisse und Fehler.For more information about SQL Server engine errors and error messages, see Database Engine Events and Errors.

Achtung

Sie können TCP anstelle von Shared Memory erzwingen.You can force TCP instead of shared memory. Dies erreichen Sie, indem Sie TCP: dem Servernamen in der Verbindungs Zeichenfolge voranstellen, oder Sie können localhost verwenden.You can do that by prefixing tcp: to the server name in the connection string or you can use localhost.

Konstruktoren

SqlConnection()

Initialisiert eine neue Instanz der SqlConnection-Klasse.Initializes a new instance of the SqlConnection class.

SqlConnection(String)

Initialisiert eine neue Instanz der SqlConnection-Klasse, sofern eine Zeichenfolge mit der Verbindungszeichenfolge angegeben wird.Initializes a new instance of the SqlConnection class when given a string that contains the connection string.

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.Initializes a new instance of the SqlConnection class given a connection string, that does not use Integrated Security = true and a SqlCredential object that contains the user ID and password.

Eigenschaften

AccessToken

Ruft das Zugriffstoken für die Verbindung ab oder legt es fest.Gets or sets the access token for the connection.

CanRaiseEvents

Ruft einen Wert ab, der angibt, ob die Komponente ein Ereignis auslösen kann.Gets a value indicating whether the component can raise an event.

(Geerbt von Component)
ClientConnectionId

Die Verbindungs-ID der letzten Verbindungsversuchs, unabhängig davon, ob der Versuch erfolgreich war oder fehlgeschlagen ist.The connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.

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.Gets or sets the time-to-live for column encryption key entries in the column encryption key cache for the Always Encrypted feature. Der Standardwert ist 2 Stunden.The default value is 2 hours. 0 bedeutet, dass keine Zwischenspeicherung stattfindet.0 means no caching at all.

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.Gets or sets a value that indicates whether query metadata caching is enabled (true) or not (false) for parameterized queries running against Always Encrypted enabled databases. Der Standardwert ist true.The default value is true.

ColumnEncryptionTrustedMasterKeyPaths

Ermöglicht es Ihnen, eine Liste von vertrauenswürdigen Schlüsselpfaden für einen Datenbankserver festzulegen.Allows you to set a list of trusted key paths for a database server. 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.If while processing an application query the driver receives a key path that is not on the list, the query will fail. Diese Eigenschaft bietet zusätzlichen Schutz vor Sicherheitsangriffen, bei denen ein gefährdeter SQL Server falsche Schlüsselpfade bereitstellt, was zur Offenlegung von Schlüsselspeicher-Anmeldeinformationen führen kann.This property provides additional protection against security attacks that involve a compromised SQL Server providing fake key paths, which may lead to leaking key store credentials.

ConnectionString

Ruft die Zeichenfolge ab, mit der eine SQL Server-Datenbank geöffnet wird, oder legt diese fest.Gets or sets the string used to open a SQL Server database.

ConnectionTimeout

Ruft die Zeit (in Sekunden) ab, die beim Verbindungsaufbau gewartet werden soll, bis der Versuch beendet und ein Fehler generiert wird.Gets the time to wait (in seconds) while trying to establish a connection before terminating the attempt and generating an error.

Container

Ruft den IContainer ab, der die Component enthält.Gets the IContainer that contains the Component.

(Geerbt von Component)
Credential

Ruft das SqlCredential-Objekt für diese Verbindung ab, oder legt es fest.Gets or sets the SqlCredential object for this connection.

Credentials
Database

Ruft den Namen der aktuellen Datenbank oder der nach dem Öffnen einer Verbindung zu verwendenden Datenbank ab.Gets the name of the current database or the database to be used after a connection is opened.

DataSource

Ruft den Namen der SQL Server-Instanz ab, mit der eine Verbindung hergestellt werden soll.Gets the name of the instance of SQL Server to which to connect.

DesignMode

Ruft einen Wert ab, der angibt, ob sich Component gegenwärtig im Entwurfsmodus befindet.Gets a value that indicates whether the Component is currently in design mode.

(Geerbt von Component)
Events

Ruft die Liste der Ereignishandler ab, die dieser Component angefügt sind.Gets the list of event handlers that are attached to this Component.

(Geerbt von Component)
FireInfoMessageEventOnUserErrors

Ruft die FireInfoMessageEventOnUserErrors-Eigenschaft ab oder legt diese fest.Gets or sets the FireInfoMessageEventOnUserErrors property.

PacketSize

Ruft die Größe der Netzwerkpakete in Bytes ab, die zum Kommunizieren mit einer Instanz von SQL Server verwendet werden.Gets the size (in bytes) of network packets used to communicate with an instance of SQL Server.

ServerVersion

Ruft eine Zeichenfolge mit der Version der SQL Server-Instanz ab, mit der der Client verbunden ist.Gets a string that contains the version of the instance of SQL Server to which the client is connected.

Site

Ruft den ISite von Component ab oder legt ihn fest.Gets or sets the ISite of the Component.

(Geerbt von Component)
State

Gibt den Zustand von SqlConnection während des letzten Netzwerkvorgangs an, der für die Verbindung ausgeführt wurde.Indicates the state of the SqlConnection during the most recent network operation performed on the connection.

StatisticsEnabled

Wenn true, wird für die aktuelle Verbindung die Statistikdatenerhebung aktiviert.When set to true, enables statistics gathering for the current connection.

WorkstationId

Ruft eine Zeichenfolge ab, die den Datenbankclient bezeichnet.Gets a string that identifies the database client.

Methoden

BeginTransaction()

Startet eine Datenbanktransaktion.Starts a database transaction.

BeginTransaction(IsolationLevel)

Startet eine Datenbanktransaktion mit dem angegebenen Isolationsgrad.Starts a database transaction with the specified isolation level.

BeginTransaction(IsolationLevel, String)

Startet eine Datenbanktransaktion mit dem angegebenen Isolationsgrad und Transaktionsnamen.Starts a database transaction with the specified isolation level and transaction name.

BeginTransaction(String)

Startet eine Datenbanktransaktion mit dem angegebenen Transaktionsnamen.Starts a database transaction with the specified transaction name.

ChangeDatabase(String)

Ändert die aktuelle Datenbank für eine offene SqlConnection.Changes the current database for an open SqlConnection.

ChangePassword(String, SqlCredential, SecureString)

Ändert das SQL Server-Kennwort für den Benutzer, der im SqlCredential-Objekt angegeben wird.Changes the SQL Server password for the user indicated in the SqlCredential object.

ChangePassword(String, String)

Ändert das SQL Server-Kennwort für den Benutzer, der in der Verbindungszeichenfolge zum bereitgestellten neuen Kennwort angegeben ist.Changes the SQL Server password for the user indicated in the connection string to the supplied new password.

ClearAllPools()

Leert den Verbindungspool.Empties the connection pool.

ClearPool(SqlConnection)

Leert den der angegebenen Verbindung zugeordneten Verbindungspool.Empties the connection pool associated with the specified connection.

Close()

Schließt die Verbindung mit der Datenbank.Closes the connection to the database. Dies ist die bevorzugte Methode zum Schließen offener Verbindungen.This is the preferred method of closing any open connection.

CreateCommand()

Erstellt ein SqlCommand-Objekt, das der SqlConnection zugeordnet ist, und gibt es zurück.Creates and returns a SqlCommand object associated with the SqlConnection.

CreateObjRef(Type)

Erstellt ein Objekt mit allen relevanten Informationen, die zum Generieren eines Proxys für die Kommunikation mit einem Remoteobjekt erforderlich sind.Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object.

(Geerbt von MarshalByRefObject)
Dispose()

Gibt alle vom Component verwendeten Ressourcen frei.Releases all resources used by the Component.

(Geerbt von Component)
Dispose(Boolean)

Gibt die von Component verwendeten nicht verwalteten Ressourcen und optional die verwalteten Ressourcen frei.Releases the unmanaged resources used by the Component and optionally releases the managed resources.

(Geerbt von Component)
EnlistDistributedTransaction(ITransaction)

Trägt sich in der angegebenen Transaktion als verteilte Transaktion ein.Enlists in the specified transaction as a distributed transaction.

EnlistTransaction(Transaction)

Trägt sich in der angegebenen Transaktion als verteilte Transaktion ein.Enlists in the specified transaction as a distributed transaction.

Equals(Object)

Bestimmt, ob das angegebene Objekt mit dem aktuellen Objekt identisch ist.Determines whether the specified object is equal to the current object.

(Geerbt von Object)
GetHashCode()

Fungiert als Standardhashfunktion.Serves as the default hash function.

(Geerbt von Object)
GetLifetimeService()

Ruft das aktuelle Lebensdauerdienstobjekt ab, das die Lebensdauerrichtlinien für diese Instanz steuert.Retrieves the current lifetime service object that controls the lifetime policy for this instance.

(Geerbt von MarshalByRefObject)
GetSchema()

Gibt Schemainformationen für die Datenquelle dieser SqlConnection zurück.Returns schema information for the data source of this SqlConnection. Weitere Informationen zu Schemas finden Sie unter SQL Server-Schemaauflistungen.For more information about scheme, see SQL Server Schema Collections.

GetSchema(String)

Gibt Schemainformationen für die Datenquelle dieser SqlConnection mithilfe der angegebenen Zeichenfolge des Schemanamens zurück.Returns schema information for the data source of this SqlConnection using the specified string for the schema name.

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.Returns schema information for the data source of this SqlConnection using the specified string for the schema name and the specified string array for the restriction values.

GetService(Type)

Gibt ein Objekt zurück, das einen von der Component oder von deren Container bereitgestellten Dienst darstellt.Returns an object that represents a service provided by the Component or by its Container.

(Geerbt von Component)
GetType()

Ruft den Type der aktuellen Instanz ab.Gets the Type of the current instance.

(Geerbt von Object)
InitializeLifetimeService()

Ruft ein Lebensdauerdienstobjekt zur Steuerung der Lebensdauerrichtlinie für diese Instanz ab.Obtains a lifetime service object to control the lifetime policy for this instance.

(Geerbt von MarshalByRefObject)
MemberwiseClone()

Erstellt eine flache Kopie des aktuellen Object.Creates a shallow copy of the current Object.

(Geerbt von Object)
MemberwiseClone(Boolean)

Erstellt eine flache Kopie des aktuellen MarshalByRefObject-Objekts.Creates a shallow copy of the current MarshalByRefObject object.

(Geerbt von MarshalByRefObject)
Open()

Öffnet eine Datenbankverbindung mit den von der ConnectionString angegebenen Eigenschafteneinstellungen.Opens a database connection with the property settings specified by the ConnectionString.

OpenAsync(CancellationToken)

Eine asynchrone Version von Open(), die eine Datenbankverbindung mit den Eigenschaftseinstellungen öffnet, die durch ConnectionString angegeben sind.An asynchronous version of Open(), which opens a database connection with the property settings specified by the ConnectionString. Das Abbruchtoken kann verwendet werden, um anzufordern, dass der Vorgang abgebrochen wird, bevor das Timeout der Verbindung abläuft.The cancellation token can be used to request that the operation be abandoned before the connection timeout elapses. Ausnahmen werden über die zurückgegebene Aufgabe weitergegeben.Exceptions will be propagated via the returned Task. 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.If the connection timeout time elapses without successfully connecting, the returned Task will be marked as faulted with an Exception. Die Implementierung gibt eine Aufgabe zurück, ohne den aufrufenden Verbindungs-Thread zu blockieren (gilt auch für Pool-Verbindungen).The implementation returns a Task without blocking the calling thread for both pooled and non-pooled connections.

RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)

Registriert die Schlüsselspeicheranbieter für die Spaltenverschlüsselung.Registers the column encryption key store providers.

ResetStatistics()

Wenn die Statistikdatenerhebung aktiviert wird, werden alle Werte auf 0 (null) zurückgesetzt.If statistics gathering is enabled, all values are reset to zero.

RetrieveStatistics()

Gibt eine Auflistung von Name-Wert-Paaren statistischer Daten zum Zeitpunkt des Methodenaufrufs zurück.Returns a 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 Component enthält (sofern vorhanden).Returns a String containing the name of the Component, if any. Diese Methode darf nicht überschrieben werden.This method should not be overridden.

(Geerbt von Component)

Ereignisse

Disposed

Tritt ein, wenn die Komponente durch einen Aufruf der Dispose()-Methode freigegeben wird.Occurs when the component is disposed by a call to the Dispose() method.

(Geerbt von Component)
InfoMessage

Tritt ein, wenn SQL Server eine Warn- oder Informationsmeldung zurückgibt.Occurs when SQL Server returns a warning or informational message.

StateChange

Tritt auf, wenn sich der Status der Verbindung ändert.Occurs when the state of the connection changes.

Explizite Schnittstellenimplementierungen

ICloneable.Clone()

Erstellt ein neues Objekt, das eine Kopie der aktuellen Instanz darstellt.Creates a new object that is a copy of the current instance.

IDbConnection.BeginTransaction()

Beginnt eine Datenbanktransaktion.Begins a database transaction.

IDbConnection.BeginTransaction(IsolationLevel)

Beginnt eine Datenbanktransaktion mit dem angegebenen IsolationLevel-Wert.Begins a database transaction with the specified IsolationLevel value.

IDbConnection.CreateCommand()

Erstellt ein Command-Objekt, das der Verbindung zugeordnet ist, und gibt dieses zurück.Creates and returns a Command object that is associated with the connection.

Gilt für:

Siehe auch