Izin akses file

Aplikasi Universal Windows Platform (UWP) dapat mengakses lokasi sistem file tertentu secara default. Aplikasi juga dapat mengakses lokasi tambahan melalui pemetik file, atau dengan mendeklarasikan kemampuan.

Lokasi yang dapat diakses aplikasi UWP

Saat membuat aplikasi baru, Anda dapat mengakses lokasi sistem file berikut secara default:

Direktori penginstalan aplikasi

Folder tempat aplikasi Anda diinstal pada sistem pengguna.

Ada dua cara utama untuk mengakses file dan folder di direktori penginstalan aplikasi Anda:

  1. Anda dapat mengambil StorageFolder yang mewakili direktori penginstalan aplikasi Anda, seperti ini:

    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;
    

    Anda kemudian dapat mengakses file dan folder di direktori menggunakan metode StorageFolder . Dalam contoh, StorageFolder ini disimpan dalam installDirectory variabel. Anda dapat mempelajari lebih lanjut tentang bekerja dengan paket aplikasi dan menginstal direktori dari sampel informasi paket Aplikasi di GitHub.

  2. Anda dapat mengambil file langsung dari direktori penginstalan aplikasi dengan menggunakan aplikasi URI, seperti ini:

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

    Ketika GetFileFromApplicationUriAsync selesai, ia mengembalikan StorageFile yang mewakili file.txt file di direktori penginstalan aplikasi (file dalam contoh).

    Awalan "ms-appx:///" di URI mengacu pada direktori penginstalan aplikasi. Anda dapat mempelajari lebih lanjut tentang menggunakan URI aplikasi di Cara menggunakan URI untuk mereferensikan konten.

Selain itu, dan tidak seperti lokasi lain, Anda juga dapat mengakses file di direktori penginstalan aplikasi Anda dengan menggunakan beberapa aplikasi Win32 dan COM untuk Universal Windows Platform (UWP) dan beberapa fungsi Perpustakaan Standar C /C++ dari Microsoft Visual Studio.

Direktori penginstalan aplikasi adalah lokasi baca-saja. Anda tidak dapat memperoleh akses ke direktori penginstalan melalui pemetik file.

Mengakses lokasi data aplikasi

Folder tempat aplikasi Anda dapat menyimpan data. Folder ini (lokal, roaming, dan sementara) dibuat saat aplikasi Anda diinstal.

Ada dua cara utama untuk mengakses file dan folder dari lokasi data aplikasi Anda:

  1. Gunakan properti ApplicationData untuk mengambil folder data aplikasi.

    Misalnya, Anda dapat menggunakan ApplicationData. LocalFolder untuk mengambil StorageFolder yang mewakili folder lokal aplikasi Anda seperti ini:

    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;
    

    Jika Anda ingin mengakses roaming atau folder sementara aplikasi, gunakan properti RoamingFolder atau TemporaryFolder sebagai gantinya.

    Setelah anda mengambil StorageFolder yang mewakili lokasi data aplikasi, anda dapat mengakses file dan folder di lokasi tersebut dengan menggunakan metode StorageFolder . Dalam contoh, objek StorageFolder ini disimpan dalam localFolder variabel. Anda dapat mempelajari lebih lanjut tentang menggunakan lokasi data aplikasi dari panduan di halaman kelas ApplicationData, dan dengan mengunduh sampel data Aplikasi dari GitHub.

  2. Anda dapat mengambil file langsung dari folder lokal aplikasi Anda dengan menggunakan aplikasi URI, seperti ini:

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

    Ketika GetFileFromApplicationUriAsync selesai, ia mengembalikan StorageFile yang mewakili file.txt file di folder lokal aplikasi (file dalam contoh).

    Awalan "ms-appdata:///local/" di URI mengacu pada folder lokal aplikasi. Untuk mengakses file di roaming aplikasi atau folder sementara, gunakan "ms-appdata:///roaming/" atau "ms-appdata:///temporary/" sebagai gantinya. Anda dapat mempelajari lebih lanjut tentang menggunakan URI aplikasi di Cara memuat sumber daya file.

Selain itu, dan tidak seperti lokasi lain, Anda juga dapat mengakses file di lokasi data aplikasi Anda dengan menggunakan beberapa aplikasi Win32 dan COM untuk UWP dan beberapa fungsi Perpustakaan Standar C /C ++ dari Visual Studio.

Anda tidak dapat mengakses folder lokal, roaming, atau sementara melalui pemetik file.

Mengakses perangkat yang dapat dilepas

Selain itu, aplikasi Anda dapat mengakses beberapa file di perangkat yang terhubung secara default. Ini adalah opsi jika aplikasi Anda menggunakan ekstensi AutoPlay untuk diluncurkan secara otomatis saat pengguna menghubungkan perangkat, seperti kamera atau USB thumb drive, ke sistem mereka. File yang dapat diakses aplikasi Anda terbatas pada jenis file tertentu yang ditentukan melalui deklarasi Asosiasi Tipe File dalam manifes aplikasi Anda.

Tentu saja, Anda juga dapat memperoleh akses ke file dan folder pada perangkat yang dapat dilepas dengan memanggil pemetik file (menggunakan FileOpenPicker dan FolderPicker) dan membiarkan pengguna memilih file dan folder untuk diakses aplikasi Anda. Pelajari cara menggunakan pemilih file di Buka file dan folder dengan pemetik.

Catatan

Untuk info selengkapnya tentang mengakses kartu SD atau perangkat lain yang dapat dilepas, lihat Mengakses kartu SD.

Folder Unduhan Pengguna

Folder tempat file yang diunduh disimpan secara default.

Secara default, aplikasi Anda hanya dapat mengakses file dan folder di folder Unduhan pengguna yang dibuat aplikasi Anda. Namun, Anda dapat memperoleh akses ke file dan folder di folder Unduhan pengguna dengan memanggil pemetik file (FileOpenPicker atau FolderPicker) sehingga pengguna dapat menavigasi dan memilih file atau folder untuk diakses aplikasi Anda.

  • Anda dapat membuat file di folder Unduhan pengguna seperti ini:

    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 kelebihan beban sehingga Anda dapat menentukan apa yang harus dilakukan sistem jika sudah ada file yang ada di folder Unduhan yang memiliki nama yang sama. Ketika metode ini selesai, mereka mengembalikan StorageFile yang mewakili file yang dibuat. File ini disebut newFile dalam contoh.

  • Anda dapat membuat subfolder di folder Unduhan pengguna seperti ini:

    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 kelebihan beban sehingga Anda dapat menentukan apa yang harus dilakukan sistem jika sudah ada subfolder yang ada di folder Unduhan yang memiliki nama yang sama. Ketika metode ini selesai, mereka mengembalikan StorageFolder yang mewakili subfolder yang dibuat. File ini disebut newFolder dalam contoh.

Mengakses lokasi tambahan

Selain lokasi default, aplikasi dapat mengakses file dan folder tambahan dengan mendeklarasikan kemampuan dalam manifes aplikasi atau denganmemanggil pemetik file untuk memungkinkan pengguna memilih file dan folder untuk diakses aplikasi.

Aplikasi yang mendeklarasikan ekstensi AppExecutionAlias memiliki izin sistem file dari direktori tempat mereka diluncurkan di jendela konsol, dan ke bawah.

Mempertahankan akses ke file dan folder

Saat aplikasi Anda mengambil file atau folder melalui pemetik, aktivasi file, operasi seret dan lepas, dll. aplikasi hanya memiliki akses ke file atau folder tersebut sampai aplikasi dihentikan. Jika Anda ingin secara otomatis mengakses file atau folder di masa mendatang, Anda dapat menambahkannya ke FutureAccessList sehingga aplikasi Anda dapat dengan mudah mengakses item tersebut di masa mendatang. Anda juga dapat menggunakan MostRecentlyUsedList untuk mengelola daftar file yang baru digunakan dengan mudah.

Kemampuan untuk mengakses lokasi lain

Tabel berikut mencantumkan lokasi tambahan yang dapat Anda akses dengan mendeklarasikan satu atau beberapa kemampuan dan menggunakan Windows.Storage API.

Lokasi Kemampuan Windows. api Storage
Semua file yang dapat diakses pengguna. Misalnya: dokumen, gambar, foto, unduhan, desktop, OneDrive, dll. broadFileSystemAccess

Ini adalah kemampuan yang terbatas. Akses dapat dikonfigurasi dalam sistem Pengaturan>PrivacyFile>. Karena pengguna dapat memberikan atau menolak izin kapan saja dalam Pengaturan, Anda harus memastikan bahwa aplikasi Anda tahan terhadap perubahan tersebut. Jika Anda menemukan bahwa aplikasi Anda tidak memiliki akses, Anda dapat memilih untuk meminta pengguna untuk mengubah pengaturan dengan menyediakan tautan ke akses sistem file Windows 10 dan artikel privasi. Perhatikan bahwa pengguna harus menutup aplikasi, mengalihkan pengaturan, dan memulai ulang aplikasi. Jika mereka beralih pengaturan saat aplikasi berjalan, platform akan menangguhkan aplikasi Anda sehingga Anda dapat menyimpan status, kemudian secara paksa menghentikan aplikasi untuk menerapkan pengaturan baru. Dalam pembaruan April 2018, default untuk izin adalah Menyala. Dalam pembaruan Oktober 2018, defaultnya adalah Mati.

Jika Anda mengirimkan aplikasi ke Toko yang menyatakan kemampuan ini, Anda harus memberikan deskripsi tambahan tentang mengapa aplikasi Anda membutuhkan kemampuan ini, dan bagaimana ia bermaksud menggunakannya.

Kemampuan ini berfungsi untuk API di ruang nama Windows.Storage. Lihat bagian Contoh di akhir artikel ini untuk contoh cara mengaktifkan kemampuan ini di aplikasi Anda.

Nota: Kemampuan ini tidak didukung di Xbox.
n/a
Dokumen documentsLibrary

Catatan: Anda harus menambahkan Asosiasi Jenis File ke manifes aplikasi yang mendeklarasikan jenis file tertentu yang dapat diakses aplikasi Anda di lokasi ini.

Gunakan kemampuan ini jika aplikasi Anda:
Memfasilitasi akses offline lintas platform ke konten OneDrive tertentu menggunakan URL OneDrive yang valid atau ID Sumber Daya
- Menyimpan file yang terbuka ke OneDrive pengguna secara otomatis saat offline
KnownFolders.DocumentsLibrary
Musik musicLibrary
Lihat juga File dan folder di pustaka Musik, Gambar, dan Video.
KnownFolders.MusicLibrary
Gambar picturesLibrary
Lihat juga File dan folder di pustaka Musik, Gambar, dan Video.
KnownFolders.PicturesLibrary
Video videoLibrary
Lihat juga File dan folder di pustaka Musik, Gambar, dan Video.
KnownFolders.VideosLibrary
Perangkat yang dapat dilepas removableStorage

Catatan Anda harus menambahkan Asosiasi Jenis File ke manifes aplikasi yang mendeklarasikan jenis file tertentu yang dapat diakses aplikasi Anda di lokasi ini.

Lihat juga Mengakses kartu SD.
KnownFolders.RemovableDevices
Pustaka grup rumah Setidaknya satu dari kemampuan berikut diperlukan.
- musicLibrary
- picturesLibrary
- videoLibrary
KnownFolders.HomeGroup
Perangkat server media (DLNA) Setidaknya satu dari kemampuan berikut diperlukan.
- musicLibrary
- picturesLibrary
- videoLibrary
KnownFolders.MediaServerDevices
Folder Konvensi Penamaan Universal (UNC) Kombinasi kemampuan berikut diperlukan.

Kemampuan jaringan rumah dan kerja:
- privateNetworkClientServer

Dan setidaknya satu kemampuan internet dan jaringan publik:
- internetClient
- server internetClient

Dan, jika berlaku, kemampuan kredensial domain:
- enterpriseAuthentication

Nota: Anda harus menambahkan Asosiasi Tipe File ke manifes aplikasi yang mendeklarasikan jenis file tertentu yang dapat diakses aplikasi Anda di lokasi ini.
Ambil folder menggunakan:
StorageFolder.GetFolderFromPathAsync

Ambil file menggunakan:
StorageFile.GetFileFromPathAsync

Contoh

Contoh ini menambahkan kemampuan broadFileSystemAccess yang dibatasi. Selain menentukan kemampuan, rescap namespace harus ditambahkan, dan juga ditambahkan ke IgnorableNamespaces.

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

Catatan

Untuk daftar lengkap kemampuan aplikasi, lihat Deklarasi kemampuan aplikasi.