File access permissions

Artykuł
10/20/2022

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

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

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.

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.

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

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.

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.

Access 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.

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.

Accessing additional locations

In addition to the default locations, an app can access additional files and folders by declaring capabilities in the app manifest or by calling a file picker to let the user pick files and folders for the app to access.

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

Retaining access to files and folders

When your app retrieves a file or folder via a picker, a file activation, a drag-and-drop operation, etc. it only has access to that file or folder until the app is terminated. If you would like to automatically access the file or folder in the future, you can add it to the FutureAccessList so that your app can readily access that item in the future. You can also use the MostRecentlyUsedList to easily manage a list of recently-used files.

Capabilities for accessing other locations

The following table lists additional locations that you can access by declaring one or more 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. Access is configurable in Settings > Privacy > File system. Because users can grant or deny the permission any time in Settings, you should ensure that your app is resilient to those changes. If you find that your app does not have access, you may choose to prompt the user to change the setting by providing a link to the Windows file system access and privacy article. Note that the user must close the app, toggle the setting, and restart the app. If they toggle the setting while the app is running, the platform will suspend your app so that you can save the state, then forcibly terminate the app in order to apply the new setting. In the April 2018 update, the default for the permission is On. In the October 2018 update, the default is Off. 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. See the Example section at the end of this article for an example of how to enable this capability in your app. Note: This capability is not supported on Xbox.	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	removableStorage 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 rescap">
...
<Capabilities>
    <rescap:Capability Name="broadFileSystemAccess" />
</Capabilities>