Export (0) Print
Expand All

EntityConnection.ConnectionString Property

Gets or sets the EntityConnection connection string.

Namespace:  System.Data.EntityClient
Assembly:  System.Data.Entity (in System.Data.Entity.dll)

public override string ConnectionString { get; set; }

Property Value

Type: System.String
The connection string required to establish the initial connection to a data source. The default value is an empty string. On a closed connection, the currently set value is returned. If no value has been set, an empty string is returned.

Implements

IDbConnection.ConnectionString

ExceptionCondition
InvalidOperationException

An attempt was made to set the ConnectionString property after the [EntityConnection]’s MetadataWorkspace was initialized. The [MetadataWorkspace] is initialized either when the [EntityConnection] instance is constructed through the overload that takes a [MetadataWorkspace] as a parameter, or when the EntityConnection instance has been opened.

ArgumentException

An invalid connection string keyword has been provided or a required connection string keyword has not been provided.

An EntityClient connection string consists of a sequence of keyword/value parameter pairs separated by semicolons. The equals sign (=) connects each keyword and its value. The following table lists the valid names for keyword values in the ConnectionString.

Keyword

Description

Provider

Required if the Name keyword is not specified. The provider name, which is used to retrieve the DbProviderFactory object for the underlying provider. This value is constant.

When the Name keyword is not included in the connection string, a non-empty value for the Provider keyword is required. This keyword is mutually exclusive with the Name keyword.

Provider Connection String

Optional. Specifies the provider-specific connection string that is passed to the underlying data source. This connection string is expressed by using valid keyword/value pairs for the data provider. An invalid Provider Connection String will cause a run-time error when it is evaluated by the data source.

This keyword is mutually exclusive with the Name keyword.

The value of the Provider Connection String must be surrounded by quotes. The following is an example:

Provider Connection String ="Server=serverName; User ID = userID";

The following example is not going to work:

Provider Connection String =Server=serverName; User ID = userID

Metadata

Required if the Name keyword is not specified. A pipe-delimited list of directories, files, and resource locations in which to look for model and mapping information. The following is an example:

Metadata=

c:\model | c:\model\sql\mapping.msl;

Blank spaces on each side of the pipe separator are ignored.

This keyword is mutually exclusive with the Name keyword.

Name

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 Name keyword is not allowed in a configuration file.

When the Name keyword is not included in the connection string, a non-empty values for Provider keyword is required.

This keyword is mutually exclusive with all the other connection string keywords.

The application can supply the keyword/values directly in the ConnectionString property, or it can specify a value for the Name keyword. If the Name keyword is specified, the connection string keyword/values are retrieved from an application configuration file, as follows:

Name=AdventureWorksEntities;

If the Name keyword is used in the ConnectionString property, other keywords are not allowed. The Name keyword refers to a named connection string that is stored in the connectionStrings section in an application configuration file, as shown in the following example. The Provider, Metadata, and Provider Connection String values are retrieved from the configuration file at run time.

<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>

The keyword/value pairs can also be supplied directly in the ConnectionString property, as shown in the following example. In this case, the Name keyword is not used.

"Provider=System.Data.SqlClient;
Metadata=c:\metadata|c:\Metadata\Sql;
Provider Connection String= 'Data Source=localhost;
    Initial Catalog=AdventureWorks;Integrated Security=True;Connection Timeout=60' "

To avoid inadvertently putting objects such as System.Data.Common.CommandTrees and ObjectContext out of sync with their metadata, EntityConnection must lock its metadata. No changes to the connection string are allowed after the metadata is locked. The following are two scenarios in which metadata is locked:

  • The EntityConnection instance is constructed through the default constructor, or through the EntityConnection(String) constructor, which accepts a connection string. In either case the connection string might be changed multiple times before the connection is opened. Calling [M:System.Data.EntityClient.EntityConnection.Open()] or [M:System.Data.EntityClient.EntityConnection.GetMetadataWorkspace()] locks the metadata.

  • The EntityConnection instance is constructed through the EntityConnection(MetadataWorkspace, DbConnection) constructor, which accepts a MetadataWorkspace and a DbConnection. In this case the metadata is locked at construction time. No changes to the connection string are ever allowed.

When metadata is loaded, the EntityConnection verifies that the conceptual model, the storage model, and the mapping file are all present.

The following example demonstrates how to use the EntityConnectionStringBuilder in conjunction with a SqlConnectionStringBuilder. The code sets properties of a SqlConnectionStringBuilder to create a SqlConnection string that supplies part of the underlying provider connection string. Note that the Provider name cannot be set by using the SqlConnectionStringBuilder, because it does not use valid SqlConnection syntax. The code creates the EntityConnection string by setting EntityConnectionStringBuilder properties.


// Specify the provider name, server and database. 
string providerName = "System.Data.SqlClient";
string serverName = ".";
string databaseName = "AdventureWorks";

// Initialize the connection string builder for the 
// underlying provider.
SqlConnectionStringBuilder sqlBuilder =
    new SqlConnectionStringBuilder();

// Set the properties for the data source.
sqlBuilder.DataSource = serverName;
sqlBuilder.InitialCatalog = databaseName;
sqlBuilder.IntegratedSecurity = true;

// Build the SqlConnection connection string. 
string providerString = sqlBuilder.ToString();

// Initialize the EntityConnectionStringBuilder.
EntityConnectionStringBuilder entityBuilder =
    new EntityConnectionStringBuilder();

//Set the provider name.
entityBuilder.Provider = providerName;

// Set the provider-specific connection string.
entityBuilder.ProviderConnectionString = providerString;

// Set the Metadata location.
entityBuilder.Metadata = @"res://*/AdventureWorksModel.csdl|
                            res://*/AdventureWorksModel.ssdl|
                            res://*/AdventureWorksModel.msl";
Console.WriteLine(entityBuilder.ToString());

using (EntityConnection conn =
    new EntityConnection(entityBuilder.ToString()))
{
    conn.Open();
    Console.WriteLine("Just testing the connection.");
    conn.Close();
}

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5 SP1

.NET Framework Client Profile

Supported in: 4

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft