Izin akses file

Artikel
07/13/2023

aplikasi Platform Windows Universal (UWP) dapat mengakses lokasi sistem file tertentu secara default. Aplikasi juga dapat mengakses lokasi tambahan melalui pemilih 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:

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 selengkapnya tentang bekerja dengan paket aplikasi Anda dan menginstal direktori dari sampel informasi paket Aplikasi di GitHub.

Anda dapat mengambil file langsung dari direktori penginstalan aplikasi dengan menggunakan URI aplikasi, 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, GetFile 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 selengkapnya 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 dengan menggunakan beberapa aplikasi Win32 dan COM untuk aplikasi Platform Windows Universal (UWP) dan beberapa fungsi Pustaka Standar C/C++ dari Microsoft Visual Studio.

Direktori penginstalan aplikasi adalah lokasi baca-saja. Anda tidak dapat memperoleh akses ke direktori penginstalan melalui pemilih 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:

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 folder roaming atau sementara aplikasi, gunakan properti RoamingFolder atau TemporaryFolder sebagai gantinya.

Setelah 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 selengkapnya tentang menggunakan lokasi data aplikasi dari panduan di halaman kelas ApplicationData, dan dengan mengunduh sampel data Aplikasi dari GitHub.

Anda dapat mengambil file langsung dari folder lokal aplikasi dengan menggunakan URI aplikasi, 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, getFile 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 folder roaming atau sementara aplikasi, gunakan "ms-appdata:///roaming/" atau "ms-appdata:///temporary/" sebagai gantinya. Anda dapat mempelajari selengkapnya 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 dengan menggunakan beberapa win32 dan COM untuk aplikasi UWP dan beberapa fungsi Pustaka Standar C/C++ dari Visual Studio.

Anda tidak dapat mengakses folder lokal, roaming, atau sementara melalui pemilih 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 drive jempol USB, ke sistem mereka. File yang dapat diakses aplikasi Anda terbatas pada jenis file tertentu yang ditentukan melalui deklarasi Asosiasi Jenis File di manifes aplikasi Anda.

Tentu saja, Anda juga dapat memperoleh akses ke file dan folder pada perangkat yang dapat dilepas dengan memanggil pemilih 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 pemilih.

Catatan

Untuk informasi 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 pemilih 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
});

UnduhanFolder.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 dipanggil 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
});

UnduhanFolder.CreateFolderAsync kelebihan beban sehingga Anda dapat menentukan apa yang harus dilakukan sistem jika sudah ada subfolder di folder Unduhan yang memiliki nama yang sama. Ketika metode ini selesai, mereka mengembalikan StorageFolder yang mewakili subfolder yang dibuat. File ini dipanggil newFolder dalam contoh.

Mengakses lokasi tambahan

Selain lokasi default, aplikasi dapat mengakses file dan folder tambahan dengan mendeklarasikan kemampuan dalam manifes aplikasi atau dengan memanggil pemilih 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 pemilih, aktivasi file, operasi seret dan letakkan, dll. aplikasi hanya memiliki akses ke file atau folder tersebut hingga aplikasi dihentikan. Jika Anda ingin mengakses file atau folder secara otomatis 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-baru ini digunakan dengan mudah.

Kemampuan untuk mengakses lokasi lain

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

Lokasi	Kemampuan	Windows.Storage API
Semua file yang dapat diakses pengguna. Misalnya: dokumen, gambar, foto, unduhan, desktop, OneDrive, dll.	broadFileSystemAccess Ini adalah kemampuan terbatas. Akses dapat dikonfigurasi dalam sistem File Privasi>Pengaturan>. Karena pengguna dapat memberikan atau menolak izin kapan saja di Pengaturan, Anda harus memastikan bahwa aplikasi Anda tahan terhadap perubahan tersebut. Jika menemukan bahwa aplikasi Anda tidak memiliki akses, Anda dapat memilih untuk meminta pengguna mengubah pengaturan dengan menyediakan tautan ke artikel akses dan privasi sistem file Windows. Perhatikan bahwa pengguna harus menutup aplikasi, mengalihkan pengaturan, dan menghidupkan ulang aplikasi. Jika mereka beralih ke pengaturan saat aplikasi berjalan, platform akan menangguhkan aplikasi Anda sehingga Anda dapat menyimpan status, lalu menghentikan aplikasi secara paksa untuk menerapkan pengaturan baru. Dalam pembaruan April 2018, default untuk izin adalah Aktif. Dalam pembaruan Oktober 2018, defaultnya adalah Nonaktif. Jika Anda mengirimkan aplikasi ke Toko yang mendeklarasikan kemampuan ini, Anda harus memberikan deskripsi tambahan tentang mengapa aplikasi Anda membutuhkan kemampuan ini, dan bagaimana aplikasi ingin menggunakannya. Kemampuan ini berfungsi untuk API di namespace Windows.Storage. Lihat bagian Contoh di akhir artikel ini untuk contoh cara mengaktifkan kemampuan ini di aplikasi Anda. Catatan: 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 atau ID Sumber Daya yang valid - Menyimpan file 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
Foto	gambarLibrary 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 salah satu kemampuan berikut diperlukan. - musicLibrary - gambarLibrary - videoLibrary	KnownFolders.HomeGroup
Perangkat server media (DLNA)	Setidaknya salah satu kemampuan berikut diperlukan. - musicLibrary - gambarLibrary - videoLibrary	KnownFolders.MediaServerDevices
Folder Universal Naming Convention (UNC)	Kombinasi kemampuan berikut diperlukan. Kemampuan jaringan rumah dan kantor: - privateNetworkClientServer Dan setidaknya satu kemampuan internet dan jaringan publik: - internetClient - internetClientServer Dan, jika berlaku, kemampuan kredensial domain: - enterpriseAuthentication Catatan: Anda harus menambahkan Asosiasi Jenis 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>