Разрешения на доступ к файлам

  • Статья

Приложения UWP могут иметь доступ к определенным расположениям в файловой системе по умолчанию. Приложения также могут получить доступ к дополнительным расположениям через средство выбора файлов или объявить возможности.

Расположения, доступные приложениям UWP

При создании приложения вы можете получить доступ к следующим расположениям файловой системы по умолчанию:

Папка установки приложения

Папка, в которую устанавливается ваше приложение в системе пользователя.

Существуют два основных способа получения доступа к файлам и папкам в папке установки вашего приложения.

  1. Вы можете получить служба хранилища Folder, представляющий каталог установки приложения, как показано ниже.

    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;

    Затем вы можете получить доступ к файлам и папкам в каталоге с помощью методов служба хранилища Folder. В примере этот служба хранилища Folder хранится в переменной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 в примере).

    Префикс ms-appx:/// в URI ссылается на каталог установки приложения. Дополнительные сведения об использовании URI приложений см. в руководстве по использованию URI для ссылки на содержимое.

Кроме того, в отличие от других расположений, вы также можете получить доступ к файлам в каталоге установки приложений с помощью некоторых приложений Win32 и COM для приложений универсальная платформа Windows (UWP) и некоторых функций стандартной библиотеки C/C++ из Microsoft Visual Studio.

Каталог установки приложения — это расположение только для чтения. Невозможно получить доступ к папке установки с помощью средства выбора файлов.

Получение доступа к расположениям данных приложения

Папки, в которых ваше приложение может хранить данные. Эти папки (локальные, перемещаемые и временные) создаются при установке приложения.

Существуют два основных способа получения доступа к файлам и папкам из расположения данных вашего приложения.

  1. Используйте свойства ApplicationData для получения папки данных приложения.

    Например, можно использовать ApplicationData.LocalFolder для получения служба хранилища Folder, представляющей локальную папку приложения следующим образом:

    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.

    После получения служба хранилища Folder, представляющего расположение данных приложения, вы можете получить доступ к файлам и папкам в этом расположении с помощью методов служба хранилища Folder. В этом примере эти объекты служба хранилища Folder хранятся в переменной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 в примере).

    Префикс ms-appdata:///local/ в URI ссылается на локальную папку приложения. Для доступа к файлам в перемещаемых или временных папках приложения вместо этого используйте ms-appdata:///roaming/ или ms-appdata:///temporary/. Дополнительные сведения об использовании URI приложений см. в разделе "Загрузка ресурсов файлов".

Кроме того, в отличие от других расположений, вы также можете получить доступ к файлам в расположениях данных приложения с помощью некоторых приложений Win32 и COM для приложений UWP и некоторых функций стандартной библиотеки C/C++ из Visual Studio.

Невозможно получить доступ к локальной, перемещаемой и временной папкам с помощью средства выбора файлов.

Получение доступа к съемным устройствам

Кроме того, приложение может получить доступ к некоторым файлам на подключенных устройствах по умолчанию. Это вариант, если приложение использует расширение Автозапуска для автоматического запуска при подключении устройства, например камеры или 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 перегружен таким образом, чтобы вы могли указать системе алгоритм действий, если в папке скачиваемых файлов уже существует файл с таким же именем. По завершении этих методов возвращается файл служба хранилища File, представляющий созданный файл. Этот файл вызывается 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 перегружен таким образом, чтобы вы могли указать системе алгоритм действий, если в папке скачиваемых файлов уже существует вложенная папка с таким же именем. По завершении этих методов возвращается объект служба хранилища Folder, представляющий созданную вложенную папку. Этот файл вызывается newFolder в примере.

Доступ к дополнительным расположениям

Кроме расположений по умолчанию, приложение может получить доступ к дополнительным файлам и папкам с помощью объявления возможностей в манифесте приложения или с помощью вызова средства выбора файлов, что позволяет пользователю выбирать файлы и папки, предоставляя приложению доступ к ним.

Приложения, объявляющие расширение AppExecutionAlias, имеют разрешения файловой системы, начиная с каталога, откуда они запускаются в окне консоли, и далее вниз по иерархии.

Сохранение доступа к файлам и папкам

Когда приложение получает файл или папку с помощью средства выбора, активации файла, операции перетаскивания и т. д., доступ к этому файлу или папке сохраняется, только пока приложение работает. Если вы хотите автоматически получать доступ к файлу или папке в будущем, можно добавить эти элементы в FutureAccessList. Можно также использовать MostRecentlyUsedList, чтобы управлять списком недавно использовавшихся файлов.

Возможности доступа к другим расположениям

В таблице ниже перечислены дополнительные расположения, к которым можно получить доступ, объявив возможности и используя связанные API Windows.Storage.

Местонахождение Возможность Windows. API служба хранилища
Все файлы, к которым у пользователя имеется доступ. Например: документы, изображения, фотографии, скачанные файлы, рабочий стол, OneDrive и т. д. broadFileSystemAccess

Это ограниченная возможность. Доступ настраивается в разделе Параметры>Конфиденциальность>Файловая система. Так как пользователи могут предоставить или отменить разрешение в любой момент в разделе Параметры, следует убедиться, что приложение устойчиво к этим изменениям. Если вы обнаружили, что у приложения нет доступа, вы можете предложить пользователю изменить этот параметр, предоставив ссылку на статью Доступ к файловой системе и конфиденциальность в Windows 10. Обратите внимание на то, что пользователь должен закрыть приложение, изменить параметр и перезапустить приложение. Если он изменит параметр во время работы приложения, платформа приостановит ваше приложение, чтобы можно было сохранить состояние, а затем принудительно завершит его, чтобы применить новый параметр. В обновлении за апрель 2018 года по умолчанию это разрешение включено. В обновлении октябрь 2018 по умолчанию оно отключено.

Если приложение отправляется в Store, объявляющий эту возможность, потребуется дополнительно обосновать, зачем приложению нужна эта возможность и как планируется ее использовать.

Эта возможность подходит для интерфейсов API в пространстве имен Windows.Storage. В разделе Пример в конце этой статьи показано, как включить эту возможность в приложении.

Примечание. Эта возможность не поддерживается в Xbox.		 Н/Д
документы. documentsLibrary

Примечание. Необходимо добавить сопоставления типов файлов в манифест приложения, объявляющий определенные типы файлов, к которым приложение может получить доступ в этом расположении.

Используйте эту возможность, если ваше приложение:
— упрощает кроссплатформенный автономный доступ к определенному содержимому OneDrive с помощью допустимых URL-адресов OneDrive или идентификаторов ресурсов.
- автоматически сохраняет открытые файлы в OneDrive пользователя при работе в автономном режиме.		 KnownFolders.DocumentsLibrary
Музыка musicLibrary
Также см . файлы и папки в библиотеках "Музыка", "Рисунки" и "Видео".		 KnownFolders.MusicLibrary
Изображения picturesLibrary
Также см . файлы и папки в библиотеках "Музыка", "Рисунки" и "Видео".		 KnownFolders.PicturesLibrary
Видеоролики videosLibrary
Также см . файлы и папки в библиотеках "Музыка", "Рисунки" и "Видео".		 KnownFolders.VideosLibrary
Съемные устройства removableStorage

Примечание. Необходимо добавить сопоставления типов файлов в манифест приложения, в котором указаны конкретные типы файлов, доступные приложению в этом расположении.

Кроме того, см. карта access the SD карта.		 KnownFolders.RemovableDevices
Библиотеки домашней группы Требуется по крайней мере одна из следующих возможностей.
- musicLibrary
- picturesLibrary
- videosLibrary		 KnownFolders.HomeGroup
Устройства сервера мультимедиа (DLNA) Требуется по крайней мере одна из следующих возможностей.
- musicLibrary
- picturesLibrary
- videosLibrary		 KnownFolders.MediaServerDevices
Папки универсального соглашения об именовании (UNC) Требуется сочетание следующих возможностей.

Возможности домашних и рабочих сетей:
- privateNetworkClientServer

И по крайней мере одна возможность интернета и общедоступных сетей:
- internetClient
- internetClientServer

И, если применимо, возможность учетных данных домена:
- enterpriseAuthentication

Примечание. Необходимо добавить сопоставления типов файлов в манифест приложения, объявляющий определенные типы файлов, к которым приложение может получить доступ в этом расположении.		 Получение папки с помощью:
служба хранилища Folder.GetFolderFromPathAsync

Получение файла с помощью:
служба хранилища File.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>

Примечание.

Полный список возможностей приложения приведен в разделе Объявления возможностей приложения.