SqlConnection.ConnectionString (Propiedad)
Ensamblado: System.Data (en system.data.dll)
/** @property */ public String get_ConnectionString () /** @property */ public void set_ConnectionString (String value)
public override function get ConnectionString () : String public override function set ConnectionString (value : String)
Valor de propiedad
Cadena de conexión que incluye el nombre de la base de datos de origen y otros parámetros necesarios para establecer la conexión inicial. El valor predeterminado es una cadena vacía.ConnectionString es similar a una cadena de conexión de OLE DB, aunque no idéntico. A diferencia de OLE DB y ADO, la cadena de conexión que se devuelve es la misma que la que establece el usuario en ConnectionString menos la información de seguridad si el valor de Persist Security Info está establecido en false (valor predeterminado). El proveedor de datos de .NET Framework para SQL Server no se conserva en una cadena de conexión ni devuelve la contraseña, a no ser que el valor de Persist Security Info (Información de seguridad persistente) esté establecido en true.
Se puede utilizar la propiedad ConnectionString para conectarse a una base de datos. En el ejemplo siguiente se muestra una cadena de conexión típica.
"Persist Security Info=False;Integrated Security=SSPI;Initial Catalog=Northwind;server=(local)"
Utilice el nuevo SqlConnectionStringBuilder para construir cadenas de conexión válidas en tiempo de ejecución. Para obtener más información, vea Building Connection Strings.
La propiedad ConnectionString sólo se puede configurar cuando la conexión está cerrada. Muchos de los valores de cadena de conexión tienen propiedades asociadas de sólo lectura. Cuando se establece la cadena de conexión, se actualizan estas propiedades, excepto cuando se detecta un error. En este caso, no se actualiza ninguna de las propiedades. Las propiedades de SqlConnection devuelven únicamente los valores contenidos en la propiedad ConnectionString.
Para conectarse a un equipo local, especifique "(local)" para el servidor. (Se debe especificar siempre un servidor).
El restablecimiento de ConnectionString de una conexión cerrada, restablece todos los valores de la cadena de conexión (y propiedades relacionadas) incluida la contraseña. Por ejemplo, si se establece una cadena de conexión que incluya "Database= AdventureWorks" y, a continuación, se restablece la cadena de conexión en "Data Source=myserver;Integrated Security=SSPI", el valor de la propiedad Database deja de ser "AdventureWorks".
La cadena de conexión se analiza inmediatamente, una vez establecida. Si durante el análisis se encuentran errores en la sintaxis, se genera una excepción en tiempo de ejecución, como ArgumentException. Se pueden encontrar otros errores sólo cuando se realiza un intento para abrir la conexión.
El formato básico de una cadena de conexión incluye una serie de pares de palabra clave y valor separados por puntos y comas. El signo igual (= ) asocia cada palabra clave a su valor. Para incluir valores que contengan punto y coma, un carácter de comillas simples o un carácter de comillas dobles, el valor debe escribirse entre comillas dobles. Si el valor contiene un punto y coma y un carácter de comillas dobles, se puede escribir entre comillas simples. Las comillas simples se utilizan también si el valor comienza por un carácter de comillas dobles. Y a la inversa, si el valor comienza por comillas simples, se pueden utilizar las comillas dobles. Si el valor contiene caracteres de comillas simples y de comillas dobles, el carácter de comillas entre el que se encierra el valor deberá duplicarse cada vez que aparezca dentro del valor.
Para incluir espacios iniciales o finales en el valor de la cadena, el valor debe escribirse entre comillas simples o comillas dobles. No se tienen en cuenta los espacios iniciales o finales que rodean a los valores enteros, booleanos o enumerados, aunque estén entre comillas. Sin embargo, se conservan los espacios incluidos dentro de una palabra clave o un valor literal de una cadena. Con la versión 1.1 o posterior de .NET Framework, se pueden utilizar comillas simples o dobles dentro de una cadena de conexión sin utilizar delimitadores (por ejemplo, Data Source= my'Server o Data Source= my"Server), a menos que las comillas sean el primer o último carácter del valor.
Para incluir un signo igual (=) en una palabra clave o valor, debe ir precedido de otro signo igual. Por ejemplo, en la hipotética cadena de conexión
"key==word=value"
la palabra clave es "key=word" y el valor es "value".
Si una palabra clave específica de un par palabra clave/valor aparece varias veces en una cadena de conexión, en el valor establecido se utiliza la última palabra clave que aparece.
Las palabras clave no distinguen entre mayúsculas y minúsculas.
En la siguiente tabla se muestran los nombres válidos para los valores de palabras clave dentro de la propiedad ConnectionString.
| Palabra clave | Valor predeterminado | Descripción | ||
|---|---|---|---|---|
| Application Name | N/D | Nombre de la aplicación o '.NET SQLClient Data Provider' si no se proporciona el nombre de la aplicación. | ||
| Asynch | 'false' | Cuando es true, habilita la compatibilidad con las operaciones asincrónicas. Los valores reconocidos son true, false, yes y no. | ||
| AttachDBFilename O bien extended properties O bien Initial File Name | N/D | Nombre del archivo de base de datos principal, incluido el nombre de la ruta de acceso completa de una base de datos que se puede asociar. La ruta de acceso puede ser absoluta o relativa utilizando la cadena de sustitución DataDirectory. Si se utiliza DataDirectory, el archivo de base de datos debe existir en un subdirectorio del directorio señalado por la cadena de sustitución.
El nombre de la base de datos debe especificarse con la palabra clave 'database' (o uno de sus alias) como en el ejemplo siguiente: "AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase" | ||
| Connect Timeout O bien Connection Timeout | 15 | Tiempo de espera expresado en segundos antes de terminar el intento de conexión con un servidor y generar un error. | ||
| Context Connection | 'false' | true si se debe realizar una conexión en proceso a SQL Server. | ||
| Current Language | N/D | Nombre del registro de lenguaje de SQL Server. | ||
| Data Source O bien Server O bien Address O bien Addr O bien Dirección de red | N/D | Dirección de red o nombre de la instancia de SQL Server con la que se va a establecer la conexión. El número de puerto se puede especificar después del nombre del servidor: server=tcp:servername, portnumber Al especificar una instancia local, utilice siempre (local). Para forzar un protocolo, agregue uno de los prefijos siguientes: np:(local), tcp:(local), lpc:(local) | ||
| Encrypt | 'false' | Cuando es true, SQL Server utiliza el cifrado SSL para todos los datos enviados entre el cliente y el servidor, si el servidor tiene instalado un certificado. Los valores reconocidos son true, false, yes y no. | ||
| Enlist | 'false' | true indica que el agrupador de conexión de SQL Server da de alta automáticamente la conexión en el contexto de transacción actual del subproceso de creación. | ||
| Failover Partner | N/D | Nombre del servidor asociado de conmutación por error donde se configura la creación de reflejo de la base de datos. Las versiones 1.0 y 1.1 de .NET Framework no admiten la palabra clave Failover Partner. | ||
| Initial Catalog O bien Database | N/D | Nombre de la base de datos. | ||
| Integrated Security O bien Trusted_Connection | 'false' | Si es false, en la conexión se especifican el identificador de usuario y la contraseña. Si es true, se utilizan las credenciales actuales de la cuenta de Windows para la autenticación. Los valores reconocidos son true, false, yes, no y sspi (muy recomendable) que equivale a true. | ||
| MultipleActiveResultSets | 'true' | Cuando es true, una aplicación puede mantener conjuntos de resultados activo múltiple (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. Los valores reconocidos son true y false. Las versiones 1.0 y 1.1 de .NET Framework no admiten la palabra clave. | ||
| Network Library O bien Net | 'dbmssocn' | Biblioteca de red utilizada para establecer una conexión con una instancia de SQL Server. Entre los valores compatibles se incluyen: dbnmpntw (Canalizaciones con nombre), dbmsrpcn (Multiprotocolo), dbmsadsn (Apple Talk), dbmsgnet (VIA), dbmslpcn (Memoria compartida) y dbmsspxn (IPX/SPX), y dbmssocn (TCP/IP). La DLL de red correspondiente debe estar instalada en el sistema al que se conecta. Si no se especifica ninguna red y se utiliza un servidor local (por ejemplo, "." o "(local)"), se utiliza la memoria compartida. | ||
| Packet Size | 8192 | Tamaño en bytes de los paquetes de red utilizados para establecer comunicación con una instancia de SQL Server. | ||
| Password O bien Pwd | N/D | Contraseña para el inicio de sesión de la cuenta de SQL Server. No se recomienda. Para mantener un alto nivel de seguridad, se recomienda especialmente utilizar la palabra clave de seguridad de Integrated Security o Trusted_Connection. | ||
| Persist Security Info | 'false' | Cuando se establece en false o no (especialmente recomendado), la información de seguridad confidencial, como la contraseña, no se devuelve como parte de la conexión si la conexión está abierta o alguna vez ha indicado este estado. El restablecimiento de la cadena de conexión restablece todos los valores de la cadena de conexión incluida la contraseña. Los valores reconocidos son true, false, yes y no. | ||
| Replication | 'false' | true si se admite la replicación utilizando la conexión. | ||
| TrustServerCertificate | 'false' | Cuando se establece en true, SSL se utiliza para cifrar el canal al tiempo que se evita recorrer la cadena de certificados para validar la confianza. Si TrustServerCertificate se establece en true y Encrypt también se establece en false, el canal no se cifrará. Los valores reconocidos son true, false, yes y no. Para obtener más información, vea "Encryption Hierarchy" y "Using Encryption Without Validation" en los Libros en pantalla de SQL Server 2005. | ||
| Type System Version | N/D | Valor de cadena que indica el sistema de tipos que espera la aplicación. Los valores posibles son: Type System Version=SQL Server 2000; Type System Version=SQL Server 2005; Type System Version=Latest; Cuando se establece en SQL Server 2000, se utiliza el sistema de tipos de SQL Server 2000. Al conectar a una instancia de SQL Server se realizan las conversiones siguientes: XML a NTEXT UDT a VARBINARY VARCHAR (MAX), NVARCHAR (MAX) y VARBINARY (MAX) a TEXT, NEXT e IMAGE, respectivamente. Cuando se establece en SQL Server 2005, se utiliza el sistema de tipos de SQL Server 2005. No se realiza ninguna conversión para la versión actual de ADO.NET. Cuando se establece en Latest, se utiliza la versión más reciente que puede controlar este par cliente/servidor. Avanzará automáticamente a medida que se actualicen los componentes del cliente y del servidor. | ||
| User ID | N/D | Cuenta de inicio de sesión de SQL Server. No se recomienda. Para mantener un alto nivel de seguridad, se recomienda especialmente utilizar las palabras clave de seguridad de Integrated Security o Trusted_Connection. | ||
| User Instance | 'false' | 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. | ||
| Workstation ID | Nombre del equipo local | Nombre de la estación de trabajo que se conecta a SQL Server. |
En la siguiente tabla se recogen los nombres válidos para los valores de agrupación de conexiones dentro de ConnectionString. Para obtener más información, vea Uso de agrupación de conexiones.
| Nombre | Valor predeterminado | Descripción |
|---|---|---|
| Connection Lifetime | 0 | Cuando se devuelve una conexión al grupo, se compara la hora de creación con la hora actual, y la conexión se destruye si el intervalo de tiempo, expresado en segundos, supera el valor especificado por Connection Lifetime. Esto es útil en configuraciones agrupadas para forzar el equilibrio de cargas entre un servidor en ejecución y un servidor que se acaba de conectar. Si se especifica el valor cero (0), las conexiones agrupadas disponen del máximo tiempo de espera de conexión. |
| Connection Reset | 'true' | Determina si se restablece la conexión de la base de datos cuando se quita del grupo. Para la versión 7.0 de SQL Server, si se establece en false, se evitan las acciones de ida y vuelta adicionales al servidor cuando se obtiene una conexión, aunque se debe tener en cuenta que no se restablece el estado de la conexión como, por ejemplo, el contexto de base de datos. El método ChangeDatabase no influencia el concentrador de conexiones mientras no se establezca el valor de Connection Reset en false. Cuando la conexión sale del grupo, se restablece la conexión y el servidor vuelve a la base de datos del inicio de sesión. No se crea ninguna conexión nueva o no se producen nuevas autenticaciones. Si se establece el valor de Connection Reset en false, puede que se establezcan en el grupo conexiones a otras bases de datos. |
| Enlist | 'true' | Si este valor es true, el agrupador da de alta automáticamente la conexión en el contexto de la transacción actual del subproceso de creación. Los valores reconocidos son true, false, yes y no. |
| Load Balance Timeout | 0 | 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. |
| Max Pool Size | 100 | Número máximo de conexiones permitidas en el grupo. |
| Min Pool Size | 0 | Número mínimo de conexiones permitidas en el grupo. |
| Pooling | 'true' | Si es true, el objeto SQLConnection se extrae del grupo adecuado o, si es necesario, se crea y se agrega al grupo correspondiente. Los valores reconocidos son true, false, yes y no. |
Cuando se configuran valores de palabra clave o de agrupación de conexiones que requieren un valor booleano, se puede utilizar 'yes' en lugar de 'true' y 'no' en vez de 'false'. Los valores enteros se representan como cadenas.
 Nota |
|---|
| El proveedor de datos de .NET Framework para SQL Server utiliza su propio protocolo para comunicarse con SQL Server. Por tanto, no admite la utilización de un nombre de origen de datos ODBC para conectarse a SQL Server porque no agrega una capa ODBC. |
| Precaución |
|---|
| En esta versión, la aplicación debe ser cautelosa al generar una cadena de conexión basada en lo que escribe el usuario, por ejemplo, al recuperar la información de la identificación y la contraseña del usuario de un cuadro de diálogo y agregarla a la cadena de conexión. La aplicación debe asegurar que los usuarios no puedan incrustar parámetros de cadena de conexión adicionales en estos valores; por ejemplo, escribir una contraseña como "validpassword;database= somedb" para tratar de conectarse a otra base de datos. |
En el ejemplo siguiente se crea un objeto SqlConnection y se establece la propiedad ConnectionString antes de abrir la conexión.
private static void OpenSqlConnection() { string connectionString = GetConnectionString(); using (SqlConnection connection = new SqlConnection()) { connection.ConnectionString = connectionString; connection.Open(); Console.WriteLine("State: {0}", connection.State); Console.WriteLine("ConnectionString: {0}", connection.ConnectionString); } } static private string GetConnectionString() { // To avoid storing the connection string in your code, // you can retrieve it from a configuration file, using the // System.Configuration.ConfigurationSettings.AppSettings property return "Data Source=(local);Initial Catalog=AdventureWorks;" + "Integrated Security=SSPI;"; }
Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium, Windows Mobile para Pocket PC, Windows Mobile para Smartphone, Windows Server 2003, Windows XP Media Center, Windows XP Professional x64, Windows XP SP2, Windows XP Starter Edition
.NET Framework no admite todas las versiones de cada plataforma. Para obtener una lista de las versiones admitidas, vea Requisitos del sistema.
