[This topic is pre-release documentation and is subject to change in future releases of Microsoft Silverlight.]
Using Isolated Storage and Application Settings
Introduction
This QuickStart shows how to use the isolated storage settings feature. The IsolatedStorageSettings class in the System.IO.IsolatedStorage namespace enables each Silverlight-based application to save and retrieve its own collection of key/value pair settings. In addition, a collection is available to contain site-wide settings that are accessible to all Silverlight-based applications in a Web site's domain. The ApplicationSettings and the SiteSettings properties of the IsolatedStorageSettings class return these collections. This Quickstart demonstrates only the application settings.
This QuickStart uses the following scenario, which automates creating default application settings:
-
An XML file on the server describes the application settings to be saved on the client's computer, as provided in the sample profile.xml file.
-
The application uses the DownloadStringAsync method of the WebClient class to download the XML file as a string.
-
The application creates a tree of XML elements from the string by using the XElement class, which is in the System.Xml.Linq namespace. It then enumerates the collection of elements and obtains a key/value pair from each element (using the node's name and value) and saves each pair as an application setting in isolated storage.
This Quickstart shows only how the settings can be downloaded and removed. There are three buttons (Download Settings, Show Settings, and Delete Settings) and a text block to show output.
For more information about isolated storage settings and creating isolated storage files, see I/O and Isolated Storage.
Prerequisites (available from the Silverlight download site):
-
Silverlight version 2 Beta 2.
-
Microsoft Visual Studio 2008.
-
Silverlight Tools Beta 2 for Visual Studio 2008.
This topic also assumes that you have created a basic Silverlight project. (See Creating an Application for Silverlight for instructions.)
To obtain the application settings collection for an application
-
Use the ApplicationSettings property to obtain the collection. This QuickStart obtains the collection as a class-level variable for the Page class.
cs
private IsolatedStorageSettings appSettings = IsolatedStorageSettings.ApplicationSettings;
vb
Private appSettings As IsolatedStorageSettings = IsolatedStorageSettings.ApplicationSettings
To download the XML file from the server
-
Add the following methods to the Page class. These methods show how to call the DownloadStringAsync method and use its asynchronous DownloadStringCompleted event handler.
cs
// Download an XML file from the server.
private void OnClick_DownloadSettings(object sender, RoutedEventArgs e)
{
WebClient client = new WebClient();
client.DownloadStringCompleted += new DownloadStringCompletedEventHandler(client_DownloadStringCompleted);
client.AllowReadStreamBuffering = false;
// The XML file must be a relative URI.
Uri address = new Uri("data/profile.xml", UriKind.Relative);
// Start the download.
client.DownloadStringAsync(address);
}
private void client_DownloadStringCompleted(object sender, DownloadStringCompletedEventArgs e)
{
try
{
outputBlock.Text = "Settings downloaded.";
// Can now process the downloaded string.
SetDefaultSettings(e.Result);
}
catch (SecurityException ex)
{
outputBlock.Text = "Unable to download settings." + ex.Message;
}
}
vb
' Download an XML file from the server.
Private Sub OnClick_DownloadSettings(ByVal sender As Object, _
ByVal e As RoutedEventArgs)
Dim client As New WebClient
AddHandler client.DownloadStringCompleted, AddressOf client_DownloadStringCompleted
'XML file must be a relative URI.
Dim address As Uri = New Uri("data/profile.xml", UriKind.Relative)
' Start the download.
client.DownloadStringAsync(address)
End Sub
Private Sub client_DownloadStringCompleted(ByVal sender As Object, _
ByVal e As DownloadStringCompletedEventArgs)
Try
outputBlock.Text = "Settings downloaded."
' Can now process the downloaded string.
SetDefaultSettings(e.Result)
Catch ex As SecurityException
outputBlock.Text = "Unable to download settings." & vbLf & ex.Message
End Try
End Sub
To create application settings from the XML string
-
Add the following method to the Page class. This method derives key/value pairs from the XML string to set application settings.
cs
// Process the downloaded string.
private void SetDefaultSettings(string xmlString)
{
// Create XML elements from the downloaded string.
XElement xTree = XElement.Parse(xmlString);
// Create an enumerable collection of the elements.
IEnumerable<XElement> elements = xTree.Elements();
// Create an application storage setting for each element.
foreach (XElement el in elements)
{
// Use the index instead of the Add method
// to overwrite any existing key with the same name.
appSettings[el.Name.ToString()] = el.Value.ToString();
}
outputBlock.Text = "Default application settings applied. Click Show Settings to view.";
}
vb
Private Sub SetDefaultSettings(ByVal xmlString As String)
' Create XML elements from the downloaded string.
Dim xTree As XElement = XElement.Parse(xmlString)
' Create an enumerable collection of the elements.
Dim elements As IEnumerable(Of XElement) = xTree.Elements()
' Create an application storage setting for each element.
For Each el As XElement In elements
' Use the index instead of the Add method
' to overwrite any existing key with the same name.
appSettings(el.Name.ToString()) = el.Value.ToString()
Next
outputBlock.Text = "Default application settings applied. Click Show Settings to view."
End Sub
To list and delete application settings
-
Add the following methods to the Page class to show and delete application settings.
cs
private void OnClick_ShowSettings(object sender, RoutedEventArgs e)
{
if (appSettings.Keys.Count > 0)
{
outputBlock.Text = "Current settings:\nKEY VALUE\n";
foreach (KeyValuePair<string, object> kvp in appSettings)
{
outputBlock.Text += String.Format("{0}: {1}\n",
kvp.Key, kvp.Value);
}
}
else
{
outputBlock.Text = "No current settings.";
}
}
private void OnClick_DeleteSettings(object sender, RoutedEventArgs e)
{
if (appSettings.Keys.Count > 0)
{
appSettings.Clear();
outputBlock.Text = "Settings deleted.";
}
else
{
outputBlock.Text = "No settings to delete.";
}
}
vb
Private Sub OnClick_ShowSettings(ByVal sender As Object, ByVal e As RoutedEventArgs)
If appSettings.Keys.Count > 0 Then
outputBlock.Text = "Current settings:" & vbCrLf & "KEY VALUE" & vbCrLf
For Each kvp As KeyValuePair(Of String, Object) In appSettings
outputBlock.Text += String.Format("{0}: {1}", kvp.Key, kvp.Value) & vbCrLf
Next
Else
outputBlock.Text = "No current settings."
End If
End Sub
Private Sub OnClick_DeleteSettings(ByVal sender As Object, ByVal e As RoutedEventArgs)
If appSettings.Keys.Count > 0 Then
appSettings.Clear()
outputBlock.Text = "Settings deleted."
Else
outputBlock.Text = "No settings to delete."
End If
End Sub