Export (0) Print
Expand All

SQL Server Connection Director (ADO.NET)

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

Beginning in the .NET Framework version 4.0, the .NET Framework Data Provider for SQL Server (System.Data.SqlClient) supports the SQL Server Connection Director, which lets you specify a connection plan in a SqlConnection.ConnectionString instead of the name. For more information on the SQL Server Connection Director, see Using the SQL Server Connection Director.

When a client requests a new connection and pooling is enabled, SqlClient first checks the pool to see if there is a connection that matches the sample connection string along with the transaction and user context. For pooled Plan connections, the SQL connection pool asks the connection plan resolver to resolve the plan again and match new plan node data with the previous plan. If the connection plan has changed, the connection will not be reused.

Use the Plan keyword with ConnectionString to specify a connection plan when opening a SqlConnection.

string planConnectionString = 
  @"Plan=file://C:\MyPlans\MyServer1.xml; Integrated Security=true";
using (SqlConnection planConnection = 
  new SqlConnection(planConnectionString))
{
    planConnection.Open();

    // use the connection as before
}

You can now specify a connection plan in the SqlConnectionStringBuilder constructor using the PLAN keyword or by using the Plan property:

SqlConnectionStringBuilder connectionStringBuilder = new SqlConnectionStringBuilder();
connectionStringBuilder.Plan = @"file://C:\MyPlans\MyServer1.xml";
connectionStringBuilder.IntegratedSecurity = true;

using (SqlConnection con = new SqlConnection(conString))
{
    con.Open();
    // ...
}

An ArgumentException is thrown in the following cases:

  • The ConnectionString argument specifies a connection plan and a FailOverPartner.

  • The ConnectionString argument specifies a connection plan and an AttachDbFileName.

  • The ConnectionString argument specifies a connection plan and has UserInstance=true.

  • The ConnectionString argument specifies a connection plan and contextConnection=true.

  • The ConnectionString argument specifies a server and a connection plan. The server can be specified with any of the following keywords: Server, Data Source, Address, addr, or Network Address.

  • The ConnectionString argument has an empty value for a connection plan.

The following table lists the errors that can occur when the connection plan is processed:

Condition

Exception Type

Database is specified in connection string and in connection plan

ArgumentException

The connection plan resolver returns an error while trying to resolve the connection

ConnectionPlanException

Database mirroring is enabled on the server specified in the connection pool

SqlException

Timeout period expires before connection is made.

SqlException

XmlLite is not present and the operating system is Windows XP.

PlatformNotSupportedException

XmlLite is not present and the operating system is Windows Server 2003.

PlatformNotSupportedException

Note Note

Using the ChangePassword method will throw an InvalidOperationException if the ConnectionString specifies a connection plan.

Show:
© 2014 Microsoft