SqlConnectionStringBuilder Clase
Definición
Importante
Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.
Proporciona una manera sencilla de crear y administrar el contenido de las cadenas de conexión usadas por la clase 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- Herencia
-
SqlConnectionStringBuilder
- Atributos
Ejemplos
La siguiente aplicación de consola compila cadenas de conexión para una base de datos de SQL Server. El código usa una SqlConnectionStringBuilder clase para crear el cadena de conexión y, a continuación, pasa la ConnectionString propiedad de la SqlConnectionStringBuilder instancia al constructor de la clase de conexión. En el ejemplo también se analiza un cadena de conexión existente y se muestran varias formas de manipular el contenido del cadena de conexión.
Note
En este ejemplo se incluye una contraseña para demostrar cómo SqlConnectionStringBuilder funciona con cadenas de conexión. En las aplicaciones, se recomienda usar la autenticación de Windows. Si debe usar una contraseña, no incluya una contraseña codificada de forma rígida en la aplicación.
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";
}
}
Comentarios
El generador de cadenas de conexión permite a los desarrolladores crear mediante programación cadenas de conexión sintácticas correctas y analizar y recompilar las cadenas de conexión existentes mediante propiedades y métodos de la clase . El generador de cadenas de conexión proporciona propiedades fuertemente tipadas correspondientes a los pares clave-valor conocidos permitidos por SQL Server. Los desarrolladores que necesitan crear cadenas de conexión como parte de las aplicaciones pueden usar la SqlConnectionStringBuilder clase para compilar y modificar cadenas de conexión. La clase también facilita la administración de cadenas de conexión almacenadas en un archivo de configuración de aplicación.
SqlConnectionStringBuilder Realiza comprobaciones de pares clave-valor válidos. Por lo tanto, no puede usar esta clase para crear cadenas de conexión no válidas; si intenta agregar pares no válidos, se producirá una excepción. La clase mantiene una colección fija de sinónimos y puede traducirse de un sinónimo al nombre de clave conocido correspondiente.
Por ejemplo, al usar la propiedad Item para recuperar un valor, puede especificar una cadena que contenga cualquier sinónimo de la clave que necesite. Por ejemplo, puede especificar "Dirección de red", "addr" o cualquier otro sinónimo aceptable para esta clave dentro de un cadena de conexión cuando use cualquier miembro que requiera una cadena que contenga el nombre de clave, como la propiedad Item o el Remove método . Consulte la propiedad ConnectionString para obtener una lista completa de sinónimos aceptables.
La propiedad Item intenta insertar entradas malintencionadas. Por ejemplo, el código siguiente, con la propiedad Item predeterminada (el indizador, en C#) escapa correctamente al par clave-valor anidado:
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);
El resultado es la siguiente cadena de conexión que controla el valor no válido de forma segura:
Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";
Integrated Security=True
Constructores
| Nombre | Description |
|---|---|
| SqlConnectionStringBuilder() |
Inicializa una nueva instancia de la clase SqlConnectionStringBuilder. |
| SqlConnectionStringBuilder(String) |
Inicializa una nueva instancia de la clase SqlConnectionStringBuilder. La cadena de conexión proporcionada proporciona los datos para la información de conexión interna de la instancia. |
Propiedades
| Nombre | Description |
|---|---|
| ApplicationIntent |
Declara el tipo de carga de trabajo de aplicación al conectarse a una base de datos en un grupo de disponibilidad de SQL Server. Puede establecer el valor de esta propiedad con ApplicationIntent. Para obtener más información sobre la compatibilidad de SqlClient con Always On Availability Groups, consulte Compatibilidad de SqlClient para Alta Disponibilidad y Recuperación ante Desastres. |
| ApplicationName |
Obtiene o establece el nombre de la aplicación asociada a la cadena de conexión. |
| AsynchronousProcessing |
Obsoletos.
Obsoleto. Obtiene o establece un valor booleano que indica si la conexión creada mediante esta cadena de conexión permite el procesamiento asincrónico. |
| AttachDBFilename |
Obtiene o establece una cadena que contiene el nombre del archivo de datos principal. Esto incluye el nombre de ruta de acceso completo de una base de datos adjuntable. |
| AttestationProtocol |
Obtiene o establece el valor del Protocolo de atestación. |
| Authentication |
Obtiene o establece el método de autenticación usado para Conectar con Microsoft Entra para Azure SQL recursos. |
| ColumnEncryptionSetting |
Obtiene o establece la configuración de cifrado de columnas para el generador de cadenas de conexión. |
| CommandTimeout |
Tiempo de espera predeterminado (en segundos) antes de terminar el intento de ejecutar un comando y generar un error. El valor predeterminado es 30 segundos. |
| ConnectionReset |
Obsoletos.
Obsoletos.
Obsoleto. Obtiene o establece un valor booleano que indica si la conexión se restablece cuando se extrae del grupo de conexiones. |
| ConnectRetryCount |
Número de reconexión que se intentó después de identificar que se produjo un error de conexión inactiva. Debe ser un entero entre 0 y 255. El valor predeterminado para los puntos de conexión que no son Azure es 1. Para los puntos de conexión de Azure SQL, el valor predeterminado es 2. A partir de la versión 5.x, para Azure SQL puntos de conexión sin servidor o a petición, el valor predeterminado es 5 para mejorar el éxito de la conexión para las conexiones a una instancia inactiva o en pausa. Establézcalo en 0 para deshabilitar la reconexión en los errores de conexión inactivos. ArgumentException Se producirá una excepción si se establece en un valor fuera del intervalo permitido. |
| ConnectRetryInterval |
Cantidad de tiempo (en segundos) entre cada intento de reconexión después de identificar que se produjo un error de conexión inactiva. Debe ser un entero entre 1 y 60. El valor predeterminado es 10 segundos. |
| ConnectTimeout |
Obtiene o establece el período de tiempo (en segundos) para esperar una conexión al servidor antes de finalizar el intento y generar un error. |
| ContextConnection |
Obsoletos.
Obsoleto. Obtiene o establece un valor que indica si se debe realizar una conexión de cliente o servidor en proceso a SQL Server. |
| CurrentLanguage |
Obtiene o establece el idioma usado para los mensajes de error o advertencia del servidor de bases de datos. |
| DataSource |
Obtiene o establece el nombre o la dirección de red de la instancia de SQL Server a la que se va a conectar. |
| EnclaveAttestationUrl |
Obtiene o establece la dirección URL de atestación del enclave que se va a usar con Always Encrypted basado en enclave. |
| Encrypt |
Obtiene o establece un SqlConnectionEncryptOption valor desde la versión 5.0 o un Boolean valor para las versiones anteriores que indica si se requiere cifrado TLS para todos los datos enviados entre el cliente y el servidor. |
| Enlist |
Obtiene o establece un valor booleano que indica si el grupo de conexiones de SQL Server incluye automáticamente la conexión en el contexto de transacción actual del subproceso de creación. |
| FailoverPartner |
Obtiene o establece el nombre o la dirección del servidor asociado al que se va a conectar si el servidor principal está inactivo. |
| FailoverPartnerSPN |
Obtiene o establece el nombre de entidad de seguridad de servicio (SPN) del asociado de conmutación por error para la conexión. |
| HostNameInCertificate |
Obtiene o establece el nombre de host que se va a usar al validar el certificado de servidor para la conexión. Cuando no se especifica, el nombre del servidor de |
| IdleTimeout |
Obtiene o establece el tiempo máximo, en segundos, que una conexión puede estar sin usar (inactiva) en el grupo de conexiones antes de descartarla. El valor predeterminado es 300 (5 minutos). |
| InitialCatalog |
Obtiene o establece el nombre de la base de datos asociada a la conexión. |
| IntegratedSecurity |
Obtiene o establece un valor booleano que indica si el identificador de usuario y la contraseña se especifican en la conexión (cuando |
| IPAddressPreference |
Obtiene o establece la preferencia de familia de direcciones IP al establecer conexiones TCP. |
| IsFixedSize |
Obtiene un valor que indica si SqlConnectionStringBuilder tiene un tamaño fijo. |
| Item[String] |
Obtiene o establece el valor asociado a la clave especificada. En C#, esta propiedad es el indexador. |
| Keys |
Obtiene un ICollection objeto que contiene las claves de .SqlConnectionStringBuilder |
| LoadBalanceTimeout |
Obtiene o establece el tiempo mínimo, en segundos, para que la conexión resida en el grupo de conexiones antes de destruirse. |
| MaxPoolSize |
Obtiene o establece el número máximo de conexiones permitidas en el grupo de conexiones para esta cadena de conexión específica. |
| MinPoolSize |
Obtiene o establece el número mínimo de conexiones permitidas en el grupo de conexiones para esta cadena de conexión específica. |
| MultipleActiveResultSets |
Cuando es true, una aplicación puede mantener varios conjuntos de resultados activos (MARS). Cuando es false, una aplicación debe procesar o cancelar todos los conjuntos de resultados de un lote antes de poder ejecutar cualquier otro lote en esa conexión. Para obtener más información, consulte Conjuntos de resultados activos múltiples (MARS). |
| MultiSubnetFailover |
Si la aplicación se conecta a un grupo de disponibilidad AlwaysOn (AG) en diferentes subredes, la configuración |
| NetworkLibrary |
Obtiene o establece una cadena que contiene el nombre de la biblioteca de red utilizada para establecer una conexión con SQL Server. |
| PacketSize |
Obtiene o establece el tamaño en bytes de los paquetes de red usados para comunicarse con una instancia de SQL Server. |
| Password |
Obtiene o establece la contraseña de la cuenta de SQL Server. |
| PersistSecurityInfo |
Obtiene o establece un valor booleano que indica si la información confidencial de seguridad, como la contraseña o el token de acceso, se debe devolver como parte del cadena de conexión en una conexión creada con esta SqlConnectionStringBuilder después de que esa conexión haya estado en estado abierto. Esta propiedad solo debe establecerse |
| PoolBlockingPeriod |
Comportamiento del período de bloqueo de un grupo de conexiones. |
| Pooling |
Obtiene o establece un valor booleano que indica si la conexión se agrupará o se abrirá explícitamente cada vez que se solicite la conexión. |
| Replication |
Obtiene o establece un valor booleano que indica si se admite la replicación mediante la conexión. |
| ServerCertificate |
Obtiene o establece la ruta de acceso a un archivo de certificado que debe coincidir con el certificado TLS/SSL de SQL Server para la conexión. Los formatos de certificado permitidos son PEM, DER y CER. Si se especifica, el certificado de SQL Server se comprueba comprobando si el |
| ServerSPN |
Obtiene o establece el nombre de entidad de seguridad de servicio (SPN) del origen de datos. |
| TransactionBinding |
Obtiene o establece un valor de cadena que indica cómo la conexión mantiene su asociación con una transacción enlistada |
| TransparentNetworkIPResolution |
Obsoletos.
En .NET Framework, cuando el valor de esta clave se establece |
| TrustServerCertificate |
Obtiene o establece un valor que indica si el canal se cifrará mientras se pasa el recorrido de la cadena de certificados para validar la confianza. |
| TypeSystemVersion |
Obtiene o establece un valor de cadena que indica el sistema de tipos que espera la aplicación. |
| UserID |
Obtiene o establece el identificador de usuario que se va a usar al conectarse a SQL Server. |
| UserInstance |
Obtiene o establece un valor que indica si se va a redirigir la conexión desde la instancia predeterminada de SQL Server Express a una instancia iniciada por el entorno de ejecución que se ejecuta en la cuenta del autor de la llamada. |
| Values |
Obtiene un ICollection objeto que contiene los valores de .SqlConnectionStringBuilder |
| WorkstationID |
Obtiene o establece el nombre de la estación de trabajo que se conecta a SQL Server. |
Métodos
| Nombre | Description |
|---|---|
| Clear() |
Borra el contenido de la SqlConnectionStringBuilder instancia. |
| ContainsKey(String) |
Determina si contiene SqlConnectionStringBuilder una clave específica. |
| Remove(String) |
Quita la entrada con la clave especificada de la instancia de SqlConnectionStringBuilder. |
| ShouldSerialize(String) |
Indica si la clave especificada existe en esta instancia de SqlConnectionStringBuilder. |
| TryGetValue(String, Object) |
Recupera un valor correspondiente a la clave proporcionada de este SqlConnectionStringBuilder . |