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

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

Расположения, к которым могут получить доступ приложения WinUI

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

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

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

В каталоге установки приложения есть два основных способа доступа к файлам и папкам:

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

   Windows.Storage.StorageFolder installedLocation = Windows.ApplicationModel.Package.Current.InstalledLocation;
   

   #include <winrt/Windows.Storage.h>
   ...
   Windows::Storage::StorageFolder installedLocation{ Windows::ApplicationModel::Package::Current().InstalledLocation() };
   

   Затем вы можете получить доступ к файлам и папкам в каталоге с помощью методов StorageFolder . В этом примере хранилищеFolder хранится в переменной installDirectory . Дополнительные сведения о работе с пакетом приложения и каталогом установки см. в примере сведений о пакете приложения на сайте GitHub.

2. Файл можно получить непосредственно из каталога установки приложения с помощью URI приложения, как показано ниже.

   using Windows.Storage;            
   StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///file.txt"));
   

   Windows::Foundation::IAsyncAction ExampleCoroutineAsync()
   {
       Windows::Storage::StorageFile file{
           co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{L"ms-appx:///file.txt"})
       };
       // Process file
   }
   

   После завершения GetFileFromApplicationUriAsync возвращает файл StorageFile , представляющий file.txt файл в каталоге установки приложения (file в примере).

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

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

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

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

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

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

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

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

   using Windows.Storage;
   StorageFolder localFolder = ApplicationData.Current.LocalFolder;
   

   Windows::Storage::StorageFolder storageFolder{
       Windows::Storage::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 file{
       co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{ L"ms-appdata:///local/file.txt" })
   };
   // Process file
   

   После завершения GetFileFromApplicationUriAsync возвращает файл StorageFile , представляющий file.txt файл в локальной папке приложения (file в примере).

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

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

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

Доступ к съемным устройствам

Кроме того, приложение может получить доступ к некоторым файлам на подключенных устройствах по умолчанию. Это вариант, если приложение использует расширение Автозапуска для автоматического запуска при подключении устройства, например камеры или USB-накопителя, к системе. Доступ к файлам приложения ограничен определенными типами файлов, указанными в объявлениях сопоставления типов файлов в манифесте приложения.

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

Замечание

Дополнительные сведения о доступе к SD-карте или другим съемным устройствам см. в статье "Доступ к SD-карте".

Папка загрузки пользователя

Папка, в которой скачанные файлы сохраняются по умолчанию.

По умолчанию приложение может получать доступ только к файлам и папкам в папке загрузки пользователя, созданной приложением. Однако вы можете получить доступ к файлам и папкам в папке загрузки пользователя, вызвав средство выбора файлов (FileOpenPicker или FolderPicker), чтобы пользователи могли перемещаться и выбирать файлы или папки для доступа к приложению.

• Вы можете создать файл в папке загрузки пользователя, как показано ниже.

  using Windows.Storage;
  StorageFile newFile = await DownloadsFolder.CreateFileAsync("file.txt");
  

  Windows::Storage::StorageFile newFile{
      co_await Windows::Storage::DownloadsFolder::CreateFileAsync(L"file.txt")
  };
  // Process file
  

  DownloadsFolder. CreateFileAsync перегружен таким образом, чтобы можно было указать, что должна сделать система, если в папке downloads уже есть существующий файл с тем же именем. После завершения этих методов они возвращают файл StorageFile , представляющий созданный файл. Этот файл называется newFile в примере.

• Вы можете создать вложенную папку в папке загрузки пользователя, как показано ниже.

  using Windows.Storage;
  StorageFolder newFolder = await DownloadsFolder.CreateFolderAsync("New Folder");
  

  Windows::Storage::StorageFolder newFolder{
      co_await Windows::Storage::DownloadsFolder::CreateFolderAsync(L"New Folder")
  };
  // Process folder
  

  DownloadsFolder. CreateFolderAsync перегружен, чтобы указать, что должна сделать система, если в папке Downloads уже есть вложенная папка, которая имеет то же имя. После завершения этих методов они возвращают папку StorageFolder , представляющую созданную вложенную папку. Этот файл называется newFolder в примере.

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

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

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

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

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

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

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

Местоположение	Функциональность	Windows.Storage API
Все файлы, к которым у пользователя есть доступ. Например, документы, рисунки, фотографии, загрузки, настольные компьютеры, OneDrive и т. д.	broadFileSystemAccess Это ограниченная возможность. Доступ можно настроить в Параметры > Конфиденциальность >Файловая система. Так как пользователи могут предоставить или отменить разрешение в любой момент в разделе "Параметры", следует убедиться, что приложение устойчиво к этим изменениям. Если у приложения нет доступа, вы можете предложить пользователю изменить этот параметр, предоставив ссылку на доступ к файловой системе Windows и статью о конфиденциальности. Обратите внимание, что пользователь должен закрыть приложение, переключить параметр и перезапустить приложение. Если они переключают параметр во время работы приложения, платформа приостанавливает приложение, чтобы сохранить состояние, а затем принудительно завершить работу приложения, чтобы применить новый параметр. В обновлении за апрель 2018 года по умолчанию это разрешение включено. В обновлении октябрь 2018 по умолчанию оно отключено. Если вы отправляете приложение в Магазин, которое объявляет эту возможность, вам потребуется предоставить дополнительные описания того, почему ваше приложение нуждается в этой возможности и как оно намерено его использовать. Эта возможность работает для API в пространстве имен Windows.Storage . В разделе "Пример" в конце этой статьи приведен пример включения этой возможности в приложении. Примечание. Эта возможность не поддерживается в Xbox.	n/a
Documents	библиотека документов Примечание. Необходимо добавить сопоставления типов файлов в манифест приложения, объявляющий определенные типы файлов, к которым приложение может получить доступ в этом расположении. Используйте эту возможность, если ваше приложение: — упрощает кроссплатформенный автономный доступ к определенному содержимому OneDrive с помощью допустимых URL-адресов OneDrive или идентификаторов ресурсов. — автоматически сохраняет открытые файлы в OneDrive пользователя в автономном режиме.	KnownFolders.DocumentsLibrary
Music	Музыкальная библиотека Также см. файлы и папки в библиотеках "Музыка", "Рисунки" и "Видео".	KnownFolders.MusicLibrary
Pictures	библиотека изображений Также см. файлы и папки в библиотеках "Музыка", "Рисунки" и "Видео".	KnownFolders.PicturesLibrary
Видеоролики	библиотека видео Также см. файлы и папки в библиотеках "Музыка", "Рисунки" и "Видео".	KnownFolders.VideosLibrary
Съемные устройства	съемное хранилище Примечание. Необходимо добавить сопоставления типов файлов в манифест приложения, которые объявляют определенные типы файлов, к которым приложение может получить доступ в этом расположении. Также см. раздел "Доступ к SD-карте".	KnownFolders.RemovableDevices
Библиотеки домашней группы	Требуется по крайней мере одна из следующих возможностей. - musicLibrary - библиотека изображений - видеобиблиотека	KnownFolders.HomeGroup
Устройства сервера мультимедиа (DLNA)	Требуется по крайней мере одна из следующих возможностей. - musicLibrary - библиотека изображений - видеотека	KnownFolders.MediaServerDevices
Папки универсальной системы имен (UNC)	Требуется сочетание следующих возможностей. Возможности домашних и рабочих сетей: — privateNetworkClientServer И по крайней мере одна возможность интернета и общедоступных сетей: — internetClient — internetClientServer И, если применимо, возможность учетных данных домена: — аутентификация предприятия Примечание: Необходимо добавить сопоставления типов файлов в манифест приложения, объявляющий определенные типы файлов, к которым приложение может получить доступ в этом расположении.	Получение папки с помощью: 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>

Замечание

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