SqlConnectionStringBuilder Classe

Référence

Définition

Espace de noms:: System.Data.SqlClient

Assembly:: System.Data.SqlClient.dll

Assembly:: System.Data.dll

Paquet:: System.Data.SqlClient v4.8.6

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.

Fournit un moyen simple de créer et de gérer le contenu des 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

[System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

[<System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Héritage: Object

DbConnectionStringBuilder
SqlConnectionStringBuilder

Attributs: TypeConverterAttribute

Exemples

L’application console suivante génère des chaînes de connexion pour une base de données SQL Server. Le code utilise la classe SqlConnectionStringBuilder pour créer la chaîne de connexion. L’exemple analyse ensuite la chaîne de connexion et montre différentes façons de manipuler son contenu.

// Create a new SqlConnectionStringBuilder and
// initialize it with a few name/value pairs.
SqlConnectionStringBuilder builder = new(
    "Server=(local);Integrated Security=true;" +
    "Initial Catalog=AdventureWorks"
    );

// The input connection string used the
// Server key, but the new connection string uses
// the well-known Data Source key instead.
Console.WriteLine($"Original connection string: '{builder.ConnectionString}'");

// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine($"Initial catalog: '{builder.InitialCatalog}'");
builder.InitialCatalog = "Northwind";
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($"Modified connection string: '{builder.ConnectionString}'");

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(
            "Server=(local);Integrated Security=true;" &
            "Initial Catalog=AdventureWorks"
            )

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

        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine("Initial catalog: " + builder.InitialCatalog)
        builder.InitialCatalog = "Northwind"
        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("Modified connection string: " + builder.ConnectionString)
    End Sub
End Module

Remarques

Le générateur de chaînes de connexion permet aux développeurs de créer par programmation des chaînes de connexion correctes par programmation, d’analyser et de reconstruire 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. Si vous devez créer des chaînes de connexion dans le cadre de votre application, vous pouvez utiliser la classe SqlConnectionStringBuilder pour générer et modifier des chaînes de connexion. La classe facilite également la gestion des chaînes de connexion stockées dans un fichier de configuration d’application.

SqlConnectionStringBuilder effectue des vérifications pour les paires clé/valeur valides. Par conséquent, vous ne pouvez pas utiliser cette classe pour créer des chaînes de connexion non valides ; la tentative d’ajout de paires non valides lève une exception. La classe conserve une collection fixe de synonymes et peut passer d’un synonyme au nom de clé connu correspondant.

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 de 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 une chaîne de connexion lorsque vous utilisez un membre qui nécessite une chaîne qui contient le nom de clé, tel que la propriété Item[String] ou la méthode Remove. Consultez la propriété ConnectionString pour obtenir la liste complète des synonymes acceptables.

La propriété Item[String] gère les tentatives d’insertion d’entrées malveillantes. Par exemple, le code suivant, à l’aide de la propriété Item par défaut (l’indexeur, en C#) échappe correctement 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 fournie fournit les données des 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 définir la valeur de cette propriété avec ApplicationIntent. Pour plus d’informations sur la prise en charge de SqlClient pour les groupes de disponibilité Always On, consultez prise en charge de SqlClient pour la haute disponibilité, la récupération d’urgence.
ApplicationName	Obtient ou définit le nom de l’application associée à la chaîne de connexion.
AsynchronousProcessing	Obtient ou définit une valeur booléenne qui indique si le traitement asynchrone est autorisé par la connexion créée à l’aide de cette 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 complet du chemin d’accès d’une base de données pouvant être attachée.
Authentication	Obtient l’authentification de la chaîne de connexion.
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)
ColumnEncryptionSetting	Obtient ou définit les paramètres de chiffrement de colonne pour le générateur de chaînes de connexion.
ConnectionReset	Obsolète. Obsolète. Obtient ou définit une valeur booléenne qui indique si la connexion est réinitialisée lorsqu’elle est dessinée à partir du pool de connexions.
ConnectionString	Obtient ou définit la chaîne de connexion associée au DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
ConnectRetryCount	Nombre de reconnexions tentées après avoir identifié qu’il y avait un échec de connexion inactif. Il doit s’agir d’un entier compris entre 0 et 255. La valeur par défaut est 1. Définissez la valeur 0 pour désactiver la reconnexion en cas d’échec de connexion inactive. Une ArgumentException est levée si elle est définie sur une valeur en dehors de la plage autorisée.
ConnectRetryInterval	Durée (en secondes) entre chaque tentative de reconnexion après avoir identifié qu’il y avait un échec de connexion inactif. Il doit s’agir d’un entier compris entre 1 et 60. La valeur par défaut est de 10 secondes. Une ArgumentException est levée si elle est définie sur une valeur en dehors de la plage autorisée.
ConnectTimeout	Obtient ou définit la durée (en secondes) d’attente d’une connexion au serveur avant de terminer la tentative et de générer une erreur.
ContextConnection	Obtient ou définit une valeur qui indique si une connexion client/serveur ou in-process à SQL Server doit être établie.
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 de l’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.
EnclaveAttestationUrl	Obtient ou définit l’URL d’attestation d’enclave à utiliser avec Always Encrypted basé sur enclave.
Encrypt	Obtient ou définit une valeur booléenne qui indique si SQL Server utilise le chiffrement SSL pour toutes les données envoyées entre le client et le serveur si un certificat est installé sur le serveur.
Enlist	Obtient ou définit une valeur booléenne qui indique si le pool de connexions 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 arrêté.
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 d’identification du compte Windows actuelles sont utilisées pour l’authentification (quand `true`).
IsFixedSize	Obtient une valeur qui indique si le SqlConnectionStringBuilder a une taille fixe.
IsFixedSize	Obtient une valeur qui indique si le DbConnectionStringBuilder a une taille fixe. (Hérité de DbConnectionStringBuilder)
IsReadOnly	Obtient une valeur qui indique si la 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 dans le SqlConnectionStringBuilder.
LoadBalanceTimeout	Obtient ou définit la durée minimale, en secondes, pour que la connexion se trouve dans le pool de connexions avant d’être détruite.
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	Lorsque la valeur est true, une application peut gérer plusieurs jeux de résultats actifs (MARS). Lorsque la valeur est false, une application doit traiter ou annuler tous les jeux de résultats d’un lot avant de pouvoir exécuter n’importe quel autre lot sur cette connexion. Pour plus d’informations, consultez plusieurs jeux de résultats actifs (MARS).
MultiSubnetFailover	Si votre application se connecte à un groupe de disponibilité Always On ou à une instance de cluster de basculement Always On (FCI) sur différents sous-réseaux, la définition de MultiSubnetFailover=true permet une détection et une connexion plus rapides au serveur actif (actuellement). 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.
NetworkLibrary	Obtient ou définit une chaîne qui contient le nom de la bibliothèque réseau utilisée pour établir une connexion à SQL Server.
PacketSize	Obtient ou définit la taille en octets des paquets réseau utilisés pour 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 des 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 la chaîne de connexion sur une connexion créée avec cette SqlConnectionStringBuilder après que cette connexion ait été dans un état ouvert.
PoolBlockingPeriod	Comportement de période de blocage pour un pool de connexions.
Pooling	Obtient ou définit une valeur booléenne qui indique si la connexion sera mise en pool 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 à l’aide de la connexion.
TransactionBinding	Obtient ou définit une valeur de chaîne qui indique comment la connexion conserve son association avec une transaction `System.Transactions` inscrite.
TransparentNetworkIPResolution	Lorsque la valeur de cette clé est définie sur `true`, l’application est requise pour récupérer toutes les adresses IP d’une entrée DNS particulière et tenter de se connecter avec la première dans la liste. Si la connexion n’est pas établie dans les 0,5 secondes, l’application tente de se connecter à tous les autres en parallèle. Lorsque les premières réponses sont fournies, l’application établit la connexion avec l’adresse IP du répondant.
TrustServerCertificate	Obtient ou définit une valeur qui indique si le canal sera chiffré lors du contournement de la marche à pied de la chaîne de certificats pour valider l’approbation.
TypeSystemVersion	Obtient ou définit une valeur de chaîne qui indique le système de type attendu par l’application.
UserID	Obtient ou définit l’ID 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 SQL Server Express par défaut vers une instance lancée par le runtime exécutée sous le compte de l’appelant.
Values	Obtient une ICollection qui contient les valeurs dans le SqlConnectionStringBuilder.
WorkstationID	Obtient ou définit le nom de la station de travail qui se connecte à SQL Server.

Méthodes

Add(String, Object)	Ajoute une entrée avec la clé et la valeur spécifiées dans le DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
Clear()	Efface le contenu de l’instance de SqlConnectionStringBuilder.
ClearPropertyDescriptors()	Efface la collection d’objets PropertyDescriptor sur le DbConnectionStringBuilderassocié. (Hérité de DbConnectionStringBuilder)
ContainsKey(String)	Détermine si le 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 dans cet objet DbConnectionStringBuilder avec les informations de connexion de l’objet fourni. (Hérité de DbConnectionStringBuilder)
GetHashCode()	Sert 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 cette DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
GetType()	Obtient la Type de l’instance actuelle. (Hérité de Object)
MemberwiseClone()	Crée une copie superficielle du Objectactuel. (Hérité de Object)
Remove(String)	Supprime l’entrée avec la clé spécifiée de l’instance SqlConnectionStringBuilder.
ShouldSerialize(String)	Indique si la clé spécifiée existe dans cette instance SqlConnectionStringBuilder.
ToString()	Retourne la chaîne de connexion associée à cette DbConnectionStringBuilder. (Hérité de DbConnectionStringBuilder)
TryGetValue(String, Object)	Récupère une valeur correspondant à la clé fournie à partir de cette SqlConnectionStringBuilder.

Implémentations d’interfaces explicites

ICollection.CopyTo(Array, Int32)	Copie les éléments du ICollection dans un Array, en commençant à un index Array particulier. (Hérité de DbConnectionStringBuilder)
ICollection.IsSynchronized	Obtient une valeur indiquant si l’accès au ICollection est synchronisé (thread safe). (Hérité de DbConnectionStringBuilder)
ICollection.SyncRoot	Obtient un objet qui peut être utilisé pour synchroniser l’accès au ICollection. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetAttributes()	Retourne une collection d’attributs personnalisés pour cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetClassName()	Retourne le nom de classe de cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()	Retourne le nom de cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetConverter()	Retourne un convertisseur de type pour cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultEvent()	Retourne l’événement par défaut pour cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultProperty()	Retourne la propriété par défaut pour cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEditor(Type)	Retourne un éditeur du type spécifié pour cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents()	Retourne les événements de cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])	Retourne les événements de cette instance d’un composant à l’aide du tableau d’attributs spécifié en tant que filtre. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()	Retourne les propriétés de cette instance d’un composant. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])	Retourne les propriétés de cette instance d’un composant à l’aide du tableau d’attributs en tant que filtre. (Hérité de DbConnectionStringBuilder)
ICustomTypeDescriptor.GetPropertyOwner(PropertyDescriptor)	Retourne un objet qui contient la propriété décrite par le descripteur de propriété spécifié. (Hérité de DbConnectionStringBuilder)
IDictionary.Add(Object, Object)	Ajoute un élément avec la clé et la valeur fournies à l’objet IDictionary. (Hérité de DbConnectionStringBuilder)
IDictionary.Contains(Object)	Détermine si l’objet IDictionary contient un élément avec la clé spécifiée. (Hérité de DbConnectionStringBuilder)
IDictionary.GetEnumerator()	Retourne un objet IDictionaryEnumerator pour l’objet IDictionary. (Hérité de DbConnectionStringBuilder)
IDictionary.IsFixedSize	Obtient une valeur indiquant si l’objet IDictionary a une taille fixe. (Hérité de DbConnectionStringBuilder)
IDictionary.IsReadOnly	Obtient une valeur indiquant si le IDictionary est en lecture seule. (Hérité de DbConnectionStringBuilder)
IDictionary.Item[Object]	Obtient ou définit l’élément avec la clé spécifiée. (Hérité de DbConnectionStringBuilder)
IDictionary.Remove(Object)	Supprime l’élément avec la clé spécifiée de l’objet IDictionary. (Hérité de DbConnectionStringBuilder)
IEnumerable.GetEnumerator()	Retourne un énumérateur qui itère dans une collection. (Hérité de DbConnectionStringBuilder)

Méthodes d’extension

Cast<TResult>(IEnumerable)	Convertit les éléments d’un IEnumerable en type spécifié.
OfType<TResult>(IEnumerable)	Filtre les éléments d’une IEnumerable en fonction d’un type spécifié.
AsParallel(IEnumerable)	Active la parallélisation d’une requête.
AsQueryable(IEnumerable)	Convertit un IEnumerable en IQueryable.

S’applique à

Voir aussi

chaînes de connexion (ADO.NET)
ADO.NET Vue d’ensemble

Partager via