The Sandboxed File Access Model
Unlike a traditional Win32 desktop app, a UWP app cannot open an arbitrary path like C:\Users\name\Documents\report.docx directly with File.Open. Every file operation is mediated by the Windows.Storage API and a separate broker process that runs outside the app's sandbox. Instead of raw string paths, code works with StorageFile and StorageFolder objects — opaque handles that represent a specific, already-authorized file or folder, obtained either from a known folder, a picker, or a previously cached access token.
Cricket analogy: Like a stadium groundskeeper who can't just wander onto the pitch whenever they like — every entry goes through the curator's office, which issues a specific pass for a specific patch of turf, similar to how UWP apps must go through the storage broker rather than touching raw paths.
Known Folders and Pickers
KnownFolders such as PicturesLibrary, MusicLibrary, and DocumentsLibrary give pre-authorized access to standard library locations, but each still requires the matching manifest capability (picturesLibrary, musicLibrary, documentsLibrary) to be declared. For anything outside those declared libraries, apps use FileOpenPicker or FileSavePicker, which show broker-owned system UI that runs outside the app's process; whatever the user explicitly selects there is granted to the app for that session, regardless of whether the app declared any library capability at all.
Cricket analogy: Like a member enjoying automatic access to the players' pavilion because their club membership already covers it, a known folder with declared capability, versus a walk-in fan who's individually escorted in by a steward for one match only, picker-granted access.
Reading and Writing with StorageFile
Once a StorageFile is obtained, the FileIO helper class provides async methods like ReadTextAsync and WriteTextAsync, while StorageFile.OpenAsync gives lower-level stream access for binary data. Every one of these calls returns an IAsyncOperation that must be awaited; because the broker process actually performs the disk I/O out-of-process, treating these calls as synchronous will either deadlock the UI thread or produce code that appears to work but silently races ahead of the actual write. For files that sync via OneDrive or another cloud provider, CachedFileManager.DeferUpdates should wrap the write to avoid corrupting an in-flight sync.
Cricket analogy: Like a scorer who must wait for the over to actually finish before updating the scorebook — you can't read the final tally mid-delivery, just as ReadTextAsync must be awaited before the file content is actually available.
async Task<string> ReadNotesAsync()
{
StorageFolder folder = KnownFolders.DocumentsLibrary;
StorageFile file = await folder.GetFileAsync("notes.txt");
string contents = await FileIO.ReadTextAsync(file);
return contents;
}
async Task SaveNotesAsync(StorageFile file, string text)
{
CachedFileManager.DeferUpdates(file);
await FileIO.WriteTextAsync(file, text);
var status = await CachedFileManager.CompleteUpdatesAsync(file);
if (status != FileUpdateStatus.Complete)
{
// notify user the save to a cloud-synced location may not have completed
}
}Persisting Access with the Future Access List
Access granted through a picker is normally session-scoped — close the app and the token is gone, forcing the user to pick the same file again next launch. StorageApplicationPermissions.FutureAccessList lets an app add a StorageFile or StorageFolder with a string token, then retrieve it by that same token in a future session using GetFileAsync, entirely skipping the picker. Each app can cache up to 1,000 items this way, and entries should be explicitly removed with Remove when no longer needed, since stale tokens can silently fail to resolve if the underlying file has been moved or deleted.
Cricket analogy: Like a stadium issuing a season-long access pass to a specific commentator after their first successful accreditation, so they don't have to re-apply before every single match — the FutureAccessList token works the same way for a previously picked file.
The Future Access List and Most Recently Used List each cap out at 1,000 entries per app. Older entries are not automatically evicted, so long-running apps that repeatedly add new tokens without calling Remove on stale ones can silently hit the cap and fail to persist new access — periodically pruning unused tokens is good practice.
- UWP apps never touch raw file-system paths directly; every file operation goes through StorageFile/StorageFolder and a broker process.
- KnownFolders (PicturesLibrary, DocumentsLibrary, etc.) require both a matching manifest capability and are pre-authorized once declared.
- FileOpenPicker and FileSavePicker grant access to any user-chosen file outside declared libraries, via explicit user action, regardless of manifest capabilities.
- FileIO.ReadTextAsync/WriteTextAsync and StorageFile.OpenAsync are all asynchronous and must be awaited.
- CachedFileManager.DeferUpdates protects writes to cloud-synced files like OneDrive documents from racing an in-flight sync.
- StorageApplicationPermissions.FutureAccessList persists picker-granted access across app sessions using a string token, up to 1,000 items.
- Stale Future Access List tokens should be removed explicitly since they can silently fail to resolve if the underlying file moves or is deleted.
Practice what you learned
1. Why can't a UWP app open a file using a raw path like C:\Users\name\file.txt directly?
2. What is required to get pre-authorized access to the Pictures library via KnownFolders.PicturesLibrary?
3. What does StorageApplicationPermissions.FutureAccessList allow an app to do?
4. Why should CachedFileManager.DeferUpdates be used when writing to a file in a OneDrive-synced folder?
5. How many items can the Future Access List cache per app?
Was this page helpful?
You May Also Like
UWP App Capabilities
How Universal Windows Platform apps declare and request access to system resources like the microphone, location, and internet through capability declarations in the app manifest.
UWP Background Tasks
How Universal Windows Platform apps run code while suspended or not in the foreground, using triggers, conditions, and a constrained execution model.
UWP Notifications and Tiles
How Universal Windows Platform apps surface toast notifications and live tile updates to keep users informed, both locally and via push.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics
Microsoft TechnologiesMVVM Design Pattern Study Notes
.NET · 30 topics