File access and permissions (Windows Runtime apps)

發行項
10/13/2015

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

Location	Capability	Windows.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 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. 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. MusicLibrary PicturesLibrary VideosLibrary	KnownFolders.HomeGroup
Media server devices (DLNA) (Windows Store apps only)	At least one of the following capabilities is needed. MusicLibrary PicturesLibrary VideosLibrary	KnownFolders.MediaServerDevices
Universal Naming Convention (UNC) folders (Windows Store apps only)	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