共用方式為

檔案存取權限

  • 發行項

通用 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) 中的 file.txt 檔案。

    URI 中的 "ms-appx:///" 前置詞是指應用程式的安裝目錄。 您可以在如何使用 URI 來參考內容中深入了解如何使用應用程式 URI。

此外，與其他位置不同，您也可以使用一些 Win32 和 COM for Universal Windows Platform (UWP) 應用程式和一些來自 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) 中的 file.txt 檔案。

    URI 中的 "ms-appdata:///local/" 前置詞是指應用程式的本機資料夾。 若要存取應用程式的漫遊或暫存資料夾中的檔案，請改用 "ms-appdata:///roaming/" 或 "ms-appdata:///temporary/"。 您可以在如何載入檔案資源中深入了解如何使用應用程式 URI。

此外，與其他位置不同，您也可以使用一些 Win32 和 COM for UWP 應用程式和一些來自 Visual Studio 的 C/C++ 標準程式庫函式，來存取應用程式資料位置中的檔案。

您無法透過檔案選擇器存取本機、漫遊或暫存資料夾。

存取卸除式裝置

此外，您的應用程式預設可以存取連線的裝置上的一些檔案。 如果您的應用程式使用自動播放延伸模組，以在使用者將相機或 USB 隨身碟等裝置連線到其系統時自動啟動，則這是一個選項。 您的應用程式可以存取的檔案僅限於透過應用程式資訊清單中的檔案類型關聯宣告所指定的特定檔案類型。

當然，您也可以藉由呼叫檔案選擇器 (使用 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 檔案系統存取權與隱私權一文的連結，來提示他們變更設定。 請注意，使用者必須關閉應用程式，切換該設定，然後再重新啟動應用程式。 如果他們在應用程式執行期間切換該設定，平台將會暫停您的應用程式以讓您儲存狀態，然後強制終止該應用程式以套用新設定。 在 2018 年 4 月更新中，該權限的預設值為 [開啟]。 在 2018 年 10 月更新中，預設值為 [關閉]。

如果您將應用程式提交至會宣告此功能的 Microsoft Store，則須提供其他描述以說明應用程式為何需要此功能，以及其意圖使用此功能的方式。

此功能適用於 Windows.Storage \(英文\) 命名空間中的 API。 請參閱本文結尾的＜範例＞小節，以取得在應用程式中啟用此功能的範例。

注意：Xbox 上不支援此功能。		 n/a
文件​​ documentsLibrary

注意：您必須將檔案類型關聯新增到應用程式資訊清單中，其會宣告您的應用程式可在這個位置中存取的特定檔案類型。

如果您的應用程式符合以下情況，請使用此功能：
- 使用有效的 OneDrive URL 或資源識別碼，協助跨平台離線存取特定 OneDrive 內容
- 在離線時自動將開啟的檔案儲存到使用者的 OneDrive		 KnownFolders.DocumentsLibrary \(英文\)
音樂 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

以及至少一個網際網路和公用網路功能：
- 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>

注意

如需完整的應用程式功能清單，請參閱應用程式功能宣告 \(部分機器翻譯\)。