Options de connexion pour Microsoft. Data.SqlClient

Cet article liste tous les mots-clés de chaîne de connexion que Microsoft. Data.SqlClient accepte. Chaque mot-clé possède également une propriété de correspondance SqlConnectionStringBuilder . Pour une introduction, des motifs courants et des règles d’analyse, voir Chaînes de connexion.

Les mots-clés et alias ne sont pas sensibles à la majuscule. Lorsque vous fixez une valeur via un bien constructeur, celui-ci écrit le mot-clé canonique dans la colonne Mot-clé .

Définir des options avec SqlConnectionStringBuilder

Commencez par une chaîne de connexion de base qui contient les paramètres serveur, de base de données et d’authentification. Ensuite, définissez des options spécifiques à la charge de travail via les propriétés du constructeur. Les onglets du cadre .NET utilisent C# 7.3. Pour créer un projet qui exécute les échantillons, voir Créer le projet.

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

using System;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task Main()
    {
        string connectionString =
            Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
            ?? throw new InvalidOperationException(
                "Set the SQL_CONNECTION_STRING environment variable.");

        var builder = new SqlConnectionStringBuilder(connectionString)
        {
            ApplicationName = "Orders.Worker",
            ConnectTimeout = 30,
            CommandTimeout = 60,
            MaxPoolSize = 50,
        };

        using (var connection = new SqlConnection(builder.ConnectionString))
        {
            await connection.OpenAsync();

            using (var command = new SqlCommand("SELECT APP_NAME();", connection))
            {
                Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
                Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
                Console.WriteLine($"Command timeout: {command.CommandTimeout}");
            }
        }
    }
}

La sortie est la suivante :

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

Un nouveau SqlCommand prend son délai d’expiration par défaut à partir du Command Timeout mot-clé de sa connexion.

Vérifier les valeurs par défaut

Un nouveau SqlConnectionStringBuilder signale le défaut pour chaque option. Ce programme affiche les paramètres par défaut que la plupart des applications examinent :

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        var defaults = new SqlConnectionStringBuilder();

        Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
        Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
        Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
        Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
        Console.WriteLine($"Encrypt: {defaults.Encrypt}");
        Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
        Console.WriteLine($"Pooling: {defaults.Pooling}");
        Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
        Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
        Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
        Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
        Console.WriteLine($"Packet Size: {defaults.PacketSize}");
        Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
        Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
        Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
        Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
        Console.WriteLine($"Application Name: {defaults.ApplicationName}");
        Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
        Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");
    }
}

Sur .NET, la sortie est :

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True c’est l’option Mandatory . Sur .NET Framework, le nom d’application par défaut est Framework Microsoft SqlClient Fournisseur de données.

Options serveurs et bases de données

Options d’identité d’application

Pour indiquer quel framework ou outil a ouvert une connexion, utilisez la RegisteredApplication propriété. Il n’a pas de mot-clé de chaîne de connexion. Pour plus d’informations, voir Signaler l’identité de l’application.

Options d'authentification

Authentication accepte ces valeurs. Le constructeur les écrit sans espaces, comme ActiveDirectoryDefault, et l’analyseur accepte les deux formes.

Les méthodes Microsoft Entra ID nécessitent ce Microsoft.Data.SqlClient.Extensions.Azure package. Pour la configuration et des exemples, voir l’authentification Microsoft Entra ID et l’authentification SQL Server.

Options de chiffrement

Pour les règles complètes de validation, voir Chiffrement et validation des certificats.

Options toujours chiffrées

Options réseau

Un commutateur AppContext à l’échelle du processus peut changer le Multi Subnet Failover code par défaut en true. Pour plus d’informations, voir AppContext switches dans SqlClient.

Options de temps mort

Connect Timeout ne limite pas l’exécution des requêtes. Command Timeout Cela ne limite pas la connexion ni l’attente pour une connexion regroupée. Passez A CancellationToken à des appels asynchrones afin que l’appelant puisse arrêter d’attendre avant que l’un ou l’autre délai d’attente ne s’épuise.

Options de récupération de connexion

Lorsque Connect Retry Count est 1, qui est le code par défaut, le pilote utilise 2 pour les terminaux Azure SQL et 5 pour les points de terminaison serverless SQL Azure Synapse Analytics lorsqu’il restaure une connexion inactive défaillante. La première ouverture utilise la valeur comme définie, donc la valeur par défaut permet une seule tentative sur chaque terminaison. Le pilote utilise toute autre valeur telle que définie dans les deux cas.

Ces mots-clés ne réessaient pas une commande qui échoue pendant qu’elle est en cours d’exécution. Pour éviter la réessaie intégrée pour une ouverture, appelez une Open surcharge avec OpenWithoutRetry. Pour les politiques personnalisées, voir Logique de tentative configurable. Ne retentez une commande que lorsque la répéter est sûr.

Options de regroupement

Chaque chaîne de connexion distincte a son propre pool. Pour les clés du pool, le nettoyage et le temps d’inactivité, voir pooling de connexion SQL Server.

Options de transaction et de session

Options uniquement du framework .NET

Ces mots-clés sont acceptés uniquement sur le cadre .NET. Sur .NET, le constructeur lance NotSupportedException et SqlConnection lance ArgumentException.

Mots-clés non pris en charge

Règles de validation

SqlConnectionStringBuilder Rejette des mots-clés inconnus et de nombreuses valeurs invalides lorsque vous les définissez. SqlConnectioneffectue plus de vérifications lorsque vous définissez sa chaîne de connexion, incluant des valeurs uniques acceptées par le constructeur et des combinaisons de mots-clés. Une chaîne acceptée par le constructeur peut toujours tomber en panne lorsque vous créez la connexion.

Le constructeur et la connexion rejettent ces valeurs avec ArgumentException:

• Connect Timeout, Command Timeout, Load Balance Timeout, Connection Idle Timeout, ou Min Pool Size moins que 0.
• Max Pool Size moins d’un.
• Packet Size à l’extérieur de 512 à 32 768.
• Connect Retry Count À l’extérieur de 0 à 255.
• Connect Retry Interval En dehors de 1 à 60.
• Un mot-clé qui ne figure pas dans cet article.

SqlConnection rejette également ces valeurs avec ArgumentException, même si le constructeur les accepte :

• Type System Version Autres que Latest, SQL Server 2012, SQL Server 2008, ou SQL Server 2005.
• Transaction Binding à part Implicit Unbind ou Explicit Unbind.
• Une valeur plus longue que la limite TDS pour Application Name, Current Language, Data Source, Failover Partner, Initial CatalogPassword, User ID, , Workstation ID, , ou AttachDBFilename.

SqlConnection rejette également ces combinaisons avec ArgumentException:

• Min Pool Size supérieur à Max Pool Size.
• Failover Partner sans Initial Catalog.
• Failover Partner avec Multi Subnet Failover=true, User Instance=trueou Application Intent=ReadOnly.
• Authentication avec Integrated Security=true.
• Password avec Active Directory Integrated, Active Directory Interactive, Active Directory Managed Identity, Active Directory MSI, Active Directory Default, ou Active Directory Workload Identity.
• User ID ou Password avec Active Directory Device Code Flow.

Modifications des options de révision

Avant de changer une option en production :

1. Enregistrez la chaîne de connexion actuelle, la version du pilote, le type de terminaison et le problème que vous résoudrez.
2. Changez une option à la fois.
3. Test de l’établissement de la connexion, de l’authentification, de la validation des certificats, du pool de connexions, du basculement, de l’annulation et de l’exécution des requêtes.
4. Mesurez la latence de connexion, les attentes du pool et les numéros d’erreur.
5. Confirmez le réglage sur chaque instance déployée.

Une chaîne de connexion modifiée crée un nouveau pool. Lors d’un déploiement par étapes, les anciens et nouveaux pools existent simultanément, ce qui permet d’augmenter le nombre total de connexions physiques au serveur.

Contenu connexe

• Chaînes de connexion
• Générateurs de chaînes de connexion
• Se connecter à une source de données
• Pooling de connexions SQL Server
• Chiffrement et validation de certificat