Local database connection strings for Windows Phone 8
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
Windows Phone apps can use LINQ to SQL to store relational data in a local database. This topic describes the supported connection string parameters that you can use with a local database in your app. For more information about using a local database, see Local database for Windows Phone 8.
This topic contains the following sections.
- Using connection strings
- Supported properties
- Examples
- Related Topics
Using connection strings
Before the database is created, a connection string can be used to specify database configuration values. For example, the connection string can specify whether the database should be encrypted and password-protected.
In a connection string, individual parameters are separated by semicolons and parameter values are placed within single quotes. Some parameters are applicable only to creating the database; after the database has been created, those parameters are ignored.
Supported properties
The following table lists all of the supported parameters for local database connection strings.
Parameter |
Description |
|---|---|
data source or datasource |
The file path and name of the local database file. When this is the only connection string property specified, only the value of the property is required to instantiate a data context object. For more information about a data context, see Local database for Windows Phone 8. Use the following prefixes to explicitly specify the root location of the path:
When a prefix is not specified, the file path is applied to the local folder. |
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. .jpeg "Note") Note:
You cannot encrypt a database after it has been created.
The database is encrypted using AES-128 and the password is hashed using SHA-256. To encrypt select data, rather than the entire database, see How to encrypt data for Windows Phone 8. |
max buffer size or ssce:max buffer size |
The largest amount of memory, in kilobytes, that a local database can use before it starts flushing changes to disk. If not specified, the default value is 384. The maximum value is 5120. |
max database size or ssce:max database size |
The maximum size of a local database, in megabytes. If not specified, the default value is 32. The maximum value is 512. |
Mode or file mode or ssce:mode |
The mode to use when opening the database file. The following values are valid:
.gif "Important note") Important Note:
Starting with Windows Phone 8, the Read Only parameter value is supported only with the installation folder.
|
Culture Identifier |
The culture code to use with the database. For example, en-US for United States English. For the full list of supported culture codes in Windows Phone OS 7.1, see Culture and language support for Windows Phone. Note:
This property is ignored if used 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. Note:
This property is ignored if used when connecting to an existing database.
|
| Important Note: |
|---|
Some Microsoft SQL Compact connection string parameters may work in this release of the Windows Phone app platform. We do not recommend using any connection string parameters that are not listed in this topic. |
Examples
The following examples demonstrate how to use a connection string with a local database.
Single parameter usage
If you are only using the data source property, you do not need to include the property name in the connection string, as shown in the following example.
// Create the data context.
MyDataContext db = new MyDataContext ("isostore:/mydb.sdf")
In this example, the isostore prefix indicates that the file is located in the local folder.
Reading from the installation folder
The installation folder does not support write operations. When connecting to a local database there, you must use the File Mode property to specify the connection as read-only. The following example demonstrates how to make a read-only connection to the installation folder.
// Create the data context.
MyDataContext db = new MyDataContext("Data Source = 'appdata:/mydb.sdf'; File Mode = read only;");
| Important Note: |
|---|
We do not recommend encrypting your reference database file if you are going to access it exclusively from the installation folder. Doing so prevents the system from performing routine database maintenance operations, such as re-indexing, upon the first connection. To use an encrypted reference database, copy it to the local folder before first use and then connect to it with a read-write connection. For more information about how to copy it, see How to deploy a reference database with an app for Windows Phone 8. |
Creating an encrypted database
If you want an encrypted database, you must specify a password with the connection string before the database has been created. In this example, a password is specified before the database is created.
// Create the data context.
MyDataContext db = new MyDataContext("Data Source='isostore:/mydb.sdf';Password='securepassword';");
// Create an encrypted database after confirming that it does not exist.
if (!db.DatabaseExists()) db.CreateDatabase();
To encrypt select data, rather than the entire database, see How to encrypt data for Windows Phone 8.
Creating a database with a specific culture
In this example, a database that has a German culture and a case-sensitive collation is created.
// Create the data context.
MyDataContext db = new MyDataContext("Data Source = 'mydb.sdf'; Culture Identifier = de-de; Case Sensitive = true;");
// Create a database after confirming that it does not exist.
if (!db.DatabaseExists()) db.CreateDatabase();
See Also
Other Resources
How to use the Isolated Storage Explorer tool for Windows Phone 8