Local database connection strings for Windows Phone 8

Article
05/20/2016

[ 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

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: isostore: path is applied to the local folder (previously known as isolated storage). appdata: path is applied to the installation folder. 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. 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: 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 from the installation folder. 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. 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.

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

Partager via