SqlConnectionStringBuilder Classe

Définition

Espace de noms:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Package:

Microsoft.Data.SqlClient v7.1.0

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

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

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

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Héritage

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 une SqlConnectionStringBuilder classe pour créer le chaîne de connexion, puis transmet la ConnectionString propriété de l’instance SqlConnectionStringBuilder au constructeur de la classe de connexion. L'exemple analyse également une chaîne de connexion existante et montre différentes façons de manipuler le contenu du chaîne de connexion.

Note

Cet exemple inclut un mot de passe pour illustrer le SqlConnectionStringBuilder fonctionnement des 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 Microsoft.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=********;initial catalog=AdventureWorks";

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

        // 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";
    }
}

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. Les développeurs qui ont besoin de créer des chaînes de connexion dans le cadre d’applications peuvent utiliser la SqlConnectionStringBuilder classe 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.

Le SqlConnectionStringBuilder service 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 tout synonyme de la clé dont vous avez besoin. Par exemple, vous pouvez spécifier « Adresse réseau », « addr » ou tout autre synonyme acceptable de cette clé dans un 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 ou la Remove méthode. Consultez la propriété ConnectionString pour obtenir la liste complète des synonymes acceptables.

La propriété Item 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 Microsoft.Data.SqlClient.SqlConnectionStringBuilder  
builder("Data Source") = "(local)"  
builder("Integrated Security") = True  
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"  
Console.WriteLine(builder.ConnectionString)  

Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =  
new Microsoft.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

Nom	Description
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

Nom	Description
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é 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 complet du chemin d’accès d’une base de données pouvant être attachée.
AttestationProtocol	Obtient ou définit la valeur du protocole d’attestation.
Authentication	Obtient ou définit la méthode d’authentification utilisée pour Se connecter avec Microsoft Entra pour Azure SQL ressources.
ColumnEncryptionSetting	Obtient ou définit les paramètres de chiffrement de colonne pour le générateur de chaînes de connexion.
CommandTimeout	Délai d’attente par défaut (en secondes) avant l’arrêt de la tentative d’exécution d’une commande, et la génération d’une erreur. La valeur par défaut est 30 secondes.
ConnectionReset	Obsolète. Obsolete. 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.
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 pour les points de terminaison non Azure est 1. Pour les points de terminaison Azure SQL, la valeur par défaut est 2. À compter de la version 5.x, pour Azure SQL point de terminaison serverless ou à la demande, la valeur par défaut est 5 pour améliorer la réussite de la connexion pour les connexions à une instance inactive ou suspendue. Définissez la valeur 0 pour désactiver la reconnexion en cas d’échec de connexion inactive. Une ArgumentException valeur 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.
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.
CurrentLanguage	Obtient ou définit la langue utilisée pour les messages d’avertissement ou d’erreur du serveur de base de données.
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 SqlConnectionEncryptOption valeur depuis la version 5.0 ou une Boolean valeur pour les versions antérieures qui indique si le chiffrement TLS est requis pour toutes les données envoyées entre le client et 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é.
FailoverPartnerSPN	Obtient ou définit le nom du principal de service (SPN) du partenaire de basculement pour la connexion.
HostNameInCertificate	Obtient ou définit le nom d’hôte à utiliser lors de la validation du certificat de serveur pour la connexion. Lorsqu’il n’est pas spécifié, le nom du serveur à partir de celui-ci est utilisé pour la Data Source validation de certificat. (Disponible uniquement dans v5.0+)
IdleTimeout	Obtient ou définit la durée maximale, en secondes, qu’une connexion peut rester inutilisée (inactive) dans le pool de connexions avant d’être ignorée. La valeur par défaut est 300 (5 minutes).
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 de compte Windows actuelles sont utilisées pour l’authentification (quand true ).
IPAddressPreference	Obtient ou définit la préférence de famille d’adresses IP lors de l’établissement de connexions TCP.
IsFixedSize	Obtient une valeur qui indique si la SqlConnectionStringBuilder taille fixe est définie.
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é AlwaysOn sur différents sous-réseaux, le paramètre MultiSubnetFailover=true fournit 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 groupes de disponibilité AlwaysOn, consultez Prise en charge de SqlClient pour la haute disponibilité et 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 booléenne 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 celle-ci SqlConnectionStringBuilder après que cette connexion ait été dans un état ouvert. Cette propriété ne doit être définie true que si votre application a un besoin spécifique de lire le mot de passe d’une connexion de base de données déjà ouverte. La valeur false par défaut est le paramètre plus sécurisé . L’utilisation true de cette propriété ouvre votre application aux risques de sécurité tels que la journalisation accidentelle ou le suivi du mot de passe de la base de données.
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.
ServerCertificate	Obtient ou définit le chemin d’accès à un fichier de certificat correspondant au certificat TLS/SSL SQL Server pour la connexion. Les formats de certificat acceptés sont PEM, DER et CER. S’il est spécifié, le certificat SQL Server est vérifié en vérifiant si le ServerCertificate certificat fourni est une correspondance exacte. (Disponible uniquement dans la version 5.1+)
ServerSPN	Obtient ou définit le nom du principal de service (SPN) de la source de données.
TransactionBinding	Obtient ou définit une valeur de chaîne qui indique comment la connexion conserve son association avec une transaction inscrite System.Transactions .
TransparentNetworkIPResolution	Obsolète. Sur .NET Framework, lorsque la valeur de cette clé est définietrue, le pilote exécute plusieurs rondes de connexion sur les adresses IP résolues par DNS, avec des délais d’expiration progressivement plus importants par tentative et un minimum de 500 ms sur la tentative en mode séquentiel, jusqu’à ce qu’une connexion réussisse ou que l’ensemble Connect Timeout soit atteint.
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 un 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

Nom	Description
Clear()	Efface le contenu de l’instance SqlConnectionStringBuilder .
ContainsKey(String)	Détermine si le SqlConnectionStringBuilder conteneur contient une clé spécifique.
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.
TryGetValue(String, Object)	Récupère une valeur correspondant à la clé fournie à partir de ce SqlConnectionStringBuilder .