SqlConnection Classe

Définition

Espace de noms:

System.Data.SqlClient

Assembly:

System.Data.dll

Représente une connexion à une base de données SQL Server. Cette classe ne peut pas être héritée.

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

Héritage

Object

MarshalByRefObject

Component

DbConnection

SqlConnection

Implémente

ICloneable

Exemples

L’exemple suivant crée un SqlCommand et un SqlConnection. est SqlConnection ouvert et défini comme Connection pour le SqlCommand. L’exemple appelle ExecuteNonQueryensuite . Pour ce faire, le ExecuteNonQuery est transmis à une chaîne SqlConnection et une chaîne de requête qui est une instruction Transact-SQL INSERT. La connexion est fermée automatiquement lorsque le code quitte le bloc using.

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

Remarques

Un SqlConnection objet représente une session unique à une source de données SQL Server. Avec un système de base de données client/serveur, cela équivaut à une connexion réseau au serveur. SqlConnection est utilisé avec SqlDataAdapter et SqlCommand pour augmenter les performances lors de la connexion à une base de données Microsoft SQL Server. Pour tous les produits SQL Server tiers et autres sources de données prises en charge par OLE DB, utilisez OleDbConnection.

Lorsque vous créez une instance de SqlConnection, toutes les propriétés sont définies sur leurs valeurs initiales. Pour obtenir la liste de ces valeurs, consultez le SqlConnection constructeur.

Consultez ConnectionString pour obtenir la liste des mots clés dans une chaîne de connexion.

Si le SqlConnection sort de l’étendue, il ne sera pas fermé. Par conséquent, vous devez fermer explicitement la connexion en appelant Close ou Dispose. Close et Dispose sont fonctionnellement équivalents. Si la valeur Pooling de regroupement de connexions est définie sur true ou yes, la connexion sous-jacente est retournée au pool de connexions. En revanche, si Pooling est défini sur false ou no, la connexion sous-jacente au serveur est en fait fermée.

Notes

Les événements de connexion et de déconnexion ne seront pas déclenchés sur le serveur si une connexion est récupérée depuis le pool de connexions ou qu’elle est retournée au pool, car elle n’est pas réellement fermée lorsqu’elle est retournée au pool. Pour plus d’informations, consultez Regroupement de connexions SQL Server (ADO.NET).

Pour vous assurer que les connexions sont toujours fermées, ouvrez la connexion à l’intérieur d’un using bloc, comme indiqué dans le fragment de code suivant. Cela garantit que la connexion est automatiquement fermée lorsque le code quitte le bloc.

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

Notes

Pour déployer des applications hautes performances, vous devez utiliser le regroupement de connexions. Lorsque vous utilisez le fournisseur de données .NET Framework pour SQL Server, vous n’avez pas besoin d’activer le regroupement de connexions, car le fournisseur gère cela automatiquement, bien que vous puissiez modifier certains paramètres. Pour plus d’informations, consultez Regroupement de connexions SQL Server (ADO.NET).

Si un SqlException est généré par la méthode exécutant un SqlCommand, le SqlConnection reste ouvert lorsque le niveau de gravité est inférieur ou égal à 19. Lorsque le niveau de gravité est supérieur ou égal à 20, le serveur ferme généralement le SqlConnection. L'utilisateur peut toutefois rouvrir la connexion et continuer.

Une application qui crée une instance de l’objet SqlConnection peut exiger que tous les appelants directs et indirects disposent d’autorisations suffisantes sur le code en définissant des exigences de sécurité déclaratives ou impératives. SqlConnection effectue des demandes de sécurité à l’aide de l’objet SqlClientPermission . Les utilisateurs peuvent vérifier que leur code dispose d’autorisations suffisantes à l’aide de l’objet SqlClientPermissionAttribute . Les utilisateurs et les administrateurs peuvent également utiliser le Caspol.exe (Code Access Security Policy Tool) pour modifier la stratégie de sécurité au niveau de l’ordinateur, de l’utilisateur et de l’entreprise. Pour plus d’informations, consultez Sécurité dans .NET. Pour obtenir un exemple montrant comment utiliser les demandes de sécurité, consultez Sécurité d’accès du code et ADO.NET.

Pour plus d’informations sur la gestion des messages d’avertissement et d’information provenant du serveur, consultez Événements de connexion. Pour plus d’informations sur les erreurs et les messages d’erreur du moteur SQL Server, consultez Événements et erreurs du moteur de base de données.

Attention

Vous pouvez forcer TCP au lieu de la mémoire partagée. Pour ce faire, vous pouvez préfixer tcp : sur le nom du serveur dans la chaîne de connexion ou vous pouvez utiliser localhost.

Constructeurs

SqlConnection()	Initialise une nouvelle instance de la classe SqlConnection.
SqlConnection(String)	Initialise une nouvelle instance de la classe SqlConnection pendant la réception d’une chaîne contenant une chaîne de connexion.
SqlConnection(String, SqlCredential)	Initialise une nouvelle instance de la classe SqlConnection en fonction d’une chaîne de connexion, qui n’utilise pas Integrated Security = true et un objet SqlCredential qui contient l’ID d’utilisateur et le mot de passe.

Propriétés

AccessToken	Obtient ou définit le jeton d’accès pour la connexion.
CanCreateBatch	Obtient une valeur qui indique si cette instance DbConnection prend en charge la classe DbBatch. (Hérité de DbConnection)
CanRaiseEvents	Obtient une valeur qui indique si le composant peut déclencher un événement. (Hérité de Component)
ClientConnectionId	ID de connexion de la tentative de connexion la plus récente, que la tentative ait réussi ou échoué.
ColumnEncryptionKeyCacheTtl	Obtient ou définit la durée de vie des entrées de la clé de chiffrement de colonne du cache de clé de chiffrement de colonne pour la fonctionnalité Always Encrypted. La valeur par défaut est 2 heures. 0 signifie aucune mise en cache.
ColumnEncryptionQueryMetadataCacheEnabled	Récupère ou définit une valeur qui indique si la mise en cache des métadonnées de requête est activée (true) ou non (false) pour les requêtes paramétrables qui s’exécutent sur des bases de données Always Encrypted. La valeur par défaut est true.
ColumnEncryptionTrustedMasterKeyPaths	Vous permet de définir une liste de chemins d’accès de clés approuvés pour un serveur de bases de données. Si le pilote reçoit un chemin de clé qui ne figure pas dans la liste pendant le traitement d’une requête d’application, celle-ci échouera. Cette propriété fournit une protection supplémentaire contre les attaques de sécurité durant lesquelles un ordinateur SQL Server compromis fournit des chemins d’accès de clés factices, qui peuvent entraîner une fuite des informations d’identification du magasin de clés.
ConnectionString	Obtient ou définit la chaîne utilisée pour ouvrir une base de données SQL Server.
ConnectionTimeout	Obtient le délai d’attente (en secondes) lors de la tentative d’établissement d’une connexion avant de mettre fin à la tentative et de générer une erreur.
Container	Obtient le IContainer qui contient la Component. (Hérité de Component)
Credential	Obtient ou définit l’objet SqlCredential pour cette connexion.
Database	Obtient le nom de la base de données active ou de la base de données à utiliser une fois la connexion ouverte.
DataSource	Obtient le nom de l’instance de SQL Server à laquelle se connecter.
DbProviderFactory	Obtient le DbProviderFactory pour ce DbConnection. (Hérité de DbConnection)
DesignMode	Obtient une valeur qui indique si Component est actuellement en mode design. (Hérité de Component)
Events	Obtient la liste des gestionnaires d'événements attachés à ce Component. (Hérité de Component)
FireInfoMessageEventOnUserErrors	Obtient ou définit la propriété FireInfoMessageEventOnUserErrors.
PacketSize	Obtient la taille (en octets) des paquets réseau permettant de communiquer avec une instance de SQL Server.
ServerVersion	Obtient une chaîne comportant la version de l’instance de SQL Server à laquelle le client est connecté.
Site	Obtient ou définit le ISite de Component. (Hérité de Component)
State	Indique l’état de SqlConnection pendant la dernière opération réseau exécutée sur la connexion.
StatisticsEnabled	Quand la valeur est true, active la collecte de statistiques pour la connexion actuelle.
WorkstationId	Obtient une chaîne qui identifie le client de la base de données.

Méthodes

BeginDbTransaction(IsolationLevel)	En cas de substitution dans une classe dérivée, démarre une transaction de base de données. (Hérité de DbConnection)
BeginDbTransactionAsync(IsolationLevel, CancellationToken)	Démarre de manière asynchrone une transaction de base de données. (Hérité de DbConnection)
BeginTransaction()	Commence une transaction de base de données.
BeginTransaction(IsolationLevel)	Commence une transaction de base de données avec le niveau d’isolement spécifié.
BeginTransaction(IsolationLevel, String)	Commence une transaction de base de données avec le niveau d'isolement et le nom de transaction spécifiés.
BeginTransaction(String)	Commence une transaction de base de données avec le nom de transaction spécifié.
BeginTransactionAsync(CancellationToken)	Commence de manière asynchrone une transaction de base de données. (Hérité de DbConnection)
BeginTransactionAsync(IsolationLevel, CancellationToken)	Commence de manière asynchrone une transaction de base de données. (Hérité de DbConnection)
ChangeDatabase(String)	Modifie la base de données actuelle d'une connexion SqlConnection établie.
ChangeDatabaseAsync(String, CancellationToken)	Change de manière asynchrone la base de données actuelle pour une connexion ouverte. (Hérité de DbConnection)
ChangePassword(String, SqlCredential, SecureString)	Change le mot de passe SQL Server pour l’utilisateur indiqué dans l’objet SqlCredential.
ChangePassword(String, String)	Remplace le mot de passe SQL Server de l’utilisateur indiqué dans la chaîne de connexion par le nouveau mot de passe fourni.
ClearAllPools()	Vide le pool de connexions.
ClearPool(SqlConnection)	Vide le pool de connexions associé à la connexion spécifiée.
Close()	Ferme la connexion à la base de données. C'est la méthode recommandée de fermeture d'une connexion ouverte.
CloseAsync()	Ferme de manière asynchrone la connexion à la base de données. (Hérité de DbConnection)
CreateBatch()	Retourne une nouvelle instance de la classe du fournisseur qui implémente la classe DbBatch. (Hérité de DbConnection)
CreateCommand()	Crée et retourne un objet SqlCommand associé à SqlConnection.
CreateDbBatch()	En cas de substitution dans une classe dérivée, retourne une nouvelle instance de la classe du fournisseur qui implémente la DbBatch classe . (Hérité de DbConnection)
CreateDbCommand()	En cas de substitution dans une classe dérivée, crée et retourne un objet DbCommand associé à la connexion active. (Hérité de DbConnection)
CreateObjRef(Type)	Crée un objet contenant toutes les informations appropriées requises pour générer un proxy permettant de communiquer avec un objet distant. (Hérité de MarshalByRefObject)
Dispose()	Exécute les tâches définies par l'application associées à la libération ou à la redéfinition des ressources non managées. (Hérité de DbConnection)
Dispose(Boolean)	Libère les ressources non managées utilisées par DbConnection et libère éventuellement les ressources managées. (Hérité de DbConnection)
DisposeAsync()	Supprime de manière asynchrone l’objet de connexion. (Hérité de DbConnection)
EnlistDistributedTransaction(ITransaction)	S’inscrit dans la transaction spécifiée en tant que transaction distribuée.
EnlistTransaction(Transaction)	S’inscrit dans la transaction spécifiée en tant que transaction distribuée.
Equals(Object)	Détermine si l'objet spécifié est égal à l'objet actuel. (Hérité de Object)
GetHashCode()	Fait office de fonction de hachage par défaut. (Hérité de Object)
GetLifetimeService()	Récupère l'objet de service de durée de vie en cours qui contrôle la stratégie de durée de vie de cette instance. (Hérité de MarshalByRefObject)
GetSchema()	Retourne les informations de schéma pour la source de données de ce SqlConnection. Pour plus d’informations sur le schéma, consultez Collections de schémas SQL Server.
GetSchema(String)	Retourne des informations de schéma pour la source de données de ce SqlConnection à l’aide de la chaîne spécifiée pour le nom de schéma.
GetSchema(String, String[])	Retourne les informations de schéma pour la source de données de ce SqlConnection à l’aide de la chaîne spécifiée pour le nom de schéma et du tableau de chaînes spécifié pour les valeurs de restriction.
GetSchemaAsync(CancellationToken)	Il s'agit d’une version asynchrone de GetSchema(). Les fournisseurs doivent effectuer le remplacement avec une implémentation appropriée. Le cancellationToken peut éventuellement être respecté. L'implémentation par défaut appelle l'appel de méthode GetSchema() synchrone et retourne une tâche terminée. L'implémentation par défaut retourne une tâche annulée si un cancellationToken déjà annulé est passé. Les exceptions levées par GetSchema() sont communiquées via la propriété d'exception de tâche retournée. (Hérité de DbConnection)
GetSchemaAsync(String, CancellationToken)	Il s'agit de la version asynchrone de GetSchema(String). Les fournisseurs doivent effectuer le remplacement avec une implémentation appropriée. Le cancellationToken peut éventuellement être respecté. L'implémentation par défaut appelle l'appel de méthode GetSchema(String) synchrone et retourne une tâche terminée. L'implémentation par défaut retourne une tâche annulée si un cancellationToken déjà annulé est passé. Les exceptions levées par GetSchema(String) sont communiquées via la propriété d'exception de tâche retournée. (Hérité de DbConnection)
GetSchemaAsync(String, String[], CancellationToken)	Il s'agit de la version asynchrone de GetSchema(String, String[]). Les fournisseurs doivent effectuer le remplacement avec une implémentation appropriée. Le cancellationToken peut éventuellement être respecté. L'implémentation par défaut appelle l'appel de méthode GetSchema(String, String[]) synchrone et retourne une tâche terminée. L'implémentation par défaut retourne une tâche annulée si un cancellationToken déjà annulé est passé. Les exceptions levées par GetSchema(String, String[]) sont communiquées via la propriété d'exception de tâche retournée. (Hérité de DbConnection)
GetService(Type)	Retourne un objet qui représente un service fourni par Component ou par son Container. (Hérité de Component)
GetType()	Obtient le Type de l'instance actuelle. (Hérité de Object)
InitializeLifetimeService()	Obtient un objet de service de durée de vie pour contrôler la stratégie de durée de vie de cette instance. (Hérité de MarshalByRefObject)
MemberwiseClone()	Crée une copie superficielle du Object actuel. (Hérité de Object)
MemberwiseClone(Boolean)	Crée une copie superficielle de l'objet MarshalByRefObject actuel. (Hérité de MarshalByRefObject)
OnStateChange(StateChangeEventArgs)	Déclenche l’événement StateChange. (Hérité de DbConnection)
Open()	Ouvre une connexion de base de données avec les paramètres de propriété spécifiés par le ConnectionString.
OpenAsync()	Version asynchrone de Open(), qui ouvre une connexion de base de données avec les paramètres spécifiés par ConnectionString. Cette méthode appelle la méthode virtuelle OpenAsync(CancellationToken) avec CancellationToken.None. (Hérité de DbConnection)
OpenAsync(CancellationToken)	Version asynchrone de Open(), qui ouvre une connexion de base de données avec les paramètres de propriété spécifiés par ConnectionString. Le jeton d'annulation peut être utilisé pour demander l'abandon de l'opération avant que le délai d'attente de connexion s'écoule. Les exceptions seront propagées via la tâche retournée. Si le délai d'attente de connexion s'écoule sans connexion réussie, la tâche retournée est marquée comme défaillante avec une exception. L'implémentation retourne une tâche sans bloquer le thread appelant pour les connexions regroupées et non regroupées.
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Inscrit les fournisseurs de magasin de clés de chiffrement de colonne.
ResetStatistics()	Si le recueil de statistiques est activé, toutes les valeurs sont rétablies à zéro.
RetrieveStatistics()	Retourne une collection de statistiques de paires nom/valeur au moment où la méthode est appelée.
ToString()	Retourne un String contenant le nom du Component, s’il en existe un. Cette méthode ne doit pas être remplacée. (Hérité de Component)

Événements

Disposed	Se produit lorsque le composant est supprimé par un appel à la méthode Dispose(). (Hérité de Component)
InfoMessage	Se produit quand SQL Server retourne un message d’avertissement ou d’information.
StateChange	Se produit quand l’état de la connexion change. (Hérité de DbConnection)

Implémentations d’interfaces explicites

ICloneable.Clone()	Crée un objet qui est une copie de l'instance actuelle.
IDbConnection.BeginTransaction()	Commence une transaction de base de données. (Hérité de DbConnection)
IDbConnection.BeginTransaction(IsolationLevel)	Commence une transaction de base de données avec le niveau d’isolement spécifié. (Hérité de DbConnection)
IDbConnection.CreateCommand()	Crée et retourne un objet DbCommand associé à la connexion actuelle. (Hérité de DbConnection)

Voir aussi

• Connexion à une source de données dans ADO.NET
• SQL Server et ADO.NET
• Vue d'ensemble d’ADO.NET