SqlConnectionStringBuilder Classe

Définition

Espace de noms:

System.Data.SqlClient

Assembly:

System.Data.SqlClient.dll

Paquet:

System.Data.SqlClient v4.8.6

Fournit un moyen simple de créer et de gérer le contenu de chaînes de connexion utilisées par la classe SqlConnection.

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder

public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Héritage

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

Exemples

L’application console suivante génère des chaînes de connexion pour une base de données SQL Server. Le code utilise une classe SqlConnectionStringBuilder pour créer la chaîne de connexion, puis passe la propriété ConnectionString de l'instance de SqlConnectionStringBuilder au constructeur de la classe de connexion. L'exemple analyse également une chaîne de connexion existante et présente plusieurs façons de manipuler le contenu de la chaîne de connexion.

Notes

Cet exemple inclut un mot de passe pour illustrer l'utilisation de SqlConnectionStringBuilder avec les chaînes de connexion. Dans vos applications, nous vous recommandons d'utiliser l'authentification Windows. Si vous devez utiliser un mot de passe, n'incluez pas de mot de passe codé en dur dans votre application.

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

class Program
{
    static void Main()
    {
        // Create a new SqlConnectionStringBuilder and
        // initialize it with a few name/value pairs.
        SqlConnectionStringBuilder builder =
            new SqlConnectionStringBuilder(GetConnectionString());

        // The input connection string used the
        // Server key, but the new connection string uses
        // the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString);

        // Pass the SqlConnectionStringBuilder an existing
        // connection string, and you can retrieve and
        // modify any of the elements.
        builder.ConnectionString = "server=(local);user id=ab;" +
            "password= a!Pass113;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "new@1Password";
        builder.AsynchronousProcessing = true;

        // You can refer to connection keys using strings,
        // as well. When you use this technique (the default
        // Item property in Visual Basic, or the indexer in C#),
        // you can specify any synonym for the connection string key
        // name.
        builder["Server"] = ".";
        builder["Connect Timeout"] = 1000;
        builder["Trusted_Connection"] = true;
        Console.WriteLine(builder.ConnectionString);

        Console.WriteLine("Press Enter to finish.");
        Console.ReadLine();
    }

    private static string GetConnectionString()
    {
        // To avoid storing the connection string in your code,
        // you can retrieve it from a configuration file.
        return "Server=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}

Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As New SqlConnectionStringBuilder(GetConnectionString())

        ' The input connection string used the 
        ' Server key, but the new connection string uses
        ' the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString)

        ' Pass the SqlConnectionStringBuilder an existing 
        ' connection string, and you can retrieve and
        ' modify any of the elements.
        builder.ConnectionString = _
            "server=(local);user id=ab;" & _
            "password=a!Pass113;initial catalog=AdventureWorks"
        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine(builder.Password)
        builder.Password = "new@1Password"
        builder.AsynchronousProcessing = True

        ' You can refer to connection keys using strings, 
        ' as well. When you use this technique (the default
        ' Item property in Visual Basic, or the indexer in C#)
        ' you can specify any synonym for the connection string key
        ' name.
        builder("Server") = "."
        builder("Connect Timeout") = 1000

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine(builder.ConnectionString)

        Console.WriteLine("Press Enter to finish.")
        Console.ReadLine()
    End Sub

    Private Function GetConnectionString() As String
        ' To avoid storing the connection string in your code,
        ' you can retrieve it from a configuration file. 
        Return "Server=(local);Integrated Security=SSPI;" & _
          "Initial Catalog=AdventureWorks"
    End Function
End Module

Remarques

Le générateur de chaînes de connexion permet aux développeurs de créer par programme des chaînes de connexion correctes du point de vue de la syntaxe, et d'analyser et régénérer des chaînes de connexion existantes, à l'aide de propriétés et de méthodes de la classe. Le générateur de chaînes de connexion fournit des propriétés fortement typées correspondant aux paires clé/valeur connues autorisées par SQL Server. Les développeurs ayant besoin de créer des chaînes de connexion dans le cadre d'applications peuvent utiliser la classe SqlConnectionStringBuilder pour générer et modifier des chaînes de connexion. Cette classe permet également de gérer facilement les chaînes de connexion stockées dans un fichier de configuration de l'application.

SqlConnectionStringBuilder vérifie la validité des paires clé/valeur. Par conséquent, il n'est pas possible d'utiliser cette classe pour créer des chaînes de connexion non valides ; toute tentative d'ajout de paires non valides lève une exception. La classe maintient une collection fixe de synonymes et peut traduire un synonyme vers le nom de la clé connue correspondante.

Par exemple, lorsque vous utilisez la propriété Item pour récupérer une valeur, vous pouvez spécifier une chaîne qui contient n’importe quel synonyme pour la clé dont vous avez besoin. Par exemple, vous pouvez spécifier « Adresse réseau », « addr » ou tout autre synonyme acceptable pour cette clé dans un chaîne de connexion lorsque vous utilisez un membre qui nécessite une chaîne qui contient le nom de la clé, comme la propriété Item ou la Remove méthode. Pour obtenir la liste complète des synonymes acceptables, consultez la propriété ConnectionString.

La propriété Item gère tente d’insérer des entrées malveillantes. Par exemple, le code suivant, qui utilise la propriété Item par défaut (l'indexeur en C#) s'échappe correctement de la paire clé/valeur imbriquée :

Dim builder As New System.Data.SqlClient.SqlConnectionStringBuilder
builder("Data Source") = "(local)"
builder("Integrated Security") = True
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"
Console.WriteLine(builder.ConnectionString)

System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.Data.SqlClient.SqlConnectionStringBuilder();
builder["Data Source"] = "(local)";
builder["integrated Security"] = true;
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";
Console.WriteLine(builder.ConnectionString);

Le résultat est la chaîne de connexion suivante qui gère la valeur non valide de manière sécurisée.

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";
Integrated Security=True

Constructeurs

SqlConnectionStringBuilder()	Initialise une nouvelle instance de la classe SqlConnectionStringBuilder.
SqlConnectionStringBuilder(String)	Initialise une nouvelle instance de la classe SqlConnectionStringBuilder. La chaîne de connexion spécifiée fournit les données pour les informations de connexion internes de l'instance.

Propriétés

ApplicationIntent	Déclare le type de charge de travail de l'application lors de la connexion à une base de données dans un groupe de disponibilité SQL Server. Vous pouvez affecter à cette propriété la valeur ApplicationIntent. Pour plus d’informations sur la prise en charge de SqlClient pour les groupes de disponibilité AlwaysOn, consultez Prise en charge de SqlClient pour la haute disponibilité et la récupération d’urgence.
ApplicationName	Obtient ou définit le nom de l'application associée à la chaîne de connexion.
AttachDBFilename	Obtient ou définit une chaîne qui contient le nom du fichier de données principal. Cela inclut le nom du chemin d'accès complet d'une base de données pouvant être attachée.
BrowsableConnectionString	Obtient ou définit une valeur qui indique si la propriété ConnectionString est visible dans les concepteurs Visual Studio. (Hérité de DbConnectionStringBuilder)
ConnectionString	Obtient ou définit la chaîne de connexion associée au DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
ConnectRetryCount	Nombre de tentatives de reconnexion après l’identification de l’échec de connexion inactive. La valeur doit être un entier compris entre 0 et 255. 1 constitue la valeur par défaut. Définissez la valeur sur 0 pour désactiver la reconnexion en cas d’échec de connexion inactive. Une ArgumentException est levée si la valeur n’appartient pas à la plage autorisée.
ConnectRetryInterval	Durée (en secondes) entre chaque tentative de reconnexion après identification d’un échec de connexion inactive. La valeur doit être un entier compris entre 1 et 60. La valeur par défaut est 10 secondes. Une ArgumentException est levée si la valeur n’appartient pas à la plage autorisée.
ConnectTimeout	Obtient ou définit la durée d'attente (en secondes) préalable à l'établissement d'une connexion au serveur avant que la tentative ne soit abandonnée et qu'une erreur ne soit générée.
Count	Obtient le nombre actuel de clés contenues dans la propriété ConnectionString. (Hérité de DbConnectionStringBuilder)
CurrentLanguage	Obtient ou définit le nom d'enregistrement du langage SQL Server.
DataSource	Obtient ou définit le nom ou l'adresse réseau de l'instance de SQL Server à laquelle se connecter.
Encrypt	Obtient ou définit une valeur booléenne qui indique si SQL Server utilise le chiffrement SSL pour tous les échanges de données se produisant entre le client et le serveur si celui-ci dispose d'un certificat installé.
Enlist	Obtient ou définit une valeur booléenne qui indique si le pooler de connexion SQL Server inscrit automatiquement la connexion dans le contexte de transaction actuel du thread de création.
FailoverPartner	Obtient ou définit le nom ou l'adresse du serveur partenaire auquel se connecter si le serveur principal est en panne.
InitialCatalog	Obtient ou définit le nom de la base de données associée à la connexion.
IntegratedSecurity	Obtient ou définit une valeur booléenne qui indique si l’ID d’utilisateur et le mot de passe sont spécifiés dans la connexion (quand false) ou si les informations actuelles d’identification du compte Windows sont utilisées pour l’authentification (quand true).
IsFixedSize	Obtient une valeur qui indique si DbConnectionStringBuilder est de taille fixe. (Hérité de DbConnectionStringBuilder)
IsReadOnly	Obtient une valeur qui indique si l’objet DbConnectionStringBuilder est en lecture seule. (Hérité de DbConnectionStringBuilder)
Item[String]	Obtient ou définit la valeur associée à la clé spécifiée. En C#, cette propriété est l'indexeur.
Keys	Obtient un ICollection qui contient les clés de SqlConnectionStringBuilder.
LoadBalanceTimeout	Obtient ou définit la durée de vie minimale, en secondes, de la connexion dans le pool de connexions avant sa destruction.
MaxPoolSize	Obtient ou définit le nombre maximal de connexions autorisées dans le pool de connexions pour cette chaîne de connexion spécifique.
MinPoolSize	Obtient ou définit le nombre minimal de connexions autorisées dans le pool de connexions pour cette chaîne de connexion spécifique.
MultipleActiveResultSets	Si la valeur est true, une application peut conserver plusieurs jeux MARS (Multiple Active Result Sets). Si la valeur est false, une application doit traiter ou annuler tous les jeux de résultats d’un lot avant de pouvoir exécuter un autre lot sur cette connexion. Pour plus d’informations, consultez MARS (Multiple Active Result Sets).
MultiSubnetFailover	Si votre application se connecte à un groupe de disponibilité Always On ou Always On instance de cluster de basculement (FCI) sur différents sous-réseaux, la définition de MultiSubnetFailover=true permet une détection et une connexion plus rapides au serveur (actuellement) actif. Pour plus d’informations sur la prise en charge de SqlClient pour les fonctionnalités Always On, consultez Prise en charge de SqlClient pour la haute disponibilité, la récupération d’urgence.
PacketSize	Obtient ou définit la taille en octets des paquets réseau permettant de communiquer avec une instance de SQL Server.
Password	Obtient ou définit le mot de passe du compte SQL Server.
PersistSecurityInfo	Obtient ou définit une valeur indiquant si les informations sensibles à la sécurité, telles que le mot de passe ou le jeton d’accès, doivent être retournées dans le cadre de l’chaîne de connexion sur une connexion créée avec cette SqlConnectionStringBuilder connexion une fois que cette connexion a jamais été dans un état ouvert.
Pooling	Obtient ou définit une valeur booléenne qui indique si la connexion sera regroupée ou ouverte explicitement chaque fois que la connexion est demandée.
Replication	Obtient ou définit une valeur booléenne qui indique si la réplication est prise en charge avec la connexion.
TransactionBinding	Obtient ou définit une valeur de chaîne indiquant comment la connexion continue d’être associée à la transaction System.Transactions inscrite.
TrustServerCertificate	Obtient ou définit une valeur qui indique si le canal sera chiffré dans le cas où l'approbation de la chaîne de certificats est ignorée.
TypeSystemVersion	Obtient ou définit une valeur de chaîne qui indique le système de type que l'application attend.
UserID	Obtient ou définit l'ID d'utilisateur à utiliser lors de la connexion à SQL Server.
UserInstance	Obtient ou définit une valeur qui indique s'il faut rediriger la connexion de l'instance de SQL Server Express par défaut vers une instance lancée à l'exécution qui s'exécute sous le compte de l'appelant.
Values	Obtient un objet ICollection qui contient les valeurs de l'objet SqlConnectionStringBuilder.
WorkstationID	Obtient ou définit le nom de la station de travail se connectant à SQL Server.

Méthodes

Add(String, Object)	Ajoute une entrée avec la clé et la valeur spécifiées dans DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
Clear()	Efface le contenu de l'instance SqlConnectionStringBuilder.
ClearPropertyDescriptors()	Efface la collection d’objets PropertyDescriptor du DbConnectionStringBuilder associé. (Hérité de DbConnectionStringBuilder)
ContainsKey(String)	Détermine si SqlConnectionStringBuilder contient une clé spécifique.
Equals(Object)	Détermine si l'objet spécifié est égal à l'objet actuel. (Hérité de Object)
EquivalentTo(DbConnectionStringBuilder)	Compare les informations de connexion de cet objet DbConnectionStringBuilder avec les informations de connexion de l’objet fourni. (Hérité de DbConnectionStringBuilder)
GetHashCode()	Fait office de fonction de hachage par défaut. (Hérité de Object)
GetProperties(Hashtable)	Remplit un Hashtable fourni avec des informations sur toutes les propriétés de ce DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
GetType()	Obtient le Type de l'instance actuelle. (Hérité de Object)
MemberwiseClone()	Crée une copie superficielle du Object actuel. (Hérité de Object)
Remove(String)	Supprime l'entrée contenant la clé spécifiée dans l'instance de SqlConnectionStringBuilder.
ShouldSerialize(String)	Indique si la clé spécifiée existe dans cette instance de SqlConnectionStringBuilder.
ToString()	Retourne la chaîne de connexion associée à ce DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
TryGetValue(String, Object)	Récupère une valeur correspondant à la clé fournie à partir de cet objet SqlConnectionStringBuilder.

Méthodes d’extension

Voir aussi

• Chaînes de connexion (ADO.NET)
• Vue d'ensemble d’ADO.NET