Uprawnienia dostępu do plików

Aplikacje WinUI mogą domyślnie uzyskiwać dostęp do określonych lokalizacji systemu plików. Aplikacje mogą również uzyskiwać dostęp do dodatkowych lokalizacji za pośrednictwem selektora plików lub deklarując możliwości.

Lokalizacje, do których mogą uzyskiwać dostęp aplikacje WinUI

Podczas tworzenia nowej aplikacji można domyślnie uzyskać dostęp do następujących lokalizacji systemu plików:

Katalog instalacji aplikacji

Folder, w którym aplikacja jest zainstalowana w systemie użytkownika.

Istnieją dwa podstawowe sposoby uzyskiwania dostępu do plików i folderów w katalogu instalacyjnym aplikacji:

1. Folder StorageFolder reprezentujący katalog instalacyjny aplikacji można pobrać w następujący sposób:

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

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

   Następnie możesz uzyskać dostęp do plików i folderów w katalogu przy użyciu metod StorageFolder . W tym przykładzie ten folder StorageFolder jest przechowywany w zmiennej installDirectory . Więcej informacji na temat pracy z pakietem aplikacji i katalogiem instalacji można znaleźć w przykładzie Informacje o pakiecie aplikacji w witrynie GitHub.

2. Plik można pobrać bezpośrednio z katalogu instalacji aplikacji przy użyciu identyfikatora URI aplikacji, w następujący sposób:

   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
   }
   

   Po zakończeniu polecenia GetFileFromApplicationUriAsync zwraca on plik StorageFile reprezentujący file.txt plik w katalogu instalacyjnym aplikacji (file w przykładzie).

   Prefiks "ms-appx:///" w identyfikatorze URI odnosi się do katalogu instalacji aplikacji. Aby dowiedzieć się więcej na temat używania identyfikatorów URI aplikacji, zobacz How to use URIs to reference content (Jak używać identyfikatorów URI do odwołowania się do zawartości).

Ponadto, w przeciwieństwie do innych lokalizacji, można również uzyskiwać dostęp do plików w katalogu instalacji aplikacji, korzystając z niektórych technologii Win32 i COM w przypadku aplikacji WinUI oraz niektórych funkcji standardowej biblioteki C/C++, dostępnych w Microsoft Visual Studio.

Katalog instalacyjny aplikacji jest lokalizacją tylko do odczytu. Nie można uzyskać dostępu do katalogu instalacji za pomocą selektora plików.

Uzyskiwanie dostępu do lokalizacji danych aplikacji

Foldery, w których aplikacja może przechowywać dane. Te foldery (lokalne, mobilne i tymczasowe) są tworzone podczas instalowania aplikacji.

Istnieją dwa podstawowe sposoby uzyskiwania dostępu do plików i folderów z lokalizacji danych aplikacji:

1. Użyj właściwości ApplicationData , aby pobrać folder danych aplikacji.

   Można na przykład użyć parametru ApplicationData. Folder lokalny do pobrania folderu StorageFolder reprezentującego folder lokalny aplikacji w następujący sposób:

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

   Windows::Storage::StorageFolder storageFolder{
       Windows::Storage::ApplicationData::Current().LocalFolder()
   };
   

   Jeśli chcesz uzyskać dostęp do mobilnego lub tymczasowego folderu aplikacji, zamiast tego użyj właściwości RoamingFolder lub TemporaryFolder .

   Po pobraniu folderu StorageFolder reprezentującego lokalizację danych aplikacji można uzyskać dostęp do plików i folderów w tej lokalizacji przy użyciu metod StorageFolder. W tym przykładzie te obiekty StorageFolder są przechowywane w zmiennej localFolder . Aby dowiedzieć się więcej na temat używania lokalizacji danych aplikacji, zapoznaj się ze wskazówkami na stronie klasy ApplicationData i pobierz przykładowe dane aplikacji z usługi GitHub.

2. Plik można pobrać bezpośrednio z folderu lokalnego aplikacji przy użyciu identyfikatora URI aplikacji, w następujący sposób:

   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
   

   Po zakończeniu działania GetFileFromApplicationUriAsync zwraca plik StorageFile reprezentujący file.txt plik w lokalnym folderze aplikacji (file w przykładzie).

   Prefiks "ms-appdata:///local/" w identyfikatorze URI odnosi się do folderu lokalnego aplikacji. Aby uzyskać dostęp do plików w folderach mobilnych lub tymczasowych aplikacji, zamiast tego użyj polecenia "ms-appdata:///roaming/" lub "ms-appdata:///temporary/". Aby dowiedzieć się więcej na temat używania identyfikatorów URI aplikacji, zobacz Jak załadować zasoby plików.

Ponadto, w odróżnieniu od innych lokalizacji, można również uzyskać dostęp do plików w lokalizacjach danych aplikacji, korzystając z niektórych bibliotek Win32 i COM dla aplikacji WinUI oraz niektórych funkcji standardowych biblioteki C/C++ z Visual Studio.

Nie można uzyskać dostępu do folderów lokalnych, mobilnych ani tymczasowych za pośrednictwem selektora plików.

Uzyskiwanie dostępu do urządzeń wymiennych

Ponadto aplikacja może domyślnie uzyskiwać dostęp do niektórych plików na połączonych urządzeniach. Ta opcja jest dostępna, gdy aplikacja używa rozszerzenia AutoPlay do automatycznego uruchamiania, gdy użytkownicy podłączają urządzenie, takie jak aparat lub dysk USB, do systemu. Pliki, do których aplikacja może uzyskać dostęp, są ograniczone do określonych typów plików określonych za pomocą deklaracji skojarzenia typu pliku w manifeście aplikacji.

Oczywiście możesz również uzyskać dostęp do plików i folderów na urządzeniu wymiennym, wywołując selektor plików (przy użyciu narzędzia FileOpenPicker i FolderPicker) i pozwalając użytkownikowi wybrać pliki i foldery, aby aplikacja mogła uzyskać dostęp. Dowiedz się, jak używać selektora plików w obszarze Otwieranie plików i folderów za pomocą selektora.

Uwaga / Notatka

Aby uzyskać więcej informacji na temat uzyskiwania dostępu do karty SD lub innych urządzeń wymiennych, zobacz Uzyskiwanie dostępu do karty SD.

Folder pobierania użytkownika

Folder, w którym pobierane pliki są domyślnie zapisywane.

Domyślnie aplikacja może uzyskiwać dostęp tylko do plików i folderów w folderze Pobrane utworzonej przez aplikację użytkownika. Można jednak uzyskać dostęp do plików i folderów w folderze Pobrane przez użytkownika, wywołując selektor plików (FileOpenPicker lub FolderPicker), aby użytkownicy mogli nawigować i wybierać pliki lub foldery, aby aplikacja mogła uzyskać dostęp.

• Plik można utworzyć w folderze Pobrane użytkownika w ten sposób:

  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
  

  Folder plików do pobrania. Funkcja CreateFileAsync jest przeciążona, dzięki czemu można określić, co system powinien zrobić, jeśli w folderze Pobrane znajduje się już istniejący plik o tej samej nazwie. Po zakończeniu tych metod zwracają plik StorageFile reprezentujący utworzony plik. Ten plik nazywa się newFile w przykładzie.

• Podfolder można utworzyć w folderze Pobrane użytkownika w następujący sposób:

  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 jest przeciążony, aby określić, co system powinien zrobić, jeśli w folderze Downloads istnieje już podfolder o tej samej nazwie. Po zakończeniu tych metod zwracają folder StorageFolder reprezentujący utworzony podfolder. Ten plik nazywa się newFolder w przykładzie.

Uzyskiwanie dostępu do dodatkowych lokalizacji

Oprócz lokalizacji domyślnych aplikacja może uzyskiwać dostęp do dodatkowych plików i folderów, deklarując możliwości w manifeście aplikacji lub wywołując selektor plików , aby umożliwić użytkownikowi wybranie plików i folderów w celu uzyskania dostępu do aplikacji.

Aplikacje, które deklarują rozszerzenie AppExecutionAlias , mają uprawnienia systemu plików z katalogu, z którego są uruchamiane w oknie konsoli i w dół.

Zachowywanie dostępu do plików i folderów

Gdy aplikacja pobiera plik lub folder przez selektor, aktywację pliku, operację przeciągania i upuszczania itp., ma dostęp tylko do tego pliku lub folderu, dopóki aplikacja nie zostanie zamknięta. Jeśli chcesz automatycznie uzyskać dostęp do pliku lub folderu w przyszłości, możesz dodać go do listy FutureAccessList , aby aplikacja mogła łatwo uzyskać dostęp do tego elementu w przyszłości. Możesz również użyć listy MostRecentlyUsedList , aby łatwo zarządzać listą ostatnio używanych plików.

Możliwości uzyskiwania dostępu do innych lokalizacji

W poniższej tabeli wymieniono dodatkowe lokalizacje, do których można uzyskać dostęp, deklarując co najmniej jedną funkcję i używając skojarzonego interfejsu API Windows.Storage .

Lokalizacja	Zdolność	Windows.Storage API
Wszystkie pliki, do których użytkownik ma dostęp. Na przykład: dokumenty, obrazy, zdjęcia, pliki do pobrania, pulpit, usługa OneDrive itp.	szeroki dostęp do systemu plików Jest to ograniczona funkcja. Dostęp można skonfigurować w obszarze Ustawienia >> prywatności. Ponieważ użytkownicy mogą udzielić lub odrzucić uprawnienie w dowolnym momencie w obszarze Ustawienia, upewnij się, że aplikacja jest odporna na te zmiany. Jeśli okaże się, że aplikacja nie ma dostępu, możesz poprosić użytkownika o zmianę ustawienia, podając link do artykułu dostęp do systemu plików systemu Windows i prywatność . Należy pamiętać, że użytkownik musi zamknąć aplikację, przełączyć ustawienie i ponownie uruchomić aplikację. Jeśli przełączają ustawienie podczas działania aplikacji, platforma zawiesza aplikację, aby mógł zapisać stan, a następnie wymusza jej zakończenie, aby zastosować nowe ustawienie. W aktualizacji z kwietnia 2018 r. wartość domyślna dla uprawnienia to Włączone. W aktualizacji z października 2018 r. wartość domyślna to Wyłączone. Jeśli prześlesz aplikację do Sklepu, która deklaruje tę możliwość, musisz podać dodatkowe opisy powodów, dla których aplikacja potrzebuje tej możliwości i jak zamierza jej używać. Ta funkcja działa w przypadku interfejsów API w przestrzeni nazw Windows.Storage . Zobacz sekcję Przykład na końcu tego artykułu, aby zapoznać się z przykładem włączania tej funkcji w aplikacji. Uwaga: Ta funkcja nie jest obsługiwana na konsoli Xbox.	n/a
Documents	bibliotekaDokumentów Uwaga: do manifestu aplikacji należy dodać skojarzenia typu pliku, które deklarują określone typy plików, do których aplikacja ma dostęp w tej lokalizacji. Użyj tej możliwości, jeśli aplikacja: — Ułatwia międzyplatformowy dostęp w trybie offline do określonej zawartości usługi OneDrive przy użyciu prawidłowych adresów URL usługi OneDrive lub identyfikatorów zasobów — Automatycznie zapisuje otwarte pliki w usłudze OneDrive użytkownika w trybie offline	KnownFolders.DocumentsLibrary
Music	biblioteka muzyczna Zobacz również pliki i foldery w bibliotekach Muzyka, Obrazy i Wideo.	KnownFolders.MusicLibrary
Pictures	bibliotekaObrazów Zobacz również pliki i foldery w bibliotekach Muzyka, Obrazy i Wideo.	KnownFolders.PicturesLibrary
Videos	bibliotekaWideo Zobacz również pliki i foldery w bibliotekach Muzyka, Obrazy i Wideo.	KnownFolders.VideosLibrary
Urządzenia wymienne	pamięć przenośna Uwaga Do manifestu aplikacji należy dodać skojarzenia typu pliku, które deklarują określone typy plików, do których aplikacja ma dostęp w tej lokalizacji. Zobacz również Dostęp do karty SD.	KnownFolders.RemovableDevices
Biblioteki grup domowych	Wymagana jest co najmniej jedna z następujących funkcji. - biblioteka muzyki - biblioteka zdjęć - Biblioteka filmów	KnownFolders.HomeGroup
Urządzenia serwera multimediów (DLNA)	Wymagana jest co najmniej jedna z następujących funkcji. - biblioteka muzyki - zdjęciaBiblioteka - biblioteka filmów	KnownFolders.MediaServerDevices
Katalogi systemu Universal Naming Convention (UNC)	Wymagana jest kombinacja następujących możliwości. Możliwości sieci domowych i służbowych: - klient-serwer sieci prywatnej Co najmniej jedna funkcja internetu i sieci publicznych: - InternetClient - InternetClientServer A jeśli ma to zastosowanie, możliwości poświadczeń domeny: — uwierzytelnianie przedsiębiorstwa Uwaga: Do manifestu aplikacji należy dodać skojarzenia typu pliku, które deklarują określone typy plików, do których aplikacja ma dostęp w tej lokalizacji.	Pobierz folder przy użyciu: StorageFolder.GetFolderFromPathAsync Pobierz plik przy użyciu: StorageFile.GetFileFromPathAsync

Przykład

W tym przykładzie dodano funkcję broadFileSystemAccess z ograniczeniami. Oprócz określenia możliwości należy dodać przestrzeń nazw rescap, a także dodaje się ją do IgnorableNamespaces.

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

Uwaga / Notatka

Aby uzyskać pełną listę możliwości aplikacji, zobacz Deklaracje możliwości aplikacji.