SqlCeConnection.ConnectionString Property

Gets or sets the string used to open a database.

Namespace:  System.Data.SqlServerCe
Assembly:  System.Data.SqlServerCe (in System.Data.SqlServerCe.dll)

Syntax

'Declaration
Public Overrides Property ConnectionString As String
    Get
    Set
'Usage
Dim instance As SqlCeConnection
Dim value As String

value = instance.ConnectionString

instance.ConnectionString = value
public override string ConnectionString { get; set; }
public:
virtual property String^ ConnectionString {
    String^ get () override;
    void set (String^ value) override;
}
abstract ConnectionString : string with get, set
override ConnectionString : string with get, set
override function get ConnectionString () : String
override function set ConnectionString (value : String)

Property Value

Type: System.String
The .NET Compact Framework Data Provider for SQL Server Compact connection string that includes the data source name and other parameters needed to establish the initial connection. The default value is an empty string.

Implements

IDbConnection.ConnectionString

Exceptions

Exception Condition
ArgumentException

An invalid connection string argument has been supplied.

Remarks

The ConnectionString property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, all of these properties are updated, except when an error is detected. In this case, none of the properties is updated. SqlCeConnection properties return only those settings contained in the ConnectionString.

Resetting the ConnectionString on a closed connection resets all connection string values and related properties, including the password.

The following table lists the ConnectionString properties supported in SQL Server Compact.

Property

Description

data source -or-datasource

The file path and name of the SQL Server Compact database. To indicate a relative path to the database from the application directory, use the Data Source = |DataDirectory| (enclosed in pipe symbols) substitution string. Use the SetData() method on the AppDomain object to set the application's data directory. DataDirectory is not supported for devices. For more information, see Installing and Deploying on a Desktop (SQL Server Compact)".

Password-or-Pwd-or-database password-or-ssce:database password

The database password, which can be up to 40 characters in length. If not specified, the default value is no password. This property is required if you enable encryption on the database. If you specify a password, encryption is automatically enabled on the database. If you specify a blank password, the database will not be encrypted.

ssce:enlist

or

enlist

By default, enlist value is false. This can be set to true. If a connection to SQL Server Compact database is opened by using Enlist set to true, the connection is promoted to a transaction.

ssce:encryption mode

or

encryption mode

The values for this property are

engine default

or

platform default

The default is platform default.

NoteNote
This property is a database creation time option and is ignored when connecting to an existing database.

Encrypt-or-encrypt database -or-ssce: encrypt database

A Boolean value that determines whether or not the database is encrypted. Must be set to true to enable encryption or false for no encryption. If not specified, the default value is false. If you enable encryption, you must also specify a password with the password property. If you specify a password, encryption is enabled regardless of how you set this property.

NoteNote
This property is a database creation time option and is ignored when connecting to an existing database. If an SSCE:Database password is specified, the database is encrypted regardless of whether SSCE:Encrypt Database is specified.

max buffer size-or-ssce:max buffer size

The largest amount of memory, in kilobytes, that SQL Server Compact can use before it starts flushing changes to disk. If not specified, the default value is 640.

max database size-or-ssce:max database size

The maximum size of the database, in Megabytes. If not specified, the default value is 128.

Mode-or-file mode-or-ssce:mode

The mode to use when opening the database file. For valid values, see the table that follows. If not specified, the default value is 'Read Write'.

default lock timeout-or-ssce: default lock timeout

The default number of milliseconds that a transaction will wait for a lock. If not specified, the default value is 2000.

default lock escalation-or-ssce:default lock escalation

The number of locks a transaction will acquire before attempting escalation from row to page, or from page to table. If not specified, the default value is 100.

flush interval-or-ssce:flush interval

Specified the interval time (in seconds) before all committed transactions are flushed to disk. If not specified, the default value is 10.

autoshrink threshold-or-ssce:autoshrink threshold

The percent of free space in the database file that is allowed before autoshrink begins. A value of 100 disables autoshrink. If not specified, the default value is 60.

temp path-or-temp file directory-or-ssce:temp file directory

The location of the temporary database. If not specified, the default is to use the database specified in the data source property for temporary storage.

temp file max size

The maximum size of the temporary database file, in Megabytes. If not specified, the default value is 128.

persist security info

When set to false (which is strongly recommended), security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state. Resetting the connection string resets all connection string values, including the password. The default value is false.

locale identifier-or-Lcid-or-initial lcid

The locale ID (LCID) to use with the database. Valid LCID values are listed in the CultureInfo class.

NoteNote
This property is a database creation time option and is ignored when connecting to an existing database.

Case Sensitive-or-CaseSensitive

A Boolean value that determines whether or not the database collation is case-sensitive. Must be set to true to enable case-sensitive collation or false for case-insensitive collation. If not specified, the default value is false. If you connect to an existing SQL Server Compact database with a "Case Sensitive" property in the connection string, the SQL Server Compact 3.5 SP1 ignores this setting.

NoteNote
This property is a database creation time option and is ignored when connecting to an existing database.

The following table shows valid values for the mode property of the connection string.

Value

Definition

Read Write

Allows multiple processes to open and modify the database. This is the default setting if the mode property is not specified.

Read Only

Allows you to open a read-only copy of the database.

Exclusive

Does not allow other processes from opening or modifying the database.

Shared Read

Allows other processes to read, but not modify, the database while you have it open.

A preliminary validation of the connection string is performed when the property is set. When an application calls the Open method, the connection string is fully validated. If the connection string contains properties that are unsupported or not valid, a run-time exception, such as ArgumentException, is generated at that time.

The following rules apply to connection strings:

  1. All blank characters, except those placed within a value or within quotation marks, are ignored.

  2. Keyword value pairs must be separated by a semicolon (;). If a semicolon is part of a value, it also must be delimited by quotation marks.

  3. No escape sequences are supported.

  4. The value type is irrelevant.

  5. Names are not case-sensitive.

  6. If a property name occurs more than once in the connection string, the value associated with the last occurrence is used.

  7. Values can be delimited by single or double quotation marks, (for example, name='value' or name="value"). Either single or double quotation marks can be used within a connection string by using the other delimiter. For example, the following are valid uses of quotation marks within a connection string:

    "data source='MyDb.sdf'; mode=Exclusive;"
    'data source="MyDb.sdf"; mode=Exclusive;'
    

    But these examples are not valid:

    "data source="MyDb.sdf"; mode=Exclusive;"
    'data source='MyDb.sdf'; mode=Exclusive;'
    

Examples

The following example creates a SqlCeConnection and sets some of its properties in the connection string.

Dim conn As New SqlCeConnection()

' Set some connection string properties e.g.:
' 
conn.ConnectionString = _
    "Persist Security Info = False; Data Source = 'SalesData.sdf';" & _
    "Password = '<password>'; File Mode = 'shared read'; " & _
    "Max Database Size = 256; Max Buffer Size = 1024"

conn.Open()

' You can change the database while preserving 
' the orignal connection options
'
conn.ChangeDatabase("SupportData.sdf")
SqlCeConnection conn = new SqlCeConnection();

// Set some connection string properties e.g.:
// 
conn.ConnectionString = 
    "Persist Security Info = False; Data Source = 'SalesData.sdf';" +
    "Password = '<password>'; File Mode = 'shared read'; " +
    "Max Database Size = 256; Max Buffer Size = 1024";

conn.Open();

// You can change the database while preserving 
// the orignal connection options
//
conn.ChangeDatabase("SupportData.sdf");

See Also

Reference

SqlCeConnection Class

System.Data.SqlServerCe Namespace

Other Resources

Upgrading from Earlier Versions (SQL Server Compact)