Windows.Storage API

The Windows.Storage namespace provides types that enable you to access and manage files and folders on the user's device. This includes local storage, app-specific data folders, and user-selected locations.

Overview

Accessing files and folders in a Universal Windows Platform (UWP) app is a fundamental operation. The Windows.Storage namespace offers a consistent and safe way to interact with the file system, adhering to UWP's security and privacy model.

Key concepts include:

StorageFolder: Represents a folder. You can get a StorageFolder for the current app's installation location, its data folders, or folders picked by the user.
StorageFile: Represents a file. You can get a StorageFile from a StorageFolder or by picking a file.
Access Permissions: UWP apps operate within a sandbox. Access to files and folders is granted through capabilities defined in the app's manifest and user-initiated file/folder picks.
Asynchronous Operations: Most file operations are asynchronous to avoid blocking the UI thread.

Common Scenarios

Accessing App Data Folders

Your app has dedicated folders for storing its data, such as settings, cached information, or user-generated content.

Example: Get App Local Folder


using Windows.Storage;

async Task GetAppLocalFolder()
{
    StorageFolder localFolder = ApplicationData.Current.LocalFolder;
    // Now you can interact with localFolder, e.g., create files, subfolders
    // var file = await localFolder.CreateFileAsync("mydata.txt", CreationCollisionOption.ReplaceExisting);
    System.Diagnostics.Debug.WriteLine($"Local folder path: {localFolder.Path}");
}

Creating and Reading Files

You can create new files or open existing ones to read or write data.

Example: Create and Write to a File


using Windows.Storage;
using System.Text;

async Task CreateAndWriteToFile()
{
    StorageFolder folder = ApplicationData.Current.LocalFolder;
    StorageFile sampleFile = await folder.CreateFileAsync("sample.txt", CreationCollisionOption.ReplaceExisting);

    await FileIO.WriteTextAsync(sampleFile, "Hello, Windows Storage!");

    System.Diagnostics.Debug.WriteLine($"File '{sampleFile.Name}' created and written successfully.");
}


using Windows.Storage;

async Task ReadFromFile()
{
    StorageFolder folder = ApplicationData.Current.LocalFolder;
    try
    {
        StorageFile sampleFile = await folder.GetFileAsync("sample.txt");
        string content = await FileIO.ReadTextAsync(sampleFile);
        System.Diagnostics.Debug.WriteLine($"Content of 'sample.txt': {content}");
    }
    catch (System.IO.FileNotFoundException)
    {
        System.Diagnostics.Debug.WriteLine("'sample.txt' not found.");
    }
}

Picking Files and Folders

Allow users to select files or folders using the system's file picker.

Example: Pick a Single File


using Windows.Storage;
using Windows.Storage.Pickers;

async Task PickFile()
{
    var picker = new FileOpenPicker();
    picker.ViewMode = PickerViewMode.Thumbnail;
    picker.SuggestedStartLocation = PickerLocationId.DocumentsLibrary;
    picker.FileTypeFilter.Add(".txt");
    picker.FileTypeFilter.Add(".docx");

    StorageFile file = await picker.PickSingleFileAsync();
    if (file != null)
    {
        // User picked a file
        System.Diagnostics.Debug.WriteLine($"Picked file: {file.Name}");
        // You can now open and process the file
    }
    else
    {
        // User cancelled the picker
        System.Diagnostics.Debug.WriteLine("File picker cancelled.");
    }
}

API Reference

Key Classes and Interfaces

Name	Description
`StorageFolder`	Represents a folder in the file system.
`StorageFile`	Represents a file in the file system.
`FileIO`	Provides static methods for reading and writing file content.
`KnownFolders`	Provides access to well-known folders like Documents, Pictures, and Music.
`StorageLibrary`	Represents a user's library (e.g., Documents library).
`FilePicker` (`FileOpenPicker`, `FileSavePicker`)	Provides UI for users to select files to open or save.

Permissions

Ensure you declare necessary capabilities in your app's Package.appxmanifest file, such as Documents Library, Pictures Library, etc., if you intend to access these broader storage areas. For app-specific data, no special capabilities are typically needed beyond the default sandbox.

Best Practices

Always use asynchronous methods for I/O operations.
Handle exceptions gracefully, especially for file not found or access denied scenarios.
Provide clear user feedback when file operations are in progress or completed.
Respect user privacy and only access data that is necessary for your app's functionality.