File access and permissions (Windows Runtime apps)

Applies to Windows and Windows Phone

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

  • Applies to Windows
  • Applies to Windows Phone

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;
      
      

      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
          }
      );
      
      

      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;
      
      

      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
          }
      );
      
      

      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 .

  • Applies to Windows

Locations most 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
          }
      );
      
      

      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
          }
      );
      
      

      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:

LocationCapabilityWindows.Storage API

Documents

(Windows Store apps only)

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

For more info about accessing media libraries from a Windows Phone app, see Access media libraries in Windows Phone apps.

KnownFolders.MusicLibrary
Pictures PicturesLibrary

For more info about accessing media libraries from a Windows Phone app, see Access media libraries in Windows Phone apps.

KnownFolders.PicturesLibrary
Videos VideosLibrary

For more info about accessing media libraries from a Windows Phone app, see Access media libraries in Windows Phone apps.

KnownFolders.VideosLibrary
Removable devicesRemovableDevices

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

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

KnownFolders.RemovableDevices

Homegroup libraries

(Windows Store apps only)

At least one of the following capabilities is needed.

KnownFolders.HomeGroup

Media server devices (DLNA)

(Windows Store apps only)

At least one of the following capabilities is needed.

KnownFolders.MediaServerDevices

Universal Naming Convention (UNC) folders

(Windows Store apps only)

A combination of the following capabilities is needed.

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

 

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

 

 

Show:
© 2014 Microsoft