Connection String Syntax (ADO.NET)

Each .NET Framework data provider has a Connection object that inherits from DbConnection as well as a provider-specific ConnectionString property. The specific connection string syntax for each provider is documented in its ConnectionString property. The following table lists the four data providers that are included in the .NET Framework.

Connection String Builders

ADO.NET 2.0 introduced the following connection string builders for the .NET Framework data providers.

• SqlConnectionStringBuilder

• OleDbConnectionStringBuilder

• OdbcConnectionStringBuilder

• OracleConnectionStringBuilder

The connection string builders allow you to construct syntactically valid connection strings at run time, so you do not have to manually concatenate connection string values in your code. For more information, see Connection String Builders (ADO.NET).

Windows Authentication

We recommend using Windows Authentication (sometimes referred to as integrated security) to connect to data sources that support it. The syntax employed in the connection string varies by provider. The following table shows the Windows Authentication syntax used with the .NET Framework data providers.

SqlClient Connection Strings

The syntax for a SqlConnection connection string is documented in the SqlConnection.ConnectionString property. You can use the ConnectionString property to get or set a connection string for a SQL Server 7.0 or later database. If you need to connect to an earlier version of SQL Server, you must use the .NET Framework Data Provider for OleDb (System.Data.OleDb). Most connection string keywords also map to properties in the SqlConnectionStringBuilder.

Each of the following forms of syntax will use Windows Authentication to connect to the AdventureWorks database on a local server.

"Persist Security Info=False;Integrated Security=true;
    Initial Catalog=AdventureWorks;Server=MSSQL1"
"Persist Security Info=False;Integrated Security=SSPI;
    database=AdventureWorks;server=(local)"
"Persist Security Info=False;Trusted_Connection=True;
    database=AdventureWorks;server=(local)"

SQL Server Logins

Windows Authentication is preferred for connecting to SQL Server. However, if SQL Server Authentication is required, use the following syntax to specify a user name and password. In this example, asterisks are used to represent a valid user name and password.

"Persist Security Info=False;User ID=*****;Password=*****;Initial Catalog=AdventureWorks;Server=MySqlServer"

Security Note
The default setting for thePersistSecurity Info keyword is false. Setting it to true or yes allows security-sensitive information, including the user ID and password, to be obtained from the connection after the connection has been opened. Keep PersistSecurity Info set to false to ensure that an untrusted source does not have access to sensitive connection string information.

To connect to a named instance of SQL Server, use the server name\instance name syntax.

Data Source=MySqlServer\MSSQL1;"

You can also set the DataSource property of the SqlConnectionStringBuilder to the instance name when building a connection string. The DataSource property of a SqlConnection object is read-only.

Type System Version Changes

The functionality available to a client application is dependent on the version of SQL Server and the compatibility level of the database. The Type System Version keywords in a SqlConnection.ConnectionString can be used to specify the client-side representation of SQL Server types. Explicitly setting the type system version that the client application was written for avoids potential problems that could cause an application to break if a different version of SQL Server is used. For example, UDT columns are represented as a byte[] array if you specify SQL Server 2000. If you specify SQL Server 2005, they are represented as managed types.

The available Type System Version values are described in the following table.

For compatibility with features introduced in SQL Server 2008, you can explicitly supply the Type System Version in the connection string by using one of the following.

Type System Version= SQL Server 2008;
Type System Version=Latest;

Connecting and Attaching to SQL Server Express User Instances

User instances are a new feature available in SQL Server 2005 Express Edition only. They allow a user running on a least-privileged local Windows account to attach and run a SQL Server database without requiring administrative privileges. A user instance executes with the user's Windows credentials, not as a service.

For more information on working with user instances, see Connecting to SQL Server Express User Instances (ADO.NET).

Using TrustServerCertificate

The TrustServerCertificate keyword is new in ADO.NET 2.0 and valid only when connecting to a SQL Server 2005 instance with a valid certificate. When TrustServerCertificate is set to true, the transport layer will use SSL to encrypt the channel and bypass walking the certificate chain to validate trust.

"TrustServerCertificate=true;" 

Enabling Encryption

To enable encryption when a certificate has not been provisioned on the server, the Force Protocol Encryption and the Trust Server Certificate options must be set in SQL Server Configuration Manager. In this case, encryption will use a self-signed server certificate without validation if no verifiable certificate has been provisioned on the server.

Application settings cannot reduce the level of security configured in SQL Server, but can optionally strengthen it. An application can request encryption by setting the TrustServerCertificate and Encrypt keywords to true, guaranteeing that encryption takes place even when a server certificate has not been provisioned and Force Protocol Encryption has not been configured for the client. However, if TrustServerCertificate is not enabled in the client configuration, a provisioned server certificate is still required.

The following table describes all cases.

For more information, see Using Encryption Without Validation in SQL Server Books Online.

OleDb Connection Strings

The ConnectionString property of a OleDbConnection allows you to get or set a connection string for an OLE DB data source, such as Microsoft Access or SQL Server 6.5 or earlier. You can also create an OleDb connection string at run time by using the OleDbConnectionStringBuilder class.

OleDb Connection String Syntax

You must specify a provider name for an OleDbConnection connection string. The following connection string connects to a Microsoft Access database using the Jet provider. Note that the UserID and Password keywords are optional if the database is unsecured (the default).

Provider=Microsoft.Jet.OLEDB.4.0; Data Source=d:\Northwind.mdb;User ID=Admin;Password=; 

If the Jet database is secured using user-level security, you must provide the location of the workgroup information file (.mdw). The workgroup information file is used to validate the credentials presented in the connection string.

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=d:\Northwind.mdb;Jet OLEDB:System Database=d:\NorthwindSystem.mdw;User ID=*****;Password=*****;

Use sqloledb for the Provider keyword for SQL Server version 6.5 or earlier.

Provider=sqloledb;Data Source=MySqlServer;Initial Catalog=pubs;User Id=*****;Password=*****;

Security Note
It is possible to supply connection information for an OleDbConnection in a Universal Data Link (UDL) file; however you should avoid doing so. UDL files are not encrypted, and expose connection string information in clear text. Because a UDL file is an external file-based resource to your application, it cannot be secured using the .NET Framework. UDL files are not supported for SqlClient.

Using DataDirectory to Connect to Access/Jet

DataDirectory is not exclusive to SqlClient. It can also be used with the System.Data.OleDb and System.Data.Odbc .NET data providers. The following sample OleDbConnection string demonstrates the syntax required to connect to the Northwind.mdb located in the application's app_data folder. The system database (System.mdw) is also stored in that location.

"Provider=Microsoft.Jet.OLEDB.4.0;
Data Source=|DataDirectory|\Northwind.mdb;
Jet OLEDB:System Database=|DataDirectory|\System.mdw;"

Security Note

Specifying the location of the system database in the connection string is not required if the Access/Jet database is unsecured. Security is off by default, with all users connecting as the built-in Admin user with a blank password. Even when user-level security is correctly implemented, a Jet database remains vulnerable to attack. Therefore, storing sensitive information in an Access/Jet database is not recommended because of the inherent weakness of its file-based security scheme.

Connecting to Excel

The Microsoft Jet provider is used to connect to an Excel workbook. In the following connection string, the Extended Properties keyword sets properties that are specific to Excel. "HDR=Yes;" indicates that the first row contains column names, not data, and "IMEX=1;" tells the driver to always read "intermixed" data columns as text.

Provider=Microsoft.Jet.OLEDB.4.0;Data Source=D:\MyExcel.xls;Extended Properties=""Excel 8.0;HDR=Yes;IMEX=1""

Note that the double quotation character required for the Extended Properties must also be enclosed in double quotation marks.

Data Shape Provider Connection String Syntax

Use both the Provider and the Data Provider keywords when using the Microsoft Data Shape provider. The following example uses the Shape provider to connect to a local instance of SQL Server.

"Provider=MSDataShape;Data Provider=SQLOLEDB;Data Source=(local);Initial Catalog=pubs;Integrated Security=SSPI;" 

Odbc Connection Strings

The ConnectionString property of a OdbcConnection allows you to get or set a connection string for an OLE DB data source. Odbc connection strings are also supported by the OdbcConnectionStringBuilder.

The following connection string uses the Microsoft Text Driver.

Driver={Microsoft Text Driver (*.txt; *.csv)};DBQ=d:\bin

Using DataDirectory to Connect to Visual FoxPro

The following OdbcConnection connection string sample demonstrates using DataDirectory to connect to a Microsoft Visual FoxPro file.

"Driver={Microsoft Visual FoxPro Driver};
SourceDB=|DataDirectory|\MyData.DBC;SourceType=DBC;"

Oracle Connection Strings

The ConnectionString property of a OracleConnection allows you to get or set a connection string for an OLE DB data source. Oracle connection strings are also supported by the OracleConnectionStringBuilder .

Data Source=Oracle9i;User ID=*****;Password=*****;

For more information on ODBC connection string syntax, see ConnectionString.

See Also

Other Resources

Connection Strings (ADO.NET)

Connecting to a Data Source (ADO.NET)

ADO.NET Managed Providers and DataSet Developer Center