EntityConnection.ConnectionString Property

Definition

Namespace:

System.Data.EntityClient

Assembly:

System.Data.Entity.dll

Gets or sets the EntityConnection connection string.

public:
 virtual property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };

public override string ConnectionString { get; set; }

member this.ConnectionString : string with get, set

Public Overrides Property ConnectionString As String

Property Value

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.

Exceptions

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.

Examples

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();
}

' Specify the provider name, server and database.
Dim providerName As String = "System.Data.SqlClient"
Dim serverName As String = "."
Dim databaseName As String = "AdventureWorks"

' Initialize the connection string builder for the
' underlying provider.
Dim sqlBuilder As New SqlConnectionStringBuilder

' Set the properties for the data source.
sqlBuilder.DataSource = serverName
sqlBuilder.InitialCatalog = databaseName
sqlBuilder.IntegratedSecurity = True

' Build the SqlConnection connection string.
Dim providerString As String = sqlBuilder.ToString

' Initialize the EntityConnectionStringBuilder.
Dim entityBuilder As New EntityConnectionStringBuilder

'Set the provider name.
entityBuilder.Provider = providerName
' Set the provider-specific connection string.
entityBuilder.ProviderConnectionString = providerString
' Set the Metadata location to the current directory.
entityBuilder.Metadata = "res://*/AdventureWorksModel.csdl|" & _
                            "res://*/AdventureWorksModel.ssdl|" & _
                            "res://*/AdventureWorksModel.msl"

Console.WriteLine(entityBuilder.ToString)

Using conn As EntityConnection = New EntityConnection(entityBuilder.ToString)
    conn.Open()
    Console.WriteLine("Just testing the connection.")
    conn.Close()
End Using

Remarks

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.

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 parameterless 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 Open or 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.

See also

• Connection Strings
• Connection Strings (Entity Framework)