文件访问权限

  • 项目

默认情况下，通用 Windows 平台 (UWP) 应用可以访问特定文件系统位置。 应用也可以通过文件选取器或通过声明功能访问其他位置。

UWP 应用可访问的位置

在创建新的应用时，默认情况下你可以访问以下文件系统位置：

应用程序安装目录

用户系统上用于安装应用的文件夹。

主要可以使用两种方式来访问应用的安装目录中的文件和文件夹：

  1. 可以检索代表应用的安装目录的 StorageFolder，如下所示：

    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;

    可以使用 StorageFolder 方法访问目录中的文件和文件夹。 在本例中，此 StorageFolder 存储在 installDirectory 变量中。 可以从 GitHub 上的应用包信息示例了解有关使用应用包和安装目录的详细信息。

  2. 你可以通过使用应用 URI 直接从应用的安装目录检索文件，如下所示：

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

    当 GetFileFromApplicationUriAsync 完成时，它将返回一个 StorageFile，代表应用的安装目录中的 file.txt 文件（示例中的 file）。

    URI 中的“ms-appx:///”前缀是指应用的安装目录。 你可以在如何使用 URI 来引用内容中了解有关使用应用 URI 的更多信息。

此外，与其他位置不同，你还可以使用一些用于通用 Windows 平台 (UWP) 应用的 Win32 和 COM 和一些 Microsoft Visual Studio 中的 C/C++ 标准库函数来访问应用安装目录中的文件。

应用的安装目录是一个只读位置。 不能通过文件选取器获得对安装目录的访问。

访问应用程序数据位置

你的应用可以存储数据的文件夹。 在安装你的应用时创建这些文件夹（本地、漫游和临时）。

可以通过两种主要方法来访问应用的数据位置中的文件和文件夹：

  1. 使用 ApplicationData 属性检索应用数据文件夹。

    例如，可以使用 ApplicationData.LocalFolder 检索代表应用的本地文件夹的 StorageFolder，如下所示：

    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;

    如果希望访问应用的漫游或临时文件夹，可以改用 RoamingFolder 或 TemporaryFolder 属性。

    在检索代表应用数据位置的 StorageFolder 之后，可以使用 StorageFolder 方法访问该位置中的文件和文件夹。 在本例中，这些 StorageFolder 对象存储在 localFolder 变量中。 可以从 ApplicationData 类页面上的指南，以及通过从 GitHub 下载应用程序数据示例，来了解有关使用应用数据位置的详细信息。

  2. 可以通过使用应用 URI 直接从应用的本地文件夹检索文件，如下所示：

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

    当 GetFileFromApplicationUriAsync 完成时，它将返回一个 StorageFile，代表应用的本地文件夹中的 file.txt 文件（示例中的 file）。

    URI 中的“ms-appdata:///local/”前缀是指应用的本地文件夹。 要访问应用的漫游文件夹或临时文件夹中的文件，请改用“ms-appdata:///roaming/”或“ms-appdata:///temporary/”。 你可以在如何加载文件资源中了解关于使用应用 URI 的详细信息。

此外，与其他位置不同，你还可以使用一些用于 UWP 应用的 Win32 和 COM 以及和一些 Visual Studio 中的 C/C++ 标准库函数来访问应用数据位置中的文件。

无法通过文件选取器访问本地、漫游或临时文件夹。

访问可移动设备

此外，默认情况下你的应用可以访问连接设备上的一些文件。 如果你的应用使用在用户将设备（如相机或 U 盘）连接到系统时自动启动的自动播放扩展，可以选择此选项。 你的应用可以访问的文件限于通过应用清单中的文件类型关联声明指定的特定文件类型。

当然，还可以通过调用文件选取器（使用 FileOpenPicker 和 FolderPicker）并让用户选取供你的应用访问的文件和文件夹，以获得对可移动设备上的文件和文件夹的访问权。 通过使用选取器打开文件和文件夹了解如何使用文件选取器。

注意

有关访问 SD 卡或其他可移动设备的详细信息，请参阅访问 SD 卡。

用户的“下载”文件夹

默认情况下保存下载文件的文件夹。

默认情况下，你的应用只能访问它创建的用户“下载”文件夹中的文件和文件夹。 不过，你可以通过调用文件选取器（FileOpenPicker 或 FolderPicker）让用户可以导航并选取供应用访问的文件或文件夹，以获取对用户下载文件夹中的文件和文件夹的访问权。

  • 你可以在用户的下载文件夹中创建文件，如下所示：

    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 重载，这样可以指定在“下载”文件夹中已经存在同名文件时系统应执行的操作。 这些方法完成之后，它们将返回一个代表已创建文件的 StorageFile。 此文件在本例中称为 newFile。

  • 你可以在用户的“下载”文件夹中创建子文件夹，如下所示：

    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 重载，这样可以指定在“下载”文件夹中已经存在同名子文件夹时系统应执行的操作。 这些方法完成之后，它们将返回一个代表已创建子文件夹的 StorageFolder。 此文件在本例中称为 newFolder。

访问其他位置

除了默认位置以外，应用还可以通过在应用清单中声明功能或者通过调用文件选取器让用户选取供应用访问的文件和文件夹来访问其他文件和文件夹。

声明 AppExecutionAlias 扩展的应用具有来自控制台窗口中启动的目录及下级目录的文件系统权限。

保留对文件和文件夹的访问权限

当应用通过选取器、文件激活、拖放操作等检索文件或文件夹时，只有在终止该应用后，才能访问该文件或文件夹。 如果想要在将来自动访问文件或文件夹，则可以将其添加到 FutureAccessList 中，以便应用在将来可以随时访问该项。 还可以使用 MostRecentlyUsedList 轻松管理最近使用的文件的列表。

用于访问其他位置的功能

下表列出了其他可通过声明一项或多项功能和使用关联的 Windows.Storage API 来访问的位置。

位置 功能 Windows.Storage API
用户有权访问的所有文件。 例如：文档、图片、照片、下载、桌面、OneDrive 等。 broadFileSystemAccess

此功能受限。 可以通过“设置”>“隐私”>“文件系统”配置访问。 由于用户随时可以在“设置”中授予或拒绝权限，因此，你应确保应用能够弹性应对这些更改。 如果你发现应用没有访问权限，可以选择通过提供 Windows 10 文件系统访问权限和隐私一文的链接，来提示用户更改该设置。 请注意，用户必须关闭应用、切换设置，然后重启应用。 如果他们在应用正在运行时切换设置，则平台将挂起该应用，以便你可以保存状态，然后强制终止该应用以应用新的设置。 在 2018 年 4 月更新中，该权限默认设置为“打开”。 在 2018 年 10 月更新中，默认设置为“关闭”。

如果向 Microsoft Store 提交声明此功能的应用，将需要额外说明应用需要此功能的原因以及打算使用它的方式。

此功能适用于 Windows.Storage 命名空间中的 API。 请参阅本文末尾的示例部分，其中的某个示例演示了如何在应用中启用此功能。

注意： 此功能在 Xbox 上不受支持。		 不适用
文档 documentsLibrary

注意：必须将文件类型关联（该关联声明你的应用可以在此位置中访问的特定文件类型）添加到你的应用清单。

你的应用使用此功能的情况：
- 使用有效的 OneDrive URL 或资源 ID 促进跨平台离线访问特定 OneDrive 内容
- 在离线时将打开的文件自动保存到用户的 OneDrive		 KnownFolders.DocumentsLibrary
Music musicLibrary
另请参阅音乐、图片和视频库中的文件和文件夹。		 KnownFolders.MusicLibrary
图片 picturesLibrary
另请参阅音乐、图片和视频库中的文件和文件夹。		 KnownFolders.PicturesLibrary
视频 videosLibrary
另请参阅音乐、图片和视频库中的文件和文件夹。		 KnownFolders.VideosLibrary
可移动设备 removableStorage

请注意，必须将文件类型关联（该关联声明你的应用可以在此位置中访问的特定文件类型）添加到你的应用清单。

另请参阅访问 SD 卡。		 KnownFolders.RemovableDevices
家庭组库 至少需要下列功能之一。
- musicLibrary
- picturesLibrary
- videosLibrary		 KnownFolders.HomeGroup
媒体服务器设备 (DLNA) 至少需要下列功能之一。
- musicLibrary
- picturesLibrary
- videosLibrary		 KnownFolders.MediaServerDevices
通用命名约定 (UNC) 文件夹 需要下列功能组合。

家庭和工作网络功能：
- privateNetworkClientServer

至少一个 Internet 和公共网络功能：
- internetClient
- internetClientServer

域凭据功能（如果适用）：
- enterpriseAuthentication

注意： 必须将文件类型关联（该关联声明应用可以在此位置中访问的特定文件类型）添加到应用清单。		 使用以下项检索文件夹：
StorageFolder.GetFolderFromPathAsync

使用以下项检索文件：
StorageFile.GetFileFromPathAsync

示例

此示例添加受限的 broadFileSystemAccess 功能。 除了指定功能，还必须添加 rescap 命名空间并将其添加到 IgnorableNamespaces。

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

注意

有关应用功能的完整列表，请参阅应用功能声明。