Quickstart: Working with settings for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This Quickstart covers how to work with settings in your Windows Phone app. Settings are key/value pairs that are saved in your app’s local folder.

To save or retrieve data as a key/value pair, you use the IsolatedStorageSettings class which is a dictionary that enables you to store objects, such as strings. IsolatedStorageSettings is ideally suited for saving small pieces of data, such as settings, when the app loads and exits. Two scenarios where this is common are when an app is started or stopped by the user, and when an app is tombstoned.

This topic contains the following sections.

• Settings API overview
• Setting example UI
• Adding a setting
• Reading a setting
• Removing a setting
• Related Topics

Settings API overview

A key-value pair consists of a unique key identifier and an associated data value as found in hash tables.IsolatedStorageSettings is a dictionary class used to save or retrieve data as key/value pairs. You can store any serializable object in this dictionary with a string key. Data stored with this class are persisted in the local folder after your app is closed or deactivated and automatically populated with previously persisted data when the app is launched. The IsolatedStorageSettings class is ideally suited for saving small pieces of data, such as apps that require access to settings at load time or when exiting. Two scenarios where this is common are when an app is started or stopped by the user, and when an app is tombstoned.

The following IsolatedStorageSettings methods are typically used to manage data:

Setting example UI

The following image shows a sample app that adds, retrieves, and removes a key/pair value from the local folder.

To create this UI, in the MainPage.xaml file, replace the Grid named ContentPanel with the following XAML.

<!--ContentPanel - place additional content here-->
<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <TextBox Height="72" HorizontalAlignment="Left" Margin="12,6,0,0" Name="txtInput" 
      Text="INPUT DATA" VerticalAlignment="Top" Width="438" />
    <Button Content="Save Data" Height="72" HorizontalAlignment="Left" Margin="125,84,0,0" 
      Name="btnSave" VerticalAlignment="Top" Width="216" Click="btnSave_Click" />
    <Button Content="Display Data" Height="72" HorizontalAlignment="Left" Margin="125,174,0,0" 
      Name="btnDisplay" VerticalAlignment="Top" Width="216" Click="btnDisplay_Click" />
    <Button Content="Remove Data" Height="72" HorizontalAlignment="Left" Margin="125,266,0,0" 
      Name="btnRemove" VerticalAlignment="Top" Width="216" Click="btnRemove_Click" />

    <TextBlock Height="60" HorizontalAlignment="Left" Margin="25,422,0,0" Name="txtDisplay" 
      Text="USER DATA:" VerticalAlignment="Top" Width="395" />
</Grid>

Adding a setting

The following example demonstrates how to create a key/value pair. An instance of the IsolatedStorageSettings is created from the ApplicationSettings property. A key named "userData" is created in the dictionary. The value of "userData" is set to the Text property of a TextBox. Finally, the settings are saved by using the Save method.

private void btnSave_Click(object sender, RoutedEventArgs e)
{
    IsolatedStorageSettings settings = IsolatedStorageSettings.ApplicationSettings;
    // txtInput is a TextBox defined in XAML.
    if (!settings.Contains("userData"))
    {
        settings.Add("userData", txtInput.Text);
    }
    else
    {
        settings["userData"] = txtInput.Text;
    }
    settings.Save();
}

Private Sub btnSave_Click(sender As Object, e As RoutedEventArgs)
   Dim settings As IsolatedStorageSettings = IsolatedStorageSettings.ApplicationSettings
   ' txtInput is a TextBox defined in XAML.
   If Not settings.Contains("userData") Then
      settings.Add("userData", txtInput.Text)
   Else
      settings("userData") = txtInput.Text
   End If
   settings.Save()
End Sub

Reading a setting

The following example demonstrates how to retrieve data from a key/value pair. Access to the key/value pair is gained directly from the ApplicationSettings property. The Text property of a TextBlock is set to the value of the "userData" key.

private void btnDisplay_Click(object sender, RoutedEventArgs e)
{
    // txtDisplay is a TextBlock defined in XAML.
    txtDisplay.Text = "USER DATA: ";
    if (IsolatedStorageSettings.ApplicationSettings.Contains("userData"))
    {
        txtDisplay.Text +=
        IsolatedStorageSettings.ApplicationSettings["userData"] as string;
    }
}

Private Sub btnDisplay_Click(sender As Object, e As RoutedEventArgs)
   ' txtDisplay is a TextBlock defined in XAML.
   txtDisplay.Text = "USER DATA: "
   If IsolatedStorageSettings.ApplicationSettings.Contains("userData") Then
      txtDisplay.Text += TryCast(IsolatedStorageSettings.ApplicationSettings("userData"), String)
   End If
End Sub

Removing a setting

The following example demonstrates how to remove a key/value pair. Access to the key/value pair is gained directly from the ApplicationSettings property. The "userData" key is removed from the dictionary by using the Remove method.

private void btnRemove_Click(object sender, RoutedEventArgs e)
{
    if (IsolatedStorageSettings.ApplicationSettings.Contains("userData"))
    {
        IsolatedStorageSettings.ApplicationSettings.Remove("userData");
   }
}

Private Sub btnRemoveSetting_Click(sender As Object, e As RoutedEventArgs)
   If IsolatedStorageSettings.ApplicationSettings.Contains("userData") Then
      IsolatedStorageSettings.ApplicationSettings.Remove("userData")
   End If
End Sub

See Also

Other Resources

How to create a settings page for Windows Phone 8