File access permissions

Universal Windows Apps (apps) can access certain file system locations by default. Apps can also access additional locations through the file picker, or by declaring capabilities.

The locations that all apps can access

When you create a new app, you can access the following file system locations by default:

Application install directory

The folder where your app is installed on the user's system.

There are two primary ways to access files and folders in your app's install directory:

  1. You can retrieve a StorageFolder that represents your app's install directory, like this:
Windows.Storage.StorageFolder installedLocation = Windows.ApplicationModel.Package.Current.InstalledLocation;
var installDirectory = Windows.ApplicationModel.Package.current.installedLocation;
#include <winrt/Windows.Storage.h>
...
Windows::Storage::StorageFolder installedLocation{ Windows::ApplicationModel::Package::Current().InstalledLocation() };
Windows::Storage::StorageFolder^ installedLocation = Windows::ApplicationModel::Package::Current->InstalledLocation;

You can then access files and folders in the directory using StorageFolder methods. In the example, this StorageFolder is stored in the installDirectory variable. You can learn more about working with your app package and install directory from the App package information sample on GitHub.

  1. You can retrieve a file directly from your app's install directory by using an app URI, like this:
using Windows.Storage;            
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///file.txt"));
Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appx:///file.txt").done(
    function(file) {
        // Process file
    }
);
Windows::Foundation::IAsyncAction ExampleCoroutineAsync()
{
    Windows::Storage::StorageFile file{
        co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{L"ms-appx:///file.txt"})
    };
    // Process file
}
auto getFileTask = create_task(StorageFile::GetFileFromApplicationUriAsync(ref new Uri("ms-appx:///file.txt")));
getFileTask.then([](StorageFile^ file) 
{
    // Process file
});

When GetFileFromApplicationUriAsync completes, it returns a StorageFile that represents the file.txt file in the app's install directory (file in the example).

The "ms-appx:///" prefix in the URI refers to the app's install directory. You can learn more about using app URIs in How to use URIs to reference content.

In addition, and unlike other locations, you can also access files in your app install directory by using some Win32 and COM for Universal Windows Platform (UWP) apps and some C/C++ Standard Library functions from Microsoft Visual Studio.

The app's install directory is a read-only location. You can't gain access to the install directory through the file picker.

Application data locations

The folders where your app can store data. These folders (local, roaming and temporary) are created when your app is installed.

There are two primary ways to access files and folders from your app's data locations:

  1. Use ApplicationData properties to retrieve an app data folder.

For example, you can use ApplicationData.LocalFolder to retrieve a StorageFolder that represents your app's local folder like this:

using Windows.Storage;
StorageFolder localFolder = ApplicationData.Current.LocalFolder;
var localFolder = Windows.Storage.ApplicationData.current.localFolder;
Windows::Storage::StorageFolder storageFolder{
    Windows::Storage::ApplicationData::Current().LocalFolder()
};
using namespace Windows::Storage;
StorageFolder^ storageFolder = ApplicationData::Current->LocalFolder;

If you want to access your app's roaming or temporary folder, use the RoamingFolder or TemporaryFolder property instead.

After you retrieve a StorageFolder that represents an app data location, you can access files and folders in that location by using StorageFolder methods. In the example, these StorageFolder objects are stored in the localFolder variable. You can learn more about using app data locations from the guidance on the ApplicationData class page, and by downloading the Application data sample from GitHub.

  1. For example, you can retrieve a file directly from your app's local folder by using an app URI, like this:
using Windows.Storage;
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appdata:///local/file.txt"));
Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appdata:///local/file.txt").done(
    function(file) {
        // Process file
    }
);
Windows::Storage::StorageFile file{
    co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{ L"ms-appdata:///local/file.txt" })
};
// Process file
using Windows::Storage;
auto getFileTask = create_task(StorageFile::GetFileFromApplicationUriAsync(ref new Uri("ms-appdata:///local/file.txt")));
getFileTask.then([](StorageFile^ file) 
{
    // Process file
});

When GetFileFromApplicationUriAsync completes, it returns a StorageFile that represents the file.txt file in the app's local folder (file in the example).

The "ms-appdata:///local/" prefix in the URI refers to the app's local folder. To access files in the app's roaming or temporary folders use "ms-appdata:///roaming/" or "ms-appdata:///temporary/" instead. You can learn more about using app URIs in How to load file resources.

In addition, and unlike other locations, you can also access files in your app data locations by using some Win32 and COM for UWP apps and some C/C++ Standard Library functions from Visual Studio.

You can't access the local, roaming, or temporary folders through the file picker.

Removable devices

Additionally, your app can access some of the files on connected devices by default. This is an option if your app uses the AutoPlay extension to launch automatically when users connect a device, like a camera or USB thumb drive, to their system. The files your app can access are limited to specific file types that are specified via File Type Association declarations in your app manifest.

Of course, you can also gain access to files and folders on a removable device by calling the file picker (using FileOpenPicker and FolderPicker) and letting the user pick files and folders for your app to access. Learn how to use the file picker in Open files and folders with a picker.

Note

For more info about accessing an SD card or other removable devices, see Access the SD card.

Locations that UWP apps can access

User's Downloads folder

The folder where downloaded files are saved by default.

By default, your app can only access files and folders in the user's Downloads folder that your app created. However, you can gain access to files and folders in the user's Downloads folder by calling a file picker (FileOpenPicker or FolderPicker) so that users can navigate and pick files or folders for your app to access.

  • You can create a file in the user's Downloads folder like this:
using Windows.Storage;
StorageFile newFile = await DownloadsFolder.CreateFileAsync("file.txt");
Windows.Storage.DownloadsFolder.createFileAsync("file.txt").done(
    function(newFile) {
        // Process file
    }
);
Windows::Storage::StorageFile newFile{
    co_await Windows::Storage::DownloadsFolder::CreateFileAsync(L"file.txt")
};
// Process file
using Windows::Storage;
auto createFileTask = create_task(DownloadsFolder::CreateFileAsync(L"file.txt"));
createFileTask.then([](StorageFile^ newFile)
{
    // Process file
});

DownloadsFolder.CreateFileAsync is overloaded so that you can specify what the system should do if there is already an existing file in the Downloads folder that has the same name. When these methods complete, they return a StorageFile that represents the file that was created. This file is called newFile in the example.

  • You can create a subfolder in the user's Downloads folder like this:
using Windows.Storage;
StorageFolder newFolder = await DownloadsFolder.CreateFolderAsync("New Folder");
Windows.Storage.DownloadsFolder.createFolderAsync("New Folder").done(
    function(newFolder) {
        // Process folder
    }
);
Windows::Storage::StorageFolder newFolder{
    co_await Windows::Storage::DownloadsFolder::CreateFolderAsync(L"New Folder")
};
// Process folder
using Windows::Storage;
auto createFolderTask = create_task(DownloadsFolder::CreateFolderAsync(L"New Folder"));
createFolderTask.then([](StorageFolder^ newFolder)
{
    // Process folder
});

DownloadsFolder.CreateFolderAsync is overloaded so that you can specify what the system should do if there is already an existing subfolder in the Downloads folder that has the same name. When these methods complete, they return a StorageFolder that represents the subfolder that was created. This file is called newFolder in the example.

If you create a file or folder in the Downloads folder, we recommend that you add that item to your app's FutureAccessList so that your app can readily access that item in the future.

Accessing additional locations

In addition to the default locations, an app can access additional files and folders by declaring capabilities in the app manifest (see App capability declarations), or by calling a file picker to let the user pick files and folders for the app to access (see Open files and folders with a picker).

App's that that declare the AppExecutionAlias extension, have file-system permissions from the directory that they are launched from in the console window, and downwards.

The following table lists additional locations that you can access by declaring a capability (or capabilities) and using the associated Windows.Storage API:

Location Capability Windows.Storage API
All files that the user has access to. For example: documents, pictures, photos, downloads, desktop, OneDrive, etc. broadFileSystemAccess

This is a restricted capability. On first use, the system will prompt the user to allow access. Access is configurable in Settings > Privacy > File system. If you submit an app to the Store that declares this capability, you will need to supply additional descriptions of why your app needs this capability, and how it intends to use it.
This capability works for APIs in the Windows.Storage namespace
n/a
Documents DocumentsLibrary

Note: You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location.

Use this capability if your app:
- Facilitates cross-platform offline access to specific OneDrive content using valid OneDrive URLs or Resource IDs
- Saves open files to the user's OneDrive automatically while offline
KnownFolders.DocumentsLibrary
Music MusicLibrary
Also see Files and folders in the Music, Pictures, and Videos libraries.
KnownFolders.MusicLibrary
Pictures PicturesLibrary
Also see Files and folders in the Music, Pictures, and Videos libraries.
KnownFolders.PicturesLibrary
Videos VideosLibrary
Also see Files and folders in the Music, Pictures, and Videos libraries.
KnownFolders.VideosLibrary
Removable devices RemovableDevices

Note You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location.

Also see Access the SD card.
KnownFolders.RemovableDevices
Homegroup libraries At least one of the following capabilities is needed.
- MusicLibrary
- PicturesLibrary
- VideosLibrary
KnownFolders.HomeGroup
Media server devices (DLNA) At least one of the following capabilities is needed.
- MusicLibrary
- PicturesLibrary
- VideosLibrary
KnownFolders.MediaServerDevices
Universal Naming Convention (UNC) folders A combination of the following capabilities is needed.

The home and work networks capability:
- PrivateNetworkClientServer

And at least one internet and public networks capability:
- InternetClient
- InternetClientServer

And, if applicable, the domain credentials capability:
- EnterpriseAuthentication

Note: You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location.
Retrieve a folder using:
StorageFolder.GetFolderFromPathAsync

Retrieve a file using:
StorageFile.GetFileFromPathAsync

Example

This example adds the restricted broadFileSystemAccess capability. In addition to specifying the capability, the rescap namespace must be added, and is also added to IgnorableNamespaces:

<Package
  ...
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap mp uap5 rescap">
...
<Capabilities>
    <rescap:Capability Name="broadFileSystemAccess" />
</Capabilities>

Note

For a complete list of app capabilities, see App capability declarations.