Opzioni di connessione per Microsoft. Data.SqlClient

Questo articolo elenca tutte le parole chiave stringa di connessione che Microsoft. Data.SqlClient accetta. Ogni parola chiave ha anche una proprietà corrispondente SqlConnectionStringBuilder . Per un'introduzione, i pattern comuni e le regole di parsing, vedi Stringhe di connessione.

Le parole chiave e gli alias non sono sensibili alla maiuscolagem. Quando imposti un valore tramite una proprietà costruttore, il costruttore scrive la parola chiave canonica nella colonna Parola Chiave .

Impostare le opzioni con SqlConnectionStringBuilder

Parti da una stringa di connessione base che contiene server, database e impostazioni di autenticazione. Poi imposta opzioni specifiche per carico di lavoro tramite le proprietà del costruttore. Le schede del framework .NET utilizzano C# 7.3. Per creare un progetto che esegue i campioni, vedi Crea il progetto.

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

L'output è il seguente:

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

Un nuovo SqlCommand prende il suo timeout predefinito dalla Command Timeout parola chiave della sua connessione.

Controlla i valori predefiniti

Un nuovo SqlConnectionStringBuilder riporta il valore predefinito per ogni opzione. Questo programma stampa i valori predefiniti che la maggior parte delle applicazioni esamina:

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

Su .NET, l'output è:

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 è l'opzione Mandatory . Su .NET Framework, il nome predefinito dell'applicazione è Framework Microsoft SqlClient provider di dati.

Opzioni server e database

Opzioni di identità applicativa

Per segnalare quale framework o strumento ha aperto una connessione, usa la RegisteredApplication proprietà. Non ha una parola chiave di stringa di connessione. Per ulteriori informazioni, vedi Segnala l'identità dell'applicazione.

Opzioni di autenticazione

Authentication accetta questi valori. Il costruttore le scrive senza spazi, come ActiveDirectoryDefault, e l'analizzatore accetta entrambe le forme.

I metodi Microsoft Entra ID necessitano del Microsoft.Data.SqlClient.Extensions.Azure pacchetto. Per configurazione ed esempi, vedi Microsoft Entra ID autenticazione e SQL Server autenticazione.

Opzioni di crittografia

Per le regole complete di validazione, vedi Crittografia e validazione dei certificati.

Opzioni sempre criptate

Opzioni di rete

Un interruttore AppContext a livello di processo può cambiare il Multi Subnet Failover valore predefinito in true. Per ulteriori informazioni, consulta gli interruttori AppContext in SqlClient.

Opzioni di timeout

Connect Timeout Non limita l'esecuzione delle query. Command Timeout Non limita il login né l'attesa per una connessione in pool. Passa a CancellationToken chiamate asincrone così il chiamante può smettere di aspettare prima che scada uno dei timeout.

Opzioni di recupero della connessione

Quando Connect Retry Count è 1, che è il valore predefinito, il driver lo utilizza 2 per gli endpoint Azure SQL e 5 per gli endpoint serverless SQL pool di Azure Synapse Analytics quando ripristina una connessione idle rotta. La prima apertura usa il valore impostato, quindi il predefinito consente un solo retry su ogni endpoint. Il driver utilizza qualsiasi altro valore impostato in entrambi i casi.

Queste parole chiave non riprovano un comando che fallisce mentre è in esecuzione. Per saltare il retry integrato per un aperto, chiami un Open sovraccarico con OpenWithoutRetry. Per le policy personalizzate, vedi Logica di ritenti configurabile. Riprova un comando solo quando ripeterlo è sicuro.

Opzioni di aggregazione

Ogni distinta stringa di connessione ha il proprio pool. Per chiavi del pool, cancellamento e tempo di inattività, vedi SQL Server connection pooling.

Opzioni di transazione e sessione

Opzioni solo per framework .NET

Queste parole chiave sono accettate solo su .NET Framework. Su .NET, il costruttore lancia NotSupportedException e SqlConnection lancia ArgumentException.

Parole chiave non supportate

Regole di convalida

SqlConnectionStringBuilder Rifiuta parole chiave sconosciute e molti valori non validi quando li imposti. SqlConnectionEffettua più controlli quando imposti la sua stringa di connessione, inclusi valori singoli accettati dal builder e combinazioni di parole chiave. Una stringa accettata dal costruttore può comunque guastarsi quando crei la connessione.

Il costruttore e la connessione rifiutano questi valori con ArgumentException:

• Connect Timeout, Command Timeout, Load Balance Timeout, Connection Idle Timeout, o Min Pool Size meno di 0.
• Max Pool Size meno di 1.
• Packet Size al di fuori da 512 a 32.768.
• Connect Retry Count fuori da 0 a 255.
• Connect Retry Interval fuori da 1 a 60.
• Una parola chiave che non è presente in questo articolo.

SqlConnection Rifiuta anche questi valori con ArgumentException, anche se il costruttore li accetta:

• Type System Version Diverso da Latest, SQL Server 2012, SQL Server 2008, o SQL Server 2005.
• Transaction Binding a parte Implicit Unbind o Explicit Unbind.
• Un valore più lungo del limite TDS per Application Name, Current Language, Data Source, Failover Partner, Initial Catalog, PasswordUser ID, Workstation ID, , o AttachDBFilename.

SqlConnection rifiuta anche queste combinazioni con ArgumentException:

• Min Pool Size maggiore di Max Pool Size.
• Failover Partner senza Initial Catalog.
• Failover Partner con Multi Subnet Failover=true, User Instance=true, oppure Application Intent=ReadOnly.
• Authentication con Integrated Security=true.
• Passwordcon , , , , , Active Directory Default, o Active Directory Workload Identity. Active Directory MSIActive Directory Managed IdentityActive Directory InteractiveActive Directory Integrated
• User ID oppure Password con Active Directory Device Code Flow.

Cambiamenti nelle opzioni di revisione

Prima di cambiare un'opzione in produzione:

1. Registra la stringa di connessione corrente, la versione del driver, il tipo di endpoint e il problema che stai risolvendo.
2. Cambia un'opzione alla volta.
3. Test dello stabilimento della connessione, dell'autenticazione, della convalida dei certificati, del pooling, del failover, dell'annullamento e dell'esecuzione delle query.
4. Misura la latenza di connessione, le attese del pool e i numeri di errore.
5. Conferma l'impostazione su ogni istanza distribuita.

Una stringa di connessione modificata crea un nuovo pool. Durante un rollout a tappe, pool vecchi e nuovi esistono contemporaneamente, quindi il numero totale di connessioni fisiche al server può aumentare.

Contenuti correlati

• Stringhe di connessione
• Generatori di stringhe di connessione
• Connessione a un'origine dati
• Pooling di connessioni SQL Server
• Crittografia e convalida di certificati