Cadenas de conexión (Entity Framework)

Una cadena de conexión contiene información de inicialización que se transfiere como un parámetro desde un proveedor de datos a un origen de datos. La sintaxis depende del proveedor de datos y la cadena de conexión se analiza mientras se intenta abrir una conexión. Las cadenas de conexión que usa Entity Framework contienen la información que se emplea para conectar con el proveedor de datos ADO.NET subyacente que Entity Framework admite. También contienen información sobre los archivos del modelo y de asignación necesarios.

El proveedor de EntityClient utiliza la cadena de conexión al obtener acceso a los metadatos del modelo y de asignación y al conectar con el origen de datos. Se puede obtener acceso a la cadena de conexión o establecerse a través de la propiedad ConnectionString de EntityConnection. La clase EntityConnectionStringBuilder se puede utilizar para construir mediante programación los parámetros de la cadena de conexión o tener acceso a ellos. Para obtener más información, vea Cómo generar una cadena de conexión EntityConnection (Entity Framework).

Las herramientas de Entity Data Model generan una cadena de conexión que se almacena en el archivo de configuración de la aplicación. ObjectContext recupera esta información de conexión automáticamente al crear consultas de objetos. Se puede tener acceso al elemento EntityConnection que usa una instancia de ObjectContext desde la propiedad Connection. Para obtener más información, vea Administrar conexiones y transacciones (Entity Framework).

Parámetros de la cadena de conexión

El formato de una cadena de conexión es una lista de pares de parámetros de clave y valor delimitados por punto y coma:

keyword1=value; keyword2=value;

El signo igual (=) asocia cada palabra clave a su valor. Las palabras clave no distinguen entre mayúsculas y minúsculas y los espacios entre los pares clave-valor se omiten. Sin embargo, los valores pueden distinguir entre mayúsculas y minúsculas, en función del origen de datos. Los valores que contengan un punto y coma, caracteres de comilla sencilla o caracteres de comilla doble deben colocarse entre comillas dobles. En la tabla siguiente se muestran los nombres válidos para los valores de palabra clave en la propiedad ConnectionString.

Palabra clave	Descripción
Provider	Se requiere si no se especifica la palabra clave Name. El nombre del proveedor, que se usa para recuperar el objeto DbProviderFactory para el proveedor subyacente. Este valor es constante. Cuando la palabra clave Name no se incluye en una cadena de conexión de Entity, se requiere un valor no vacío para la palabra clave Provider. Esta palabra clave y la palabra clave Name se excluyen mutuamente.
Provider Connection String	Opcional. Especifica la cadena de conexión específica del proveedor que se pasa al origen de datos subyacente. Esta cadena de conexión se expresa mediante pares de palabra clave y valor válidos para el proveedor de datos. Un valor de Provider Connection String no válido provocará un error en tiempo de ejecución cuando sea evaluado por el origen de datos. Esta palabra clave y la palabra clave Name se excluyen mutuamente. El valor de Provider Connection String debe estar entrecomillado. A continuación se muestra un ejemplo: Provider Connection String ="Server=serverName; User ID = userID"; El ejemplo siguiente no va a funcionar: Provider Connection String =Server=serverName; User ID = userID
Metadata	Se requiere si no se especifica la palabra clave Name. Una lista delimitada por barras verticales de los directorios, archivos y localizadores de recursos en que se ha de buscar información de asignación y metadatos. A continuación se muestra un ejemplo: Metadata= c:\model | c:\model\sql\mapping.msl; Los espacios en blanco a cada lado del separador de barra vertical se pasan por alto. Esta palabra clave y la palabra clave Name se excluyen mutuamente.
Name	La aplicación puede especificar, si se desea, el nombre de conexión en un archivo de configuración de la aplicación que proporcione los valores de cadena de conexión con pares de palabra clave y valor necesarios. En este caso, no es posible suministrarlos directamente en la cadena de conexión. La palabra clave Name no se permite en un archivo de configuración. Cuando la palabra clave Name no se incluye en la cadena de conexión, se requiere un valor no vacío para la palabra clave Provider. Esta palabra clave y todas las demás palabras clave de cadena de conexión se excluyen mutuamente.

El siguiente es un ejemplo de una cadena de conexión para el modelo AdventureWorks Sales almacenado en el archivo de configuración de la aplicación:

<connectionStrings>
    <add name="AdventureWorksEntities" 
         connectionString="metadata=.\AdventureWorks.csdl|.\AdventureWorks.ssdl|.\AdventureWorks.msl;
         provider=System.Data.SqlClient;provider connection string='Data Source=localhost;
         Initial Catalog=AdventureWorks;Integrated Security=True;Connection Timeout=60;
         multipleactiveresultsets=true'" providerName="System.Data.EntityClient" />
</connectionStrings>

Ubicaciones de los archivos del modelo y de asignación

El parámetro Metadata contiene una lista de ubicaciones en las que el proveedor EntityClient busca los archivos del modelo y de asignación. Los archivos del modelo y de asignación se suelen implementar en el mismo directorio que el archivo ejecutable de la aplicación. Estos archivos también se pueden implementar en una ubicación concreta o incluirse como un recurso incrustado en la aplicación.

Los recursos incrustados se especifican como sigue:

Metadata=res://<assemblyFullName>/<resourceName>. 

Las opciones siguientes están disponibles para definir la ubicación de un recurso incrustado:

Opción	Descripción
assemblyFullName	Nombre completo de un ensamblado con el recurso incrustado. El nombre incluye el nombre sencillo, nombre de la versión, referencia cultural admitida y clave pública, como se indica a continuación: ResourceLib, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null Los recursos se pueden incrustar en cualquier ensamblado al que la aplicación pueda tener acceso. Si especifica un carácter comodín (*) para assemblyFullName, el motor de tiempo de ejecución de Entity Framework buscará los recursos en las ubicaciones siguientes, en este orden: El ensamblado que realiza la llamada. Los ensamblados a los que se hace referencia. Los ensamblados en el directorio bin de una aplicación. Si los archivos no están en ninguna de estas ubicaciones, se lanzará una excepción. Nota: Al utilizar el carácter comodín (*), Entity Framework tiene que buscar a través de todos los ensamblados los recursos con el nombre correcto.Para mejorar el rendimiento, especifique el nombre de ensamblado en lugar del carácter comodín.
resourceName	Nombre del recurso incluido, como AdvendtureWorksModel.csdl. Los servicios de metadatos solo buscarán los archivos o recursos con una de las extensiones siguientes: .csdl, .ssdl o .msl. Si no se especifica resourceName, se cargarán todos los recursos de metadatos. Los recursos deberían tener nombres únicos dentro de un ensamblado. Si varios archivos con el mismo nombre se definen en directorios diferentes en el ensamblado, la información de resourceName debe incluir la estructura de carpetas antes del nombre del recurso, por ejemplo nombreDeCarpeta.nombreDeArchivo.csdl. resourceName no se requiere al especificar un carácter comodín (*) para assemblyFullName.

Nota:
Para mejorar el rendimiento, incruste los recursos en el ensamblado que realiza la llamada, excepto en escenarios sin web donde no haya ninguna referencia a los archivos de metadatos y asignaciones subyacentes en el ensamblado que realiza la llamada.

En el ejemplo siguiente se cargan todos los archivos del modelo y de asignación en el ensamblado que realiza la llamada, ensamblados a los que se hace referencia y otros ensamblados en el directorio bin de una aplicación.

Metadata=res://*/

El ejemplo siguiente carga el archivo model.csdl del ensamblado AdventureWorks y carga los archivos model.ssdl y model.msl desde el directorio predeterminado de la aplicación en ejecución.

Metadata=res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.csdl|model.ssdl|model.msl

En el ejemplo siguiente se cargan los tres recursos especificados del ensamblado concreto.

Metadata=res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.csdl| 
res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.ssdl| 
res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/model.msl

En el ejemplo siguiente se cargan todos los recursos incrustados con las extensiones .csdl, .msl y .ssdl del ensamblado.

Metadata=res://AdventureWorks, 1.0.0.0, neutral, a14f3033def15840/

En el ejemplo siguiente se cargan todos los recursos en la ruta de acceso del archivo relativa más "datadir\metadata\" desde la ubicación de ensamblado cargada.

Metadata=datadir\metadata\

En el ejemplo siguiente se cargan todos los recursos en la ruta de acceso del archivo relativa desde la ubicación de ensamblado cargada.

Metadata=.  \  

Compatibilidad con la cadena de sustitución |DataDirectory| y operator raíz de aplicación web (~)

DataDirectory y el operador ~ se utilizan en la ConnectionString como parte de las palabras clave Metadata y Provider Connection String. El elemento EntityConnection reenvía DataDirectory y el operador ~ a MetadataWorkspace y al proveedor de almacenamiento, respectivamente.

Término	Descripción
|DataDirectory|	Se resuelve como una ruta de acceso relativa a archivos de metadatos y una asignación. Se trata del valor que se establece a través del método AppDomain.SetData("DataDirectory", objValue). La cadena de sustitución DataDirectory debe incluirse entre caracteres de barra vertical y no puede haber ningún espacio en blanco entre su nombre y los caracteres de barra vertical. El nombre de DataDirectory no distingue entre mayúsculas y minúsculas. Si hay que pasar un directorio físico denominado "DataDirectory" como miembro de la lista de rutas de acceso de los metadatos, agregue el espacio en blanco en uno de los laterales del nombre o en ambos, por ejemplo: Metadata="DataDirectory1 | DataDirectory | DataDirectory2". Una aplicación ASP.NET resuelve | DataDirectory | como la carpeta "<raíz de la aplicación>/app_data".
~	Se resuelve como la raíz de la aplicación web. El carácter ~ en una posición inicial siempre se interpreta como el operador raíz de la aplicación web (~), aunque podría representar un subdirectorio local válido. Para hacer referencia a este tipo de subdirectorio local, el usuario debería pasar ./~ explícitamente.

DataDirectory y el operador ~ solo se deberían especificar al principio de una ruta de acceso; no se resuelven en ninguna otra posición. Entity Framework intentará resolver ~/data, pero tratará /data/~ como una ruta de acceso física.

Una ruta de acceso que comience con DataDirectory o con el operador ~ no se puede resolver como una ruta de acceso física fuera de la rama de DataDirectory y el operador ~. Por ejemplo, las rutas de acceso siguientes se resolverán: ~, ~/data, ~/bin/Model/SqlServer. Las rutas de acceso siguientes no se resolverán: ~/.., ~/../other.

DataDirectory y el operador ~ se puede extender para incluir los subdirectorios, de la forma siguiente: |DataDirectory|\Model, ~/bin/Model

La resolución de la cadena de sustitución DataDirectory y el operador ~ no es recursiva. Por ejemplo, cuando DataDirectory incluye el carácter ~, se lanza una excepción. De esta forma se evita una recursividad infinita.

Vea también

Conceptos

Consideraciones de implementación (Entity Framework)
Administrar conexiones y transacciones (Entity Framework)

Otros recursos

Trabajar con proveedores de Datos (Entity Framework)
Connection Strings (ADO.NET)