Connection Strings in the ADO.NET Entity Framework
A connection string contains initialization information that is passed as a parameter from a data provider to a data source. The syntax depends on the data provider, and the connection string is parsed during the attempt to open a connection. Connection strings used by the Entity Framework contain information used to connect to the underlying ADO.NET data provider that supports the Entity Framework. They also contain information about the required model and mapping files.
The connection string is used by the EntityClient provider when accessing model and mapping metadata and connecting to the data source. The connection string can be accessed or set through the ConnectionString property of EntityConnection. The EntityConnectionStringBuilder class can be used to programmatically construct or access parameters in the connection string. For more information, see How to: Build an EntityConnection Connection String.
The Entity Data Model tools generate a connection string that is stored in the application's configuration file. ObjectContext retrieves this connection information automatically when creating object queries. The EntityConnection used by an ObjectContext instance can be accessed from the Connection property. For more information, see Managing Connections and Transactions.
Connection String Syntax
To learn about the general syntax for connection strings, see Connection string syntax | Connection Strings in ADO.NET.
Connection String Parameters
The following table lists the valid names for keyword values in the ConnectionString.
||Required if the
||Optional. Specifies the provider-specific connection string that is passed to the underlying data source. This connection string contains valid keyword/value pairs for the data provider. An invalid
This keyword is mutually exclusive with the
Make sure to escape the value according to the general syntax of ADO.NET connection strings. Consider for example the following connection string:
||Required if the
Blank spaces on each side of the pipe separator are ignored.
This keyword is mutually exclusive with the
||The application can optionally specify the connection name in an application configuration file that provides the required keyword/value connection string values. In this case, you cannot supply them directly in the connection string. The
This keyword is mutually exclusive with all the other connection string keywords.
The following is an example of a connection string for the AdventureWorks Sales Model stored in the application configuration file:
Model and Mapping File Locations
Metadata parameter contains a list of locations for the
EntityClient provider to search for model and mapping files. Model and mapping files are often deployed in the same directory as the application executable file. These files can also be deployed in a specific location or included as an embedded resource in the application.
Embedded resources are specified as follows:
The following options are available for defining the location of an embedded resource:
||The full name of an assembly with the embedded resource. The name includes the simple name, version name, supported culture, and public key, as follows:
Resources can be embedded in any assembly that is accessible by the application.
If you specify a wildcard (*) for
1. The calling assembly.
2. The referenced assemblies.
3. The assemblies in the bin directory of an application.
If the files are not in one of these locations, an exception will be thrown. Note: When you use wildcard (*), the Entity Framework has to look through all the assemblies for resources with the correct name. To improve performance, specify the assembly name instead of the wildcard.
||The name of the included resource, such as AdventureWorksModel.csdl. The metadata services will only look for files or resources with one of the following extensions: .csdl, .ssdl, or .msl. If
To improve performance, embed resources in the calling assembly, except in non-Web scenarios where there is no reference to underlying mapping and metadata files in the calling assembly.
The following example loads all the model and mapping files in the calling assembly, referenced assemblies, and other assemblies in the bin directory of an application.
The following example loads the model.csdl file from the AdventureWorks assembly, and loads the model.ssdl and model.msl files from the default directory of the running application.
Metadata=res://AdventureWorks, 22.214.171.124, neutral, a14f3033def15840/model.csdl|model.ssdl|model.msl
The following example loads the three specified resources from the specific assembly.
Metadata=res://AdventureWorks, 126.96.36.199, neutral, a14f3033def15840/model.csdl| res://AdventureWorks, 188.8.131.52, neutral, a14f3033def15840/model.ssdl| res://AdventureWorks, 184.108.40.206, neutral, a14f3033def15840/model.msl
The following example loads all the embedded resources with the extensions .csdl, .msl, and .ssdl from the assembly.
Metadata=res://AdventureWorks, 220.127.116.11, neutral, a14f3033def15840/
The following example loads all the resources in the relative file path plus "datadir\metadata\" from the loaded assembly location.
The following example loads all the resources in the relative file path from the loaded assembly location.
Support for the |DataDirectory| Substitution String and the Web Application Root Operator (~)
DataDirectory and the ~ operator are used in the ConnectionString as part of the
Provider Connection String keywords. The EntityConnection forwards the
DataDirectory and the ~ operator to MetadataWorkspace and the store provider, respectively.
||Resolves to a relative path to a mapping and metadata files. This is the value that is set through the
If a physical directory named "DataDirectory" has to be passed as a member of the list of metadata paths, add white space to either or both sides of the name. For example:
|~||Resolves to the Web application root. The ~ character at a leading position is always interpreted as the Web application root operator (~), although it might represent a valid local subdirectory. To refer to such a local subdirectory, the user should explicitly pass
DataDirectory and the ~ operator should be specified only at the beginning of a path, they are not resolved at any other position. The Entity Framework will try to resolve
~/data, but it will treat
/data/~ as a physical path.
A path that starts with the
DataDirectory or the ~ operator cannot resolve to a physical path outside the branch of the
DataDirectory and the ~ operator. For example, the following paths will resolve:
~/bin/Model/SqlServer. The following paths will fail to resolve:
DataDirectory and the ~ operator can be extended to include sub-directories, as follows:
The resolution of the
DataDirectory substitution string and the ~ operator is non-recursive. For example, when
DataDirectory includes the
~ character, an exception will occur. This prevents an infinite recursion.