SqlConnectionStringBuilder Clase

Definición

Espacio de nombres:

System.Data.SqlClient

Ensamblado:

System.Data.SqlClient.dll

Paquete:

System.Data.SqlClient v4.8.6

Proporciona una manera simple de crear y administrar el contenido de las cadenas de conexión que utiliza la clase SqlConnection.

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder

public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

Herencia

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

Ejemplos

La siguiente aplicación de consola compila cadenas de conexión para una base de datos de SQL Server. El código utiliza una clase SqlConnectionStringBuilder para crear la cadena de conexión y, a continuación, envía la propiedad ConnectionString de la instancia SqlConnectionStringBuilder al constructor de la clase de conexión. El ejemplo analiza también una cadena de conexión existente y muestra distintas maneras de manipular el contenido de las cadenas de conexión.

Nota

Este ejempo incluye una contraseña para demostrar cómo SqlConnectionStringBuilder funciona con cadenas de conexión. Se recomienda que utilice autenticación de Windows en sus aplicaciones. Si necesita utilizar una contraseña en su aplicación, no incluya una contraseña codificada de forma rígida.

using System.Data;
using System.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= a!Pass113;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "new@1Password";
        builder.AsynchronousProcessing = true;

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

Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As 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=a!Pass113;initial catalog=AdventureWorks"
        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine(builder.Password)
        builder.Password = "new@1Password"
        builder.AsynchronousProcessing = True

        ' 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

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine(builder.ConnectionString)

        Console.WriteLine("Press Enter to finish.")
        Console.ReadLine()
    End Sub

    Private Function GetConnectionString() As String
        ' 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"
    End Function
End Module

Comentarios

El generador de cadenas de conexión permite a los programadores crear mediante programación cadenas de conexión sintácticamente correctas, y analizar y volver a generar cadenas de conexión existentes, utilizando las propiedades y los métodos de la clase. El generador de cadenas de conexión proporciona propiedades fuertemente tipadas que corresponden a los pares palabra clave-valor conocidos permitidos por SQL Server. Los programadores que tengan que crear cadenas de conexión como parte de las aplicaciones pueden utilizar la clase SqlConnectionStringBuilder para generarlas y modificarlas. La clase facilita también la administración de cadenas de conexión almacenadas en el archivo de configuración de una aplicación.

La clase SqlConnectionStringBuilder realiza comprobaciones para detectar si los pares palabra clave-valor son válidos. Por consiguiente, no es posible crear cadenas de conexión no válidas utilizando esta clase; el intento de agregar pares inválidos iniciará una excepción. La clase mantiene una colección fija de sinónimos y puede convertir un sinónimo al correspondiente nombre de clave conocido.

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 . Para obtener una lista de sinónimos aceptables, vea la propiedad ConnectionString.

La propiedad Item intenta insertar entradas malintencionadas. Por ejemplo, el siguiente código, utilizando la propiedad Item predeterminada (el indizador en C#) establece una secuencia de escape correcta para el par clave-valor anidado:

Dim builder As New System.Data.SqlClient.SqlConnectionStringBuilder
builder("Data Source") = "(local)"
builder("Integrated Security") = True
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"
Console.WriteLine(builder.ConnectionString)

System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.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 una manera segura:

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

Constructores

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 facilita los datos para la información de conexión interna de la instancia.

Propiedades

ApplicationIntent	Declara el tipo de carga de trabajo de la aplicación al conectarse a una base de datos en un Grupo de disponibilidad de SQL Server. Se puede establecer el valor de esta propiedad con ApplicationIntent. Para obtener más información sobre la compatibilidad de SqlClient con grupos de disponibilidad AlwaysOn, vea 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.
AttachDBFilename	Obtiene o establece una cadena que contiene el nombre del archivo de datos principal. La cadena incluye el nombre completo de la ruta de acceso a una base de datos asociable.
BrowsableConnectionString	Obtiene o establece un valor que indica si la propiedad ConnectionString está visible en los diseñadores de Visual Studio. (Heredado de DbConnectionStringBuilder)
ConnectionString	Obtiene o establece la cadena de conexión asociada con el DbConnectionStringBuilder. (Heredado de DbConnectionStringBuilder)
ConnectRetryCount	El número de reintentos de conexión que se han intentado después de identificar que se ha producido un error de conexión inactiva. Esto debe ser un número entero del 0 al 255. El valor predeterminado es 1. Establézcalo en 0 para deshabilitar la repetición de la conexión con errores de conexión inactiva. Se generará una ArgumentException 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 la identificación de que se produjo un error de conexión inactiva. Esto debe ser un número entero del 1 al 60. El valor predeterminado es 10 segundos. Se generará una ArgumentException si se establece en un valor fuera del intervalo permitido.
ConnectTimeout	Obtiene o establece el tiempo de espera, expresado en segundos, antes de terminar el intento de conexión con un servidor y generar un error.
Count	Obtiene el número actual de claves que están dentro de la propiedad ConnectionString. (Heredado de DbConnectionStringBuilder)
CurrentLanguage	Obtiene o establece el nombre del registro de lenguaje de SQL Server.
DataSource	Obtiene o establece el nombre o la dirección de red de la instancia de SQL Server con la que se va a establecer la conexión.
Encrypt	Obtiene o establece un valor booleano que indica si SQL Server utiliza el cifrado SSL para todos los datos que se envían entre el cliente y servidor si el servidor tiene instalado un certificado.
Enlist	Obtiene o establece un valor booleano que indica si el concentrador de conexiones de SQL Server muestra automáticamente la conexión en el contexto de la transacción actual del subproceso de creación.
FailoverPartner	Obtiene o establece el nombre o la dirección del servidor asociado con el que se va a establecer la conexión si el servidor principal está inactivo.
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 están especificados el identificador de usuario y la contraseña en la conexión (cuando es false) o si se utilizan las actuales credenciales de cuenta de Windows para la autenticación (cuando es true).
IsFixedSize	Obtiene un valor que indica si el objeto DbConnectionStringBuilder tiene un tamaño fijo. (Heredado de DbConnectionStringBuilder)
IsReadOnly	Obtiene un valor que indica si DbConnectionStringBuilder es de solo lectura. (Heredado de DbConnectionStringBuilder)
Item[String]	Obtiene o establece el valor asociado a la clave especificada. En C#, esta propiedad es el indizador.
Keys	Obtiene una ICollection que contiene las claves de SqlConnectionStringBuilder.
LoadBalanceTimeout	Obtiene o establece el tiempo mínimo, expresado en segundos, durante el cual la conexión permanece activa en la agrupación de conexiones antes de que se destruya.
MaxPoolSize	Obtiene o establece el número máximo de conexiones permitido en la agrupación de conexiones para esta cadena de conexión específica.
MinPoolSize	Obtiene o establece el número mínimo de conexiones permitido en la agrupación de conexiones para esta cadena de conexión específica.
MultipleActiveResultSets	Si es true, una aplicación puede mantener Conjuntos de resultados activos múltiples (MARS). Si 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 (AG) de Always On o Always On instancia de clúster de conmutación por error (FCI) en subredes diferentes, el establecimiento de MultiSubnetFailover=true proporciona una detección y conexión más rápidas con el servidor activo (actualmente). Para obtener más información sobre la compatibilidad de SqlClient con las características de Always On, consulte Compatibilidad con SqlClient para alta disponibilidad y recuperación ante desastres.
PacketSize	Obtiene o establece el tamaño, expresado en bytes, de los paquetes de red utilizados para establecer comunicación con una instancia de SQL Server.
Password	Obtiene o establece la contraseña para la cuenta de SQL Server.
PersistSecurityInfo	Obtiene o establece un valor 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 un estado abierto.
Pooling	Obtiene o establece un valor booleano que indica si la conexión se agrupará o se abrirá explícitamente cada vez que sea solicitada.
Replication	Obtiene o establece un valor booleano que indica si se admite la replicación al utilizarse la conexión.
TransactionBinding	Obtiene o establece un valor de cadena que indica cómo mantiene la conexión su asociación a una transacción System.Transactions dada de alta.
TrustServerCertificate	Obtiene o establece un valor que indica si se va a cifrar el canal, al mismo tiempo que se omite recorrer 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 utilizar al conectarse a SQL Server.
UserInstance	Obtiene o establece un valor que indica si debe redirigirse la conexión de la instancia predeterminada de SQL Server Express a una instancia iniciada en tiempo de ejecución que se ejecuta en la cuenta del llamador.
Values	Obtiene un ICollection 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

Add(String, Object)	Agrega una entrada con la clave y el valor especificados a DbConnectionStringBuilder. (Heredado de DbConnectionStringBuilder)
Clear()	Borra el contenido de la instancia de SqlConnectionStringBuilder.
ClearPropertyDescriptors()	Borra la colección de objetos PropertyDescriptor del DbConnectionStringBuilder asociado. (Heredado de DbConnectionStringBuilder)
ContainsKey(String)	Determina si SqlConnectionStringBuilder contiene una clave específica.
Equals(Object)	Determina si el objeto especificado es igual que el objeto actual. (Heredado de Object)
EquivalentTo(DbConnectionStringBuilder)	Compara la información de conexión de este objeto DbConnectionStringBuilder con la información de conexión del objeto especificado. (Heredado de DbConnectionStringBuilder)
GetHashCode()	Sirve como la función hash predeterminada. (Heredado de Object)
GetProperties(Hashtable)	Rellena un Hashtable proporcionado con información sobre todas las propiedades de este DbConnectionStringBuilder. (Heredado de DbConnectionStringBuilder)
GetType()	Obtiene el Type de la instancia actual. (Heredado de Object)
MemberwiseClone()	Crea una copia superficial del Object actual. (Heredado de Object)
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.
ToString()	Devuelve la cadena de conexión asociada a este DbConnectionStringBuilder. (Heredado de DbConnectionStringBuilder)
TryGetValue(String, Object)	Recupera un valor que corresponde a la clave proporcionada por este SqlConnectionStringBuilder.

Métodos de extensión

Consulte también

• Cadenas de conexión (ADO.NET)
• Información general de ADO.NET