SqlConnection Classe

Définition

Espace de noms:: Microsoft.Data.SqlClient

Assembly:: Microsoft.Data.SqlClient.dll

Paquet:: Microsoft.Data.SqlClient v1.0.19269.1

Paquet:: Microsoft.Data.SqlClient v1.1.4

Paquet:: Microsoft.Data.SqlClient v2.0.1

Paquet:: Microsoft.Data.SqlClient v2.1.4

Paquet:: Microsoft.Data.SqlClient v3.0.1

Paquet:: Microsoft.Data.SqlClient v3.1.0

Paquet:: Microsoft.Data.SqlClient v4.0.1

Paquet:: Microsoft.Data.SqlClient v4.1.0

Paquet:: Microsoft.Data.SqlClient v5.0.0

Paquet:: Microsoft.Data.SqlClient v5.1.0

Paquet:: Microsoft.Data.SqlClient v5.2.0

Paquet:: Microsoft.Data.SqlClient v6.0.2

Paquet:: Microsoft.Data.SqlClient v6.1.3

Paquet:: Microsoft.Data.SqlClient v7.0.1

Source:: SqlConnection.cs

Source:: SqlConnection.cs

Source:: SqlConnection.cs

Source:: SqlConnection.cs

Important

Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

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. Il SqlConnection est ouvert et défini comme pour Connection le SqlCommand. L’exemple appelle ExecuteNonQueryensuite . Pour ce faire, l'ExecuteNonQuery est passé une chaîne de requête SqlConnection et une chaîne de requête qui est une instruction INSERT Transact-SQL. La connexion est fermée automatiquement lorsque le code quitte le bloc using.

using System;
using System.Data;
using Microsoft.Data.SqlClient;

namespace SqlCommand_ExecuteNonQuery
{
    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 objet SqlConnection représente une session unique à une source de données SQL Server. Avec un système de base de données client/serveur, il équivaut à une connexion réseau au serveur. SqlConnection est utilisé avec SqlDataAdapter et SqlCommand pour augmenter les performances lors de la connexion à un base de données Microsoft SQL Server. Pour tous les produits SQL Server tiers et d’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 d’un chaîne de connexion.

Si la SqlConnection portée est hors de portée, elle ne sera pas fermée. 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 true ou yessi la connexion sous-jacente est retournée au pool de connexions. En revanche, si Pooling elle est définie false sur ou no, la connexion sous-jacente au serveur est réellement fermée.

Note

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

Note

Pour déployer des applications hautes performances, vous devez utiliser le regroupement de connexions. Lorsque vous utilisez .NET Framework Fournisseur de données pour SQL Server, vous n’avez pas besoin d’activer le regroupement de connexions, car le fournisseur gère cette fonctionnalité automatiquement, 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, il SqlConnection reste ouvert lorsque le niveau de gravité est de 19 ou moins. Lorsque le niveau de gravité est égal à 20 ou supérieur, le serveur ferme généralement le SqlConnection. Toutefois, l’utilisateur peut 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’une autorisation suffisante pour 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 l' Caspol.exe (Outil de stratégie de sécurité d’accès au code) 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 illustrant comment utiliser les demandes de sécurité, consultez Sécurité d’accès au code et ADO.NET.

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

Avertissement

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 le chaîne de connexion ou vous pouvez utiliser localhost.

Constructeurs

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

Propriétés

Nom	Description
AccessToken	Obtient ou définit le jeton d’accès pour la connexion.
AccessTokenCallback	Obtient ou définit le rappel de jeton d’accès pour la connexion.
CanCreateBatch	Obtient une valeur qui indique si cette SqlConnection instance prend en charge la DbBatch classe.
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 clé de chiffrement de colonne dans le cache de clé de chiffrement de colonne pour la fonctionnalité Always Encrypted . La valeur par défaut est de 2 heures. 0 signifie qu’aucune mise en cache n’est du tout.
ColumnEncryptionQueryMetadataCacheEnabled	Obtient 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 exécutées sur des bases de données activées par 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 lors du traitement d’une requête d’application, le pilote reçoit un chemin de clé qui n’est pas dans la liste, la requête échoue. Cette propriété offre une protection supplémentaire contre les attaques de sécurité qui impliquent une SQL Server compromise fournissant des chemins de clés factices, ce qui peut entraîner la fuite des informations d’identification du magasin de clés.
CommandTimeout	Obtient le temps d’attente par défaut (en secondes) avant de terminer la tentative d’exécution d’une commande et de générer une erreur. La valeur par défaut est de 30 secondes.
ConnectionString	Obtient ou définit la chaîne utilisée pour ouvrir une base de données SQL Server.
ConnectionTimeout	Obtient le temps d’attente lors de la tentative d’établissement d’une connexion avant de terminer la tentative et de générer une erreur.
Credential	Obtient ou définit l’objet SqlCredential de cette connexion.
Database	Obtient le nom de la base de données active ou de la base de données à utiliser après l’ouverture d’une connexion.
DataSource	Obtient le nom de l’instance de SQL Server à laquelle se connecter.
FireInfoMessageEventOnUserErrors	Obtient ou définit la FireInfoMessageEventOnUserErrors propriété.
PacketSize	Obtient la taille (en octets) des paquets réseau utilisés pour 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 qui contient la version de l’instance de SQL Server à laquelle le client est connecté.
SspiContextProvider	Obtient ou définit l’instance SspiContextProvider pour personnaliser le contexte SSPI. S’il n’est pas défini, la valeur par défaut de la plateforme est utilisée.
State	Indique l’état de SqlConnection l’opération réseau la plus récente effectuée sur la connexion.
StatisticsEnabled	Lorsque la valeur est définie `true`, active la collecte des statistiques pour la connexion actuelle.
WorkstationId	Obtient une chaîne qui identifie le client de base de données.

Méthodes

Nom	Description
BeginTransaction()	Démarre une transaction de base de données.
BeginTransaction(IsolationLevel, String)	Démarre une transaction de base de données avec le niveau d’isolation et le nom de transaction spécifiés.
BeginTransaction(IsolationLevel)	Démarre une transaction de base de données avec le niveau d’isolation spécifié.
BeginTransaction(String)	Démarre une transaction de base de données avec le nom de transaction spécifié.
ChangeDatabase(String)	Modifie la base de données active pour une base de données ouverte SqlConnection.
ChangePassword(String, SqlCredential, SecureString)	Modifie le mot de passe SQL Server de l’utilisateur indiqué dans l’objet SqlCredential.
ChangePassword(String, String)	Modifie le mot de passe SQL Server de l’utilisateur indiqué dans le 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. Il s’agit de la méthode préférée de fermeture d’une connexion ouverte.
CreateCommand()	Crée et retourne un SqlCommand objet associé au SqlConnection.
EnlistDistributedTransaction(ITransaction)	Inscrit dans la transaction spécifiée en tant que transaction distribuée.
EnlistTransaction(Transaction)	Inscrit dans la transaction spécifiée en tant que transaction distribuée.
GetSchema()	Retourne des informations de schéma pour la source de données de ce SqlConnection. Pour plus d’informations sur le schéma, consultez SQL Server Collections de schémas.
GetSchema(String, String[])	Retourne des informations de schéma pour la source de données de cette SqlConnection méthode à l’aide de la chaîne spécifiée pour le nom du schéma et du tableau de chaînes spécifié pour les valeurs de restriction.
GetSchema(String)	Retourne des informations de schéma pour la source de données de cette SqlConnection méthode à l’aide de la chaîne spécifiée pour le nom du schéma.
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 , qui ouvre une connexion de base de données avec les paramètres de Open()propriété spécifiés par le ConnectionString. Le jeton d’annulation peut être utilisé pour demander que l’opération soit abandonnée avant l’expiration du délai d’expiration de la connexion. Les exceptions sont propagées via la tâche retournée. Si le délai d’expiration de la connexion s’écoule sans se connecter correctement, la tâche retournée est marquée comme étant défectueuse avec une exception. L’implémentation retourne une tâche sans bloquer le thread appelant pour les connexions mises en pool et non mises en pool.
OpenAsync(SqlConnectionOverrides, CancellationToken)	Version asynchrone de , qui ouvre une connexion de base de données avec les paramètres de Open()propriété spécifiés par le ConnectionString. Le jeton d’annulation peut être utilisé pour demander que l’opération soit abandonnée avant l’expiration du délai d’expiration de la connexion. Les exceptions sont propagées via la tâche retournée. Si le délai d’expiration de la connexion s’écoule sans se connecter correctement, la tâche retournée est marquée comme étant défectueuse avec une exception. L’implémentation retourne une tâche sans bloquer le thread appelant pour les connexions mises en pool et non mises en pool.
RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>)	Inscrit les fournisseurs de magasins de clés de chiffrement de colonne. Cette fonction ne doit être appelée qu’une seule fois dans une application. Cette opération 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 l’instance SqlConnection . Si cette fonction a été appelée, tous les fournisseurs inscrits à l’aide des méthodes statiques RegisterColumnEncryptionKeyStoreProviders(IDictionary<String,SqlColumnEncryptionKeyStoreProvider>) sont ignorés. Cette fonction peut être appelée plusieurs fois. Cette opération 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 la collecte des statistiques est activée, toutes les valeurs sont réinitialisées à 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 paires de valeurs de nom de statistiques au moment où la méthode est appelée.

Événements

Nom	Description
InfoMessage	Se produit lorsque SQL Server retourne un message d’avertissement ou d’information.

Implémentations d’interfaces explicites

Nom	Description
ICloneable.Clone()	Crée un objet qui est une copie de l’instance actuelle.

S’applique à