SqlConnection Classe

Définition

Espace de noms:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Paquet:

Microsoft.Data.SqlClient v5.2.0

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

DbConnection

SqlConnection

Implémente

ICloneable

Exemples

L’exemple suivant crée un SqlCommand et un SqlConnection. est SqlConnection ouvert et défini comme pour Connection le SqlCommand. L’exemple appelle ExecuteNonQueryensuite . Pour ce faire, le ExecuteNonQuery est passé une chaîne de connexion 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.

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();
            }
        }
    }
}

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. SqlConnectionest 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 la liste des mots clés d’un 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 du 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 automatiquement ce fournisseur, même si vous pouvez 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 normalement 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 SQL Server erreurs et les messages d’erreur du moteur, 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. Vous pouvez le faire en préfixant tcp : sur le nom du serveur dans le 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.
AccessTokenCallback	Obtient ou définit le rappel du jeton d’accès pour la connexion.
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.
CommandTimeout	Obtient le temps d’attente par défaut (en secondes) avant de mettre fin à la tentative d’exécution d’une commande et de générer une erreur. La valeur par défaut est 30 secondes.
ConnectionString	Obtient ou définit la chaîne utilisée pour ouvrir une base de données SQL Server.
ConnectionTimeout	Obtient la durée d'attente préalable à l'établissement d'une connexion avant que la tentative ne soit abandonnée et qu'une erreur ne soit générée.
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.
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.
RetryLogicProvider	Obtient ou définit une valeur qui spécifie l’objet SqlRetryLogicBaseProvider lié à cette commande.
ServerProcessId	Obtient l’ID de processus serveur (SPID) de la connexion active.
ServerVersion	Obtient une chaîne comportant la version de l’instance de SQL Server à laquelle le client est connecté.
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

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é.
ChangeDatabase(String)	Modifie la base de données actuelle d'une connexion SqlConnection établie.
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.
CreateCommand()	Crée et retourne un objet SqlCommand associé à SqlConnection.
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.
Open()	Ouvre une connexion de base de données avec les paramètres de propriété spécifiés par le ConnectionString.
Open(SqlConnectionOverrides)	Ouvre une connexion de base de données avec les paramètres de propriété spécifiés par le ConnectionString.
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. Cette fonction ne doit être appelée qu’une seule fois dans une application. Cela effectue une copie superficielle du dictionnaire afin que l’application ne puisse pas modifier la liste des fournisseurs personnalisés une fois qu’elle a été définie. Les fournisseurs de magasins de clés principales de colonne intégrés qui sont disponibles pour le magasin de certificats Windows, le magasin CNG et CSP sont préinscrits.
RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Inscrit les fournisseurs de magasin de clés de chiffrement sur le SqlConnection instance. Si cette fonction a été appelée, tous les fournisseurs inscrits à l’aide des méthodes statiques RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) seront ignorés. Cette fonction peut être appelée plusieurs fois. Cela effectue une copie superficielle du dictionnaire afin que l’application ne puisse pas modifier la liste des fournisseurs personnalisés une fois qu’elle a été définie.
ResetStatistics()	Si le recueil de statistiques est activé, toutes les valeurs sont rétablies à zéro.
RetrieveInternalInfo()	Retourne une collection de paires de valeurs de nom de propriétés internes au moment où la méthode est appelée.
RetrieveStatistics()	Retourne une collection de statistiques de paires nom/valeur au moment où la méthode est appelée.

Événements

InfoMessage

Se produit quand SQL Server retourne un message d’avertissement ou d’information.

Implémentations d’interfaces explicites

ICloneable.Clone()

Crée un objet qui est une copie de l'instance actuelle.