SqlConnectionStringBuilder Classe

Definizione

Spazio dei nomi:

Microsoft.Data.SqlClient

Assembly:

Microsoft.Data.SqlClient.dll

Pacchetto:

Microsoft.Data.SqlClient v7.1.0

Fornisce un modo semplice per creare e gestire il contenuto delle stringhe di connessione usate dalla 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

Ereditarietà

DbConnectionStringBuilder

SqlConnectionStringBuilder

Attributi

TypeConverterAttribute

Esempio

L'applicazione console seguente compila stringhe di connessione per un database di SQL Server. Il codice usa una SqlConnectionStringBuilder classe per creare il stringa di connessione e quindi passa la ConnectionString proprietà dell'istanza SqlConnectionStringBuilder al costruttore della classe di connessione. L'esempio analizza anche un stringa di connessione esistente e illustra vari modi per modificare il contenuto del stringa di connessione.

Note

Questo esempio include una password per illustrare come SqlConnectionStringBuilder funziona con le stringhe di connessione. Nelle applicazioni è consigliabile usare l'autenticazione di Windows. Se è necessario usare una password, non includere una password hardcoded nell'applicazione.

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

Commenti

Il generatore di stringhe di connessione consente agli sviluppatori di creare stringhe di connessione sintatticamente corrette e analizzare e ricompilare le stringhe di connessione esistenti usando proprietà e metodi della classe . Il generatore di stringhe di connessione fornisce proprietà fortemente tipizzate corrispondenti alle coppie chiave/valore note consentite da SQL Server. Gli sviluppatori che devono creare stringhe di connessione come parte delle applicazioni possono usare la SqlConnectionStringBuilder classe per compilare e modificare le stringhe di connessione. La classe semplifica anche la gestione delle stringhe di connessione archiviate in un file di configurazione dell'applicazione.

SqlConnectionStringBuilder esegue i controlli per le coppie chiave/valore valide. Pertanto, non è possibile usare questa classe per creare stringhe di connessione non valide; il tentativo di aggiungere coppie non valide genererà un'eccezione. La classe gestisce una raccolta fissa di sinonimi e può traslare da un sinonimo al nome di chiave noto corrispondente.

Ad esempio, quando si usa la proprietà Item per recuperare un valore, è possibile specificare una stringa contenente qualsiasi sinonimo per la chiave necessaria. Ad esempio, è possibile specificare "Indirizzo di rete", "addr" o qualsiasi altro sinonimo accettabile per questa chiave all'interno di un stringa di connessione quando si usa un membro che richiede una stringa contenente il nome della chiave, ad esempio la proprietà Item o il Remove metodo . Per un elenco completo dei sinonimi accettabili, vedere la proprietà ConnectionString.

Gli handle di proprietà Item tentano di inserire voci dannose. Ad esempio, il codice seguente, usando la proprietà Item predefinita (l'indicizzatore, in C#) esegue correttamente l'escape della coppia chiave/valore annidata:

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

Il risultato è la stringa di connessione seguente che gestisce il valore non valido in modo sicuro:

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";  
Integrated Security=True  

Costruttori

Nome	Descrizione
SqlConnectionStringBuilder()	Inizializza una nuova istanza della classe SqlConnectionStringBuilder.
SqlConnectionStringBuilder(String)	Inizializza una nuova istanza della classe SqlConnectionStringBuilder. La stringa di connessione fornita fornisce i dati per le informazioni di connessione interne dell'istanza.

Proprietà

Nome	Descrizione
ApplicationIntent	Dichiara il tipo di carico di lavoro dell'applicazione durante la connessione a un database in un gruppo di disponibilità di SQL Server. È possibile impostare il valore di questa proprietà con ApplicationIntent. Per ulteriori informazioni sul supporto di SqlClient per i gruppi di disponibilità Always On, vedere Supporto SqlClient per l'alta disponibilità e il ripristino di emergenza.
ApplicationName	Ottiene o imposta il nome dell'applicazione associata alla stringa di connessione.
AttachDBFilename	Ottiene o imposta una stringa contenente il nome del file di dati primario. Include il nome completo del percorso di un database collegabile.
AttestationProtocol	Ottiene o imposta il valore del protocollo di attestazione.
Authentication	Ottiene o imposta il metodo di autenticazione utilizzato per La connessione con Microsoft Entra per Azure SQL risorse.
ColumnEncryptionSetting	Ottiene o imposta le impostazioni di crittografia della colonna per il generatore di stringhe di connessione.
CommandTimeout	Tempo di attesa predefinito (in secondi) prima della conclusione del tentativo di esecuzione di un comando e della generazione di un errore. Il valore predefinito è 30 secondi.
ConnectionReset	Obsoleti. Obsoleto. Ottiene o imposta un valore booleano che indica se la connessione viene reimpostata quando viene disegnata dal pool di connessioni.
ConnectRetryCount	Numero di riconnessioni tentate dopo aver identificato che si è verificato un errore di connessione inattivo. Deve essere un numero intero compreso tra 0 e 255. Il valore predefinito per gli endpoint non Azure è 1. Per gli endpoint Azure SQL, il valore predefinito è 2. A partire dalla versione 5.x, per Azure SQL endpoint serverless o su richiesta, l'impostazione predefinita è 5 per migliorare l'esito positivo della connessione per le connessioni a un'istanza inattiva o sospesa. Impostare su 0 per disabilitare la riconnessione in caso di errori di connessione inattiva. Verrà generata un'eccezione ArgumentException se impostata su un valore esterno all'intervallo consentito.
ConnectRetryInterval	Intervallo di tempo (in secondi) tra ogni tentativo di riconnessione dopo l'identificazione di un errore di connessione inattivo. Deve essere un numero intero compreso tra 1 e 60. Il valore predefinito è 10 secondi.
ConnectTimeout	Ottiene o imposta l'intervallo di tempo , espresso in secondi, per attendere una connessione al server prima di terminare il tentativo e generare un errore.
CurrentLanguage	Ottiene o imposta la lingua utilizzata per i messaggi di errore o di avviso del server di database.
DataSource	Ottiene o imposta il nome o l'indirizzo di rete dell'istanza di SQL Server a cui connettersi.
EnclaveAttestationUrl	Ottiene o imposta l'URL di attestazione dell'enclave da usare con Always Encrypted basato sull'enclave.
Encrypt	Ottiene o imposta un SqlConnectionEncryptOption valore dalla versione 5.0 o un Boolean valore per le versioni precedenti che indica se la crittografia TLS è necessaria per tutti i dati inviati tra il client e il server.
Enlist	Ottiene o imposta un valore booleano che indica se il pool di connessioni SQL Server inserisce automaticamente la connessione nel contesto di transazione corrente del thread di creazione.
FailoverPartner	Ottiene o imposta il nome o l'indirizzo del server partner a cui connettersi se il server primario è inattivo.
FailoverPartnerSPN	Ottiene o imposta il nome dell'entità servizio (SPN) del partner di failover per la connessione.
HostNameInCertificate	Ottiene o imposta il nome host da utilizzare quando si convalida il certificato del server per la connessione. Se non specificato, il nome del server da Data Source viene usato per la convalida del certificato. (Disponibile solo nella versione 5.0+)
IdleTimeout	Ottiene o imposta il tempo massimo, espresso in secondi, in cui una connessione può rimanere inutilizzata (inattiva) nel pool di connessioni prima che venga rimossa. Il valore predefinito è 300 (5 minuti).
InitialCatalog	Ottiene o imposta il nome del database associato alla connessione.
IntegratedSecurity	Ottiene o imposta un valore booleano che indica se l'ID utente e la password vengono specificati nella connessione (quando false ) o se le credenziali dell'account Windows correnti vengono usate per l'autenticazione (quando true ).
IPAddressPreference	Ottiene o imposta la preferenza della famiglia di indirizzi IP quando si stabiliscono connessioni TCP.
IsFixedSize	Ottiene un valore che indica se ha SqlConnectionStringBuilder una dimensione fissa.
Item[String]	Ottiene o imposta il valore associato alla chiave specificata. In C# questa proprietà è l'indicizzatore.
Keys	Ottiene un ICollection che contiene le chiavi nel SqlConnectionStringBuilder.
LoadBalanceTimeout	Ottiene o imposta il tempo minimo, espresso in secondi, affinché la connessione sia attiva nel pool di connessioni prima di essere eliminata definitivamente.
MaxPoolSize	Ottiene o imposta il numero massimo di connessioni consentite nel pool di connessioni per questa stringa di connessione specifica.
MinPoolSize	Ottiene o imposta il numero minimo di connessioni consentite nel pool di connessioni per questa stringa di connessione specifica.
MultipleActiveResultSets	Se true, un'applicazione può mantenere più set di risultati attivi (MARS). Se false, un'applicazione deve elaborare o annullare tutti i set di risultati da un batch prima di poter eseguire qualsiasi altro batch in tale connessione. Per altre informazioni, vedere Multiple Active Result Sets (MARS).
MultiSubnetFailover	Se l'applicazione si connette a un gruppo di disponibilità AlwaysOn in subnet diverse, l'impostazione MultiSubnetFailover=true fornisce un rilevamento e una connessione più veloci al server attivo (attualmente). Per ulteriori informazioni sul supporto di SqlClient per i gruppi di disponibilità Always On, vedere Supporto SqlClient per l'alta disponibilità e il ripristino di emergenza.
NetworkLibrary	Ottiene o imposta una stringa contenente il nome della libreria di rete utilizzata per stabilire una connessione a SQL Server.
PacketSize	Ottiene o imposta le dimensioni in byte dei pacchetti di rete usati per comunicare con un'istanza di SQL Server.
Password	Ottiene o imposta la password per l'account di SQL Server.
PersistSecurityInfo	Ottiene o imposta un valore booleano che indica se le informazioni sensibili alla sicurezza, ad esempio la password o il token di accesso, devono essere restituite come parte del stringa di connessione in una connessione creata con questa SqlConnectionStringBuilder connessione dopo che tale connessione è mai stata aperta. Questa proprietà deve essere impostata true su solo se l'applicazione deve leggere la password da una connessione di database già aperta. Il valore predefinito di è l'impostazione più sicura. L'uso false di true per questa proprietà consente di aprire l'applicazione a rischi per la sicurezza, ad esempio la registrazione accidentale o la traccia della password del database.
PoolBlockingPeriod	Comportamento del periodo di blocco per un pool di connessioni.
Pooling	Ottiene o imposta un valore booleano che indica se la connessione verrà inserita in pool o aperta in modo esplicito ogni volta che viene richiesta la connessione.
Replication	Ottiene o imposta un valore booleano che indica se la replica è supportata tramite la connessione.
ServerCertificate	Ottiene o imposta il percorso di un file di certificato in modo che corrisponda al SQL Server certificato TLS/SSL per la connessione. I formati di certificato accettati sono PEM, DER e CER. Se specificato, il certificato SQL Server viene controllato verificando se l'oggetto ServerCertificate specificato è una corrispondenza esatta. (Disponibile solo nella versione 5.1+)
ServerSPN	Ottiene o imposta il nome dell'entità servizio (SPN) dell'origine dati.
TransactionBinding	Ottiene o imposta un valore stringa che indica come la connessione mantiene l'associazione a una transazione System.Transactions inclusa nell'elenco.
TransparentNetworkIPResolution	Obsoleti. In .NET Framework, quando il valore di questa chiave è impostato su true, il driver esegue più round di connessione tra gli indirizzi IP risolti dns, con timeout per tentativi progressivamente più grandi e un minimo di 500 ms nel tentativo in modalità sequenziale, fino a quando non viene raggiunta una connessione o il Connect Timeout totale viene raggiunto.
TrustServerCertificate	Ottiene o imposta un valore che indica se il canale verrà crittografato ignorando l'esecuzione della catena di certificati per convalidare l'attendibilità.
TypeSystemVersion	Ottiene o imposta un valore stringa che indica il sistema di tipi previsto dall'applicazione.
UserID	Ottiene o imposta l'ID utente da utilizzare per la connessione a SQL Server.
UserInstance	Ottiene o imposta un valore che indica se reindirizzare la connessione dall'istanza predefinita di SQL Server Express a un'istanza avviata dal runtime in esecuzione con l'account del chiamante.
Values	Ottiene un oggetto ICollection che contiene i valori nell'oggetto SqlConnectionStringBuilder .
WorkstationID	Ottiene o imposta il nome della workstation che si connette a SQL Server.

Metodi

Nome	Descrizione
Clear()	Cancella il contenuto dell'istanza SqlConnectionStringBuilder .
ContainsKey(String)	Determina se il SqlConnectionStringBuilder contiene una chiave specifica.
Remove(String)	Rimuove la voce con la chiave specificata dall'istanza di SqlConnectionStringBuilder.
ShouldSerialize(String)	Indica se la chiave specificata esiste in questa istanza di SqlConnectionStringBuilder.
TryGetValue(String, Object)	Recupera un valore corrispondente alla chiave fornita da questo SqlConnectionStringBuilder oggetto .