Stringhe di connessione per Microsoft. Data.SqlClient

Una stringa di connessione Microsoft.Data.SqlClient è un elenco di keyword=value coppie chiave/valore separate da punti e virgola. Passalo a SqlConnection oppure a SqlConnectionStringBuilder:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

Una stringa di connessione risponde a quattro domande:

1. Quale server e database utilizza l'applicazione?
2. Quale identità usa l'applicazione?
3. Come fa il client a convalidare il certificato server?
4. Quale comportamento di connessione richiede il carico di lavoro?

Questo articolo tratta queste scelte e le regole che il conducente utilizza per leggere il testo. Per ogni parola chiave, i suoi sinonimi e il suo valore predefinito, vedi Opzioni di Connessione. Per creare e modificare stringhe di connessione nel codice, vedi Connection string builders.

Scegli un modello di autenticazione

Usa il modello che si adatta alla distribuzione. Sostituisci ogni segnaposto, come <server>, con il tuo valore.

L'autenticazione integrata di Windows si collega come identità del processo. Per un'applicazione desktop o console, di solito si tratta dell'utente connesso. Per un'applicazione web o un servizio Windows, si tratta del pool di applicazioni o dell'account servizio. L'impersonazione può cambiare l'identità. Concedi un accesso e permessi di database all'identità che la tua applicazione effettivamente utilizza.

Queste tre forme di autenticazione integrata Windows sono equivalenti:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

Se una stringa imposta Integrated Security=true e imposta anche User ID e Password, il driver utilizza l'autenticazione di Windows e ignora nome utente e password.

Microsoft. Data.SqlClient 7.0 e versioni successive necessitano del pacchetto abbinato Microsoft.Data.SqlClient.Extensions.Azure alla versione per i metodi di autenticazione Microsoft Entra ID forniti dal driver. Non serve quel pacchetto quando il codice applicativo fornisce un token di accesso o un callback di token di accesso.

Per i valori accettati Authentication , vedi Opzioni di autenticazione. L'autenticazione richiede anche utenti del database, permessi e configurazione dell'identità sul server. Per i passaggi di configurazione, consulta l'autenticazione Microsoft Entra ID e l'autenticazione SQL Server.

Specifica il server e il database

Server e Database sono i nomi chiave più leggibili. Il costruttore li scrive come equivalenti canonici, Data Source e Initial Catalog. Tutti e quattro i nomi funzionano in una stringa di connessione.

Impostato Server su una di queste forme:

Usa tcp:, un nome host completamente qualificato e una porta esplicita in produzione. Usa un nome DNS che corrisponda al certificato del server, non un indirizzo IP, perché la validazione del certificato confronta il nome del server nella stringa di connessione con i nomi nel certificato.

Quando ti connetti a database SQL di Azure con autenticazione SQL e un nome utente nel modulo user@servername, la servername parte deve corrispondere al server in Server.

Per un listener di gruppo di disponibilità o un'istanza di cluster di failover, verifica Multi Subnet Failover anche le opzioni Connection.

Configurare crittografia e validazione dei certificati

La Encrypt parola chiave accetta i seguenti valori, indipendentemente da maiuscole e minuscole:

Da utilizzare Strict quando il server supporta TDS 8.0 e possiede un certificato che il client può validare. database SQL di Azure e SQL Database in Microsoft Fabric lo supportano. Una connessione LocalDB non è criptata, nemmeno con Mandatory, e Strict fallisce.

I valori Encrypt e Trust Server Certificate si combinano come segue:

Non impostare Trust Server Certificate=true per risolvere un errore di connessione in produzione. Crittografa il canale ma non conferma l'identità del server. Limitalo agli ambienti di sviluppo in cui non è disponibile un certificato affidabile.

Quando il nome del server in Data Source non corrisponde al certificato, imposta Host Name In Certificate sul nome nel certificato. SqlClient lo controlla solo quando il nome del server non corrisponde e non effettua il pinning di un certificato. Per accettare un solo certificato specifico, imposta Server Certificate sul percorso di un file PEM, DER o CER:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

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

Utilizzare un pool di connessioni

Il pooling è attivo di default. Quando apri un SqlConnection, il driver prende una connessione fisica da un pool compatibile con quella connessione. Quando chiudi o rilasci la connessione, la connessione fisica ritorna al pool invece di chiudersi. Un'apertura da pool salta la connessione di rete, la negoziazione TLS e l'autenticazione.

Segui queste regole:

• Apri una connessione poco prima di averne bisogno e chiudila appena finisci, con using o await using. Una connessione che non viene rilasciata rimane assegnata, e il pool può esaurirsi.

• Costruisci la stringa di connessione una volta all'avvio e riutilizzala. La chiave del pool include il testo esatto della stringa di connessione, quindi un ordine di parola chiave diverso, un sinonimo o un valore per richiesta come un ID richiesta o un nome utente crea un pool separato. Il costruttore scrive una forma canonica. Per maggiori informazioni, vedi Mantieni un'unica stringa di connessione canonica.

• Aspettati un pool separato per ogni identità Windows con autenticazione integrata, ogni SqlCredential istanza e ogni AccessToken valore. Usa un metodo fornito Authentication dal driver o uno riutilizzato AccessTokenCallback invece di impostare AccessToken su ogni connessione.

• Cerca connessioni che non sono eliminate prima che tu aumenti Max Pool Size, che di default è 100. Quando ogni connessione in un pool è in uso, Open attende fino a Connect Timeout e poi lancia InvalidOperationException:

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• Pianifica la capacità dei server per ogni pool. Ogni processo, o ogni dominio applicativo su .NET Framework, ha i propri pool. Le connessioni al server possono raggiungere Max Pool Size moltiplicate per i pool in ciascun processo e per il numero di istanze applicative.

• Non impostare Pooling=false per aggirare un problema di pooling. Ogni apertura effettua poi un login completo.

Per chiudere le connessioni in pool che restano inattive troppo a lungo, vedi Limita il tempo di inattività della connessione. Per le chiavi del pool, il dimensionamento, la cancellazione e le transazioni, vedere SQL Server connection pooling.

Impostazioni di connessione e comandi separate

Una stringa di connessione controlla l'istituzione della connessione e il comportamento della sessione. Un comando controlla un'operazione SQL.

Un timeout più lungo non equivale a una logica di retry. Un timeout limita una singola attesa. Un ritentativo dà inizio a un altro tentativo, e deve essere limitato e ripetibile in sicurezza.

Segnala l'identità dell'applicazione

Application Name imposta il nome che il server segnala tramite APP_NAME(). Usa un nome stabile per ogni carico di lavoro distribuito. I framework e gli strumenti che aprono connessioni per un'applicazione possono anche segnalarsi tramite la proprietà RegisteredApplication, che non ha una parola chiave della stringa di connessione. Per ulteriori informazioni, vedi Segnala l'identità dell'applicazione.

Costruire stringhe di connessione in sicurezza

Usalo SqlConnectionStringBuilder quando il codice aggiunge o cambia un valore. Non unire testo non affidabile a una stringa di connessione, perché un punto e virgola in quel testo può aggiungere o sostituire una parola chiave. Il builder valida i valori, mappa sinonimi con parole chiave canoniche e cita ogni valore in modo che il valore non possa aggiungere parole chiave. Per esempi, vedi Connection string builders.

Memorizza le informazioni di connessione al di fuori del codice

Carica le stringhe di connessione dal sistema di configurazione dell'applicazione. Le applicazioni .NET utilizzano comunemente variabili di ambiente, segreti utente per lo sviluppo locale, Configurazione app di Azure e Azure Key Vault.

Segui queste regole:

• Non eseguire il commit di password, segreti del client, token di accesso o stringhe di connessione dell'ambiente di produzione.
• Preferisci un metodo di autenticazione che non richieda una password nella stringa di connessione.
• Limita l'accesso alla sorgente di configurazione.
• Ruota le credenziali archiviate e riavvia o aggiorna le applicazioni che le memorizzano nella cache.
• Non scrivere stringhe di connessione in log, eccezioni, tracce o telemetria.
• Lascia Persist Security Info=false, il valore predefinito, così una connessione aperta non espone la password tramite la sua ConnectionString proprietà.

Per i provider di configurazione .NET, vedi Configurazione in .NET. Per ulteriori opzioni, consulta Proteggere le informazioni di connessione.

Regole di parsing

Il conducente applica queste regole:

• Le parole chiave non fanno distinzione tra maiuscole e minuscole. DATABASE, Database, e database sono la stessa parola chiave.
• Molte parole chiave hanno sinonimi. Server e Data Source impostano lo stesso valore. L'articolo Opzioni di connessione elenca i sinonimi per ogni parola chiave.
• Quando una parola chiave appare più di una volta, vince l'ultimo valore. I sinonimi contano come la stessa parola chiave.
• Il driver ignora gli spazi intorno alle parole chiave e ai valori non citati.
• Un punto e virgola finale è opzionale.
• Una parola chiave che il driver non riconosce genera ArgumentException con il messaggio Keyword not supported.

I valori possono essere sensibili a maiuscole, a seconda della parola chiave. Una password fa distinzione tra maiuscole e minuscole. Encrypt=STRICT e Encrypt=strict sono uguali.

Questo programma mostra come il builder normalizza le parole chiave, risolve un duplicato e cita caratteri speciali. La scheda .NET Framework utilizza C# 7.3. Per creare un progetto che esegue i campioni, vedi Crea il progetto.

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

L'output è il seguente:

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

La prima riga mostra ogni sinonimo sostituito dalla sua parola chiave canonica: timeout con Connect Timeout, User ID con uid, Initial Catalog con DATABASE e Data Source con server.

Valori dei preventivi

Racchiudi un valore tra virgolette doppie (") o virgolette singole (') quando contiene un punto e virgola, inizia o termina con uno spazio, o inizia o termina con una virgoletta. All'interno di un valore citato, scrivi due volte la virgoletta di delimitazione.

Le regole delle virgolette sono facili da sbagliare. Stabilisci i valori tramite le proprietà SqlConnectionStringBuilder e lascia che il costruttore li racchiuda tra virgolette. Per maggiori informazioni, vedi Creare stringhe di connessione in modo sicuro.

Specificare i valori booleani

Le parole chiave che assumono un valore booleano accettano true, false, yes e no, indipendentemente da maiuscole e minuscole. Integrated Security accetta sspianche , il che significa true. Il costruttore scrive True o False.

Usa parole chiave di altri driver

Microsoft. Data.SqlClient non accetta parole chiave ODBC o OLE DB come Driver e Provider. Rimuovi queste parole chiave quando sposti una stringa di connessione da un altro driver. System.Data.SqlClientLe stringhe di connessione funzionano in Microsoft.Data.SqlClient, con queste differenze:

• Encrypt è predefinito in Mandatory Microsoft.Data.SqlClient. Un server senza un certificato affidabile non supera la convalida del certificato. Installa un certificato affidabile sul server.
• Su .NET, Network Library, Connection Reset, e Transparent Network IP Resolution non sono supportati. Rimuoverli.
• Context Connection=true non è supportata.
• Asynchronous Processing non è una parola chiave supportata e lancia ArgumentException. Rimuoverlo. I metodi asincroni funzionano senza.
• Type System Version=SQL Server 2000 non è supportata. Creare la connessione genera ArgumentException. Usa Latest, SQL Server 2012, SQL Server 2008, o SQL Server 2005.

Contenuti correlati

• Usa Microsoft.Data.SqlClient in un'app .NET
• Opzioni di connessione
• Generatori di stringhe di connessione
• Connessione a un'origine dati
• Pooling di connessioni SQL Server
• Autenticazione Microsoft Entra ID
• Crittografia e convalida di certificati
• Istanze utente di SQL Server Express
• Ciclo di vita del supporto per il driver SqlClient