SqlConnectionStringBuilder Classe
Definizione
Importante
Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.
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.DbConnectionStringBuilderpublic sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
inherit DbConnectionStringBuildertype SqlConnectionStringBuilder = class
inherit DbConnectionStringBuilderPublic NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder- Ereditarietà
-
SqlConnectionStringBuilder
- Attributi
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. |
| AsynchronousProcessing |
Obsoleti.
Obsoleto. Ottiene o imposta un valore booleano che indica se l'elaborazione asincrona è consentita dalla connessione creata tramite questa 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.
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. |
| ContextConnection |
Obsoleti.
Obsoleto. Ottiene o imposta un valore che indica se deve essere effettuata una connessione client/server o in-process a SQL Server. |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| TransparentNetworkIPResolution |
Obsoleti.
In .NET Framework, quando il valore di questa chiave è impostato su |
| 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 . |