09 data storage, backup and roaming

Matthias Shapiro @matthiasshapAndy Wigley @andy_wigley

Data Storage, Backup and Roaming

Windows XAML

29 April 2014

Building Apps for Windows Phone 8.1 Jump Start

2

Data Storage and Data Roaming• Local Settings• Roaming files and settings• The Windows Storage API• Serializing objects using the XML and Json serializers• Using Compression• Using the SD Card to store application data• Known Folders

This module… (50 minutes)

3

App Data Locations

Locations where apps can access data

App

Installation Folder

r/o

App data Folders

r/wApp data FoldersApp data

Folders

Local

RoamingTemp

SD Cardr/w

Known Folders

PicturesVideosMusic- Direct access needs manifest capabilities

r/w

Networks

r/w

File Syste

m

File Picker APIs

r/w

Credential Locker

r/wB/ground Transfer

App Data Storage: Overview

• Package Manager installs all app files into the Installation Folder

• Read-only access from app

• Read-only reference database

• Apps store data in Local Folder

• Settings and properties in the app dictionary

• Unstructured data in Isolated Storage files

• Structured data in database files

Local or Roaming

Settings File

App Creates/Managesfiles and settings

ApplicationFiles

App Data Folder

Creates root folder

sandboxed to App

Package Manager

Installation Folder

WinRT Storage APIs

Install

DB

Database file

DB Files (r/o)

Data Storage Areas

Roaming

FolderSettin

gs

• Other devices can access what you put in here

• Data roamed cross-device

• Limited to 100kb per application

• Held in OneDrive storage

Local

FolderSetting

s

• Store local data here for use by your application

• Can store data up to the limit of the storage on the device

• Retained if the application is updated

Temp

Folder

• Use for temporary storage

• No guarantee it will still be here next time your program runs

• Cleaned up in a low storage condition

Windows.Storage.ApplicationData Windows.Security.Credentials

PasswordVault

Credentials

• Credential Locker• Use for secure

storage of PasswordCredential objects

• Data roamed cross-device

7

Windows.Storage.ApplicationDataThis namespace provides access to the three storage folders in the app data store and the application settings containers:

Windows.Storage.StorageFolder roam = Windows.Storage.ApplicationData.Current.RoamingFolder; Windows.Storage.StorageFolder local = Windows.Storage.ApplicationData.Current.LocalFolder; Windows.Storage.StorageFolder temp = Windows.Storage.ApplicationData.Current.TemporaryFolder;

Windows.Storage.ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings; Windows.Storage.ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;The StorageFolder object represents a folder and is used to access the folder and its contents The ApplicationDataContainer object represents a key-value pair settings dictionary

8

Local and Roaming Settings

9

Local Settings

// Create a simple setting localSettings.Values["exampleSetting"] = "Hello Windows";

// Read data from a simple setting Object value = localSettings.Values["exampleSetting"];

if (value == null) { // No data } else { // Access data in value }

// Delete a simple setting localSettings.Values.Remove("exampleSetting");

10

Roaming Settings and the Roaming FolderIf a user obtains your application and installs it on multiple devices it is nice if all the devices can share the same settings informationChanges on one device are reflected on all the other devices owned by that userRoaming data is shared between Windows Phone 8.1 Store Apps and Windows 8.1 Store Apps that have the same Package Family Name (PFN)

Roaming data provides a way that an application can synchronise data and/or settings across a number of different physical devicesIt takes the form of a folder and a settings dictionary which are automatically stored in the users’ OneDrive• Roaming data is limited to value of ApplicationData.RoamingStorageQuota

(usually 100KB) but do not count against the users’ OneDrive quote• If your roaming data exceeds the quota, it won’t roam until its size is less than the

quota again

11

Roaming Data

WP 8.1 App – PFN 12345

Roaming

Local Temp

Windows App – PFN 12345

Roaming

LocalTemp

PFN 12345

Roamingfolder

App writes data using standard file/settings APIs.

Sync engine transfers data periodically based on triggers (user idle, battery, network, etc.)

OneDrive stores up to 100kb of roaming data per app (not included in user quota). If app exceeds the limit, sync stops.

Other clients are notified of updated data via Windows Notification Service. If app is running when sync occurs, an event is raised.

Roamingsettings

12

Using the Roaming settings

The RoamingSettings are exposed as a dictionary into which an application can save dataThe data is persisted on the device and also shared with other devices

Note: On Windows 8.1, there is a special HighPriority setting. This has no effect on Windows Phone.

private void name_TextChanged(object sender, TextChangedEventArgs e){ Windows.Storage.ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings; roamingSettings.Values["userName"] = name.Text;}

13

Reading the Roaming settings

This code queries the roaming settings by using the key nameThe name will be reflected across multiple devices (including Windows 8.1 ones)

Windows.Storage.ApplicationDataContainer roamingSettings = Windows.Storage.ApplicationData.Current.RoamingSettings;

if (roamingSettings.Values.ContainsKey("userName")){ name.Text = roamingSettings.Values["userName"].ToString();}

14

Receiving notification when roaming data changesThe DataChanged event fires when the roaming data has changedWindows.Storage.ApplicationData.Current.DataChanged += Current_DataChanged;...

void Current_DataChanged(ApplicationData sender, object args){ // Refresh your settings...}

The event is only fired if the application is active at the time of the changeYou should still load up all your data when your app starts

15

Tips on using roaming dataApplications can store data in the roaming folder as they would any other folder on the device, or in roaming settings in the same way as local settingsThe synchronisation takes place in the backgroundGood for app customisation settings, most recent activity, partially completed workBad for synchronising large amounts of data or “instant syncing” scenariosLast writer winsHighPriority setting is available on Windows for quick sync, but has no effect on Windows Phone

16

Debugging apps using the Roaming Folder

Developers can install an application on multiple unlocked devicesYou can debug the roaming folder with a device connect to your PCLocking a developer device will trigger the synchronisation If you have problems:Make sure that files are closed correctlyMake sure that the devices are running the same version of the application

17

Roaming Settings

demo

18

File Access

Different Methods For Addressing Storage LocationsFile Type/ API

Installation Folder App data folder Example

File access using Windows.Storage API via URIs

ms-appx:///

ms-appdata:///local/ms-appdata:///roaming/ms-appdata:///temp/

var file = await Windows.StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appdata:///local/AppConfigSettings.xml"));

File access using Windows.Storage API via StorageFolder references

Windows.ApplicationModel.Package.Current.InstalledLocation

Windows.Storage.ApplicationData.Current.LocalFolder /.RoamingFolder /.TempFolder

var localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;

Windows.Storage.StorageFile storageFile = await localFolder.GetFileAsync("CaptainsLog.store");

20

Writing a complete file

private async void writeTextToLocalStorageFile(string filename, string text) { StorageFolder fold = Windows.Storage.ApplicationData.Current.LocalFolder; StorageFile file = await fold.CreateFileAsync(filename, CreationCollisionOption.ReplaceExisting);

await FileIO.WriteTextAsync(file, text); }

This method will create a file from a string of textAll the file operations are asynchronous Sets the

target folder

Sets action if file

already exists

21

Reading a complete file

private async Task<string> readTextFromLocalStorage(string filename) { var fold = Windows.Storage.ApplicationData.Current.LocalFolder; StorageFile file = await fold.GetFileAsync(filename); string result = await FileIO.ReadTextAsync(file); return result; }

This method will read a file into a string

Writing a Complete File

demo

23

Using Streams

As well as writing a complete file in one action using the FileIO API, you can also create a stream and write to thisThe read and write operations are asynchronousStreams handle the difference in latency between one type of storage (e.g. memory) and another (e.g. network or file system)Streams are used all over WinRT

24

Writing to a file using a Stream private async void WriteToStreamButton_Click(object sender, RoutedEventArgs e) { StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder; StorageFile file = await localFolder.CreateFileAsync("JumpStart.txt");

string userContent = InputTextBox.Text; if (!String.IsNullOrEmpty(userContent)) { using (StorageStreamTransaction transaction = await file.OpenTransactedWriteAsync()) { using (DataWriter dataWriter = new DataWriter(transaction.Stream)) { dataWriter.WriteString(userContent); transaction.Stream.Size = await dataWriter.StoreAsync(); // reset stream size to override the file

await transaction.CommitAsync(); } } } }

Using a Stream

demo

26

Using XML and JSON serilializers

27

Storing Objects

We have seen that it is easy to read and write settings and blocks of textHowever it is also useful to be able to store objectsThe serialization libraries in Windows Phone make it very easy to persist structured data using serialisationAn application can serialise data into XML or JSON formatsThe data will be stored or transferred as text

28

Serialization Rules

XML Serializer requires that the object must have a parameterless constructor Private and static members of the class will not be persistedBe careful of app upgrades: If you add members to the class in an app update and restore from a data file that was created by serializing using the previous class definition, you will have problems

29

Using a Serializer

using (Stream stream = await notesFolder.OpenStreamForWriteAsync(filename, CreationCollisionOption.OpenIfExists)){ DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(Customer[]));

serializer.WriteObject(stream, customers);}

This code serializes a collection of customers

30

Using a Serializer

using (Stream stream = await notesFolder.OpenStreamForWriteAsync(filename, CreationCollisionOption.OpenIfExists)){ DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(Customers));

serializer.WriteObject(stream, customers);}

This creates the serializer The constructor is given the type of the object to store

31

Using a Serializer

using (Stream stream = await notesFolder.OpenStreamForWriteAsync(filename, CreationCollisionOption.OpenIfExists)){ DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(Customers));

serializer.WriteObject(stream, customers);}

This writes the collection of customers to the output stream

32

Deserializing the data

using (Stream stream = await notesFolder.OpenStreamForReadAsync(filename)){ DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(Customers));

Customers result = serializer.ReadObject(stream) as Customers;}

The read process is the reverse of the writing oneNote that we have to cast the result of ReadObject(Stream) to the required type

33

XML Serialization

This is how you save to an XML format file

This is how you load from an XML format file

XmlSerializer serializer = new XmlSerializer(typeof(Customers));

serializer.Serialize(stream, customers);

XmlSerializer serializer = new XmlSerializer(typeof(Customers));

Customers result = serializer.Deserialize(stream) as Customers;

34

Compression

35

Using Windows.Storage.Compression.Compressorvar s = await destFile.OpenAsync(FileAccessMode.ReadWrite);

Compressor compressor = new Compressor(s.GetOutputStreamAt(0), CompressAlgorithm.Mszip, 0);

An application can use compression when it saves and loads dataThe compression stream can be used as any other stream, but it compresses the data as it is transferred

36

Compression Algorithms

var s = await destFile.OpenAsync(FileAccessMode.ReadWrite);

Compressor compressor = new Compressor(s.GetOutputStreamAt(0), CompressAlgorithm.Mszip, 0);

There are a number of different algorithms available:LzmsMszipXpressXpressHuff

You can also set the block size for the compression, the value 0 means use the default

37

Using Decompressor

var s = await destFile.OpenAsync(FileAccessMode.ReadWrite);

Compressor compressor = new Compressor(s.GetOutputStreamAt(0), CompressAlgorithm.Mszip, 0);

The Decompressor complements the Compressor and provides an input stream that can be used to decompress files

Credential Lockersecurely store and roam user credentials

Overview

APIs to store credentials (user name, password) securelyWindows.Security.Credentials

Benefits:Secure storageCredential isolationRoaming

Apps can only access their own credentials

Isolation

App A

CredentialLocker

App B

App Sandbox Boundary

RoamingCredentials roam across trusted devices

MSAApp

App

Credential Locker sample

void SaveCredential(string username, string password) { PasswordVault vault = new PasswordVault(); PasswordCredential cred = new PasswordCredential("MyAppResource", username, password); vault.Add(cred); }

IReadOnlyList<PasswordCredential> RetrieveCredential(string resource) { PasswordVault vault = new PasswordVault(); return vault.FindAllByResource(resource); }

Credential Locker

demo

43

44

Known Folders

45

KnownFoldersKnownFolders is an API which simplifies the view the developer has of accessible user data on the phoneRather than searching through all the possible different locations on the device for a particular type of file a program can request a single list of all the files This includes files on the SD card (if inserted) along with files held on the device

Files in KnownFolders are visible to all apps (that have registered the proper capabilities)

Consider using the FileOpenPicker API as an alternative to allow users to select a file in these foldersNo capabilities required as consent is impliedCovered in Session 10

KnownFoldersPhysical View Logical View

C:\Users\Public\Pictures\Seattle\

D:\Pictures\Portland\

D:\Pictures\Birthday\

C:\Users\Public\Pictures\Birthday\C:\Users\Public\Pictures\Pic01.jpg

D:\Pictures\Pic01.jpg

Internal storage

SD Card (if present)

KnownFolders.PicturesLibrary.GetFilesAsync()

D:\Pictures\Pic02.jpg

D:\Pictures\Hawaii\Pic02.jpg

StorageFile: Pic01.jpg

StorageFile: Pic01.jpg

StorageFile: Pic02.jpg

47

KnownFolders provides access to:PicturesVideosMusic

Accessing User Contentvar pictures = await Windows.Storage.KnownFolders.PicturesLibrary.GetFilesAsync();

Accessing Known Folders

demo

49

Using the SD Card

50

The SD Card in Windows Phone 8.1Phone applications now have read/write access to the SD CardApps can store their own files and also make use of files already on the cardThis makes it possible for applications to share data amongst themselves

There is full SD Card support provided by the emulatorMaps to a local folder on your PC

Because SD cards represent a “shared” resource, the application must declare file associations in the manifest for each file type it wants to access

51

Setting SD card capabilitiesBefore an app can use the SD card you need to set some capabilitiesRemovable Storage

If you are using KnownFolders API, you may also need:Pictures LibraryVideos LibraryMusic Library

If these capabilities are not set the program will throw an exception when it runs

52

Applications and file associationsA given application is not able to work with just any type of file stored on the SD cardAn application must declare associations with the file types that it works withAn image processing program will work with files such as .jpg, .png, etcA sound processing program will work with .mp3 filesYou can add your own custom file types for your particular application if you wish

The associations are set in the manifest

Note that this is not required for applications accessing files in their own local/roaming/temporary storageThis is the same mechanism used for app-to-app communications through file associations (See Session 10)

53

Setting file associations for your applicationThe manifest for your application must specify the file types that are associated with itIt will only be able to open files with that typeThis application can only work with .txt files

54

Getting an SD Card

var devices = Windows.Storage.KnownFolders.RemovableDevices;var sdCards = await devices.GetFoldersAsync();if (sdCards.Count == 0) return;StorageFolder firstCard = sdCards[0];

These statements get a reference to the SD card on the phoneThey are part of a method that creates a file on the SD cardThis method is part of the demo software we will be running later

55

Getting an SD Card

var devices = Windows.Storage.KnownFolders.RemovableDevices;var sdCards = await devices.GetFoldersAsync();if (sdCards.Count == 0) return;StorageFolder firstCard = sdCards[0];

We get a list of SD cards using the KnownFolders APIThere will only be 0 or 1

56

Getting an SD Card

var devices = Windows.Storage.KnownFolders.RemovableDevices;var sdCards = await devices.GetFoldersAsync();if (sdCards.Count == 0) return;StorageFolder firstCard = sdCards[0];

If there is not one present the value of the Count property will be 0This method returns if there are no SD Cards on the deviceYour application must handle this eventuality gracefullyNot all devices have an SD card slotThe slot might not have a card fitted into it

57

Getting an SD Card

var devices = Windows.Storage.KnownFolders.RemovableDevices;var sdCards = await devices.GetFoldersAsync();if (sdCards.Count == 0) return;StorageFolder firstCard = sdCards[0];

The card is exposed as a StorageFolder, so we can use it in the same way the previous devices we have seen We can create folders and filesBut we can only work with files types for which we have declared a file association in the manifest

58

Inserting an SD card in the emulator

The emulator provides support for SD cardsYou just map it to the folder that you are going to use When you press the Insert SD Card the emulator behaves exactly as if a card has been inserted into the phone

59

SD Cards in the Emulator

The emulator will create the Documents, Music, Pictures and Videos folders in your SD card folder if they are not already presentIt can also use media from the folderThis is a great way to get your content in the emulator for testing

60

Ejecting an SD Card from the emulator

You can also eject an SD cardWrites to the card may be synchronised when the card is ejectedThere is an option to select this

We will use the SD card in the next section

Reading and Writing Json using the SD card storage

demo

©2014 Microsoft Corporation. All rights reserved. Microsoft, Windows, Office, Azure, System Center, Dynamics and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.