File access and permissions (Windows Runtime apps)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Apps can access certain file system locations by default. Apps can also access additional locations through the file picker, or by declaring capabilities.

Locations 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:

     var installDirectory = Windows.ApplicationModel.Package.current.installedLocation;
     

     Windows.Storage.StorageFolder installedLocation = Windows.ApplicationModel.Package.Current.InstalledLocation;
     

     After you retrieve a StorageFolder that represents the install directory, you can 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 by downloading the App package information sample.

  2. You can retrieve a file directly from your app's install directory by using an app URI, like this:

     Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appx:///file.txt").done(
         function(file) {
             // Process file
         }
     );
     

     using Windows.Storage;
     
     StorageFile file = await StorageFile.GetFileFromApplicationUriAsync("ms-appx:///file.txt");
     

     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 Windows Store 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:

     var localFolder = Windows.Storage.ApplicationData.current.localFolder;
     

     using Windows.Storage;
     
     StorageFolder localFolder = 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 in Managing application data, and by downloading the Application data sample.

  2. For example, you can retrieve a file directly from your app's local folder by using an app URI, like this:

     Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appdata:///local/file.txt").done(
         function(file) {
             // Process file
         }
     );
     

     using Windows.Storage;
     
     StorageFile file = await StorageFile.GetFileFromApplicationUriAsync("ms-appdata:///local/file.txt");
     

     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 Windows Store 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 Quickstart: Accessing files with file pickers.

  Note  For more info about accessing an SD card from a Windows Phone app, see Access the SD card in Windows Phone apps.

   

Locations Windows Store 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:

    Windows.Storage.DownloadsFolder.createFileAsync("file.txt").done(
        function(newFile) {
            // Process file
        }
    );
    

    using Windows.Storage;
    
    StorageFile newFile = await DownloadsFolder.CreateFileAsync("file.txt");
    

    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:

    Windows.Storage.DownloadsFolder.createFolderAsync("New Folder").done(
        function(newFolder) {
            // Process folder
        }
    );
    

    using Windows.Storage;
    
    StorageFolder newFolder = await DownloadsFolder.CreateFolderAsync("New 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 Quickstart: Accessing files with file pickers).

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

Related topics

Managing application data

JavaScript resources

Quickstart: Reading and writing a file

Quickstart: Accessing files with file pickers

How to load file resources

How to track recently used files and folders

C#/C++/VB resources

Quickstart: Reading and writing a file

Quickstart: Accessing files with file pickers

How to load file resources

How to track recently used files and folders

Samples

App package information sample

Application data sample

File access sample

File picker sample

API Reference

Windows.ApplicationModel.Package

Windows.Storage.ApplicationData

Windows.Storage.DownloadsFolder

Windows.Storage.Pickers.FileOpenPicker

Windows.Storage.Pickers.FolderPicker

Windows.Storage.KnownFolders

Windows.Storage.StorageFile

Windows.Storage.StorageFolder

Windows.Storage.FileIO

Windows.Storage.PathIO

Windows.Storage.AccessCache.StorageApplicationPermissions.FutureAccessList

Windows.Storage.AccessCache.StorageApplicationPermissions.MostRecentlyUsedList