Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Aplikasi Microsoft Windows sering bergantung pada file yang berisi data yang tidak dapat dieksekusi, seperti Extensible Application Markup Language (XAML), gambar, video, dan audio. Windows Presentation Foundation (WPF) menawarkan dukungan khusus untuk mengonfigurasi, mengidentifikasi, dan menggunakan jenis file data ini, yang disebut file data aplikasi. Dukungan ini berputar di sekitar sekumpulan jenis file data aplikasi tertentu, termasuk:
File Sumber Daya: File data yang dikompilasi ke dalam rakitan WPF yang dapat dieksekusi atau pustaka.
File Konten: File data mandiri yang memiliki asosiasi eksplisit dengan rakitan WPF yang dapat dieksekusi.
Situs File Asal: File data mandiri yang tidak memiliki asosiasi dengan rakitan WPF yang dapat dieksekusi.
Salah satu perbedaan penting yang harus dibuat antara ketiga jenis file ini adalah bahwa file sumber daya dan file konten diketahui pada waktu build; assembly memiliki pengetahuan eksplisit tentang mereka. Namun, untuk berkas asal situs, komponen mungkin tidak memiliki pengetahuan tentang berkas tersebut sama sekali, atau pengetahuan implisit melalui referensi pengidentifikasi sumber daya seragam (URI); dalam hal yang terakhir, tidak ada jaminan bahwa berkas asal situs yang direferensikan benar-benar ada.
Untuk mereferensikan file data aplikasi, Windows Presentation Foundation (WPF) menggunakan Skema Pengidentifikasi sumber daya seragam Paket (URI), yang dijelaskan secara rinci dalam URI Paket di WPF).
Topik ini menjelaskan cara mengonfigurasi dan menggunakan file data aplikasi.
File Sumber Daya
Jika file data aplikasi harus selalu tersedia untuk aplikasi, satu-satunya cara untuk menjamin ketersediaan adalah dengan mengkompilasinya ke dalam rakitan utama aplikasi yang dapat dieksekusi atau salah satu rakitan yang dirujuk. Jenis file data aplikasi ini dikenal sebagai file sumber daya.
Anda harus menggunakan file sumber daya saat:
Anda tidak perlu memperbarui konten file sumber daya setelah dikompilasi ke dalam rakitan.
Anda ingin menyederhanakan kompleksitas distribusi aplikasi dengan mengurangi jumlah dependensi file.
File data aplikasi Anda harus dapat dilokalisasi (lihat Gambaran Umum Globalisasi dan Pelokalan WPF).
Nota
File sumber daya yang dijelaskan di bagian ini berbeda dari file sumber daya yang dijelaskan dalam Sumber Daya XAML dan berbeda dari sumber daya yang disematkan atau ditautkan yang dijelaskan dalam Mengelola Sumber Daya Aplikasi (.NET).
Mengonfigurasi File Sumber Daya
Di WPF, berkas sumber daya adalah berkas yang disertakan dalam proyek mesin build Microsoft (MSBuild) sebagai item Resource.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >
...
<ItemGroup>
<Resource Include="ResourceFile.xaml" />
</ItemGroup>
...
</Project>
Nota
Di Visual Studio, Anda membuat file sumber daya dengan menambahkan file ke proyek dan mengaturnya Build Action ke Resource.
Ketika proyek dibangun, MSBuild mengkompilasi sumber daya ke dalam rakitan.
Menggunakan File Sumber Daya
Untuk memuat file sumber daya, Anda dapat memanggil GetResourceStream metode Application kelas, meneruskan URI paket yang mengidentifikasi file sumber daya yang diinginkan. GetResourceStream StreamResourceInfo mengembalikan objek, yang mengekspos file sumber daya sebagai Stream dan menjelaskan jenis kontennya.
Sebagai contoh, kode berikut menunjukkan cara menggunakan GetResourceStream untuk memuat Page file sumber daya dan mengaturnya sebagai konten (FramepageFrame):
// Navigate to xaml page
Uri uri = new Uri("/PageResourceFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetResourceStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;
' Navigate to xaml page
Dim uri As New Uri("/PageResourceFile.xaml", UriKind.Relative)
Dim info As StreamResourceInfo = Application.GetResourceStream(uri)
Dim reader As New System.Windows.Markup.XamlReader()
Dim page As Page = CType(reader.LoadAsync(info.Stream), Page)
Me.pageFrame.Content = page
Saat memanggil GetResourceStream memberi Anda akses ke Stream, Anda perlu melakukan pekerjaan tambahan untuk mengonversinya ke jenis properti yang akan Anda atur. Sebagai gantinya, Anda dapat membiarkan WPF menangani pembukaan dan konversi Stream dengan memuat file sumber daya langsung ke properti suatu tipe menggunakan kode.
Contoh berikut menunjukkan cara memuat Page langsung ke dalam Frame (pageFrame) menggunakan kode.
Uri pageUri = new Uri("/PageResourceFile.xaml", UriKind.Relative);
this.pageFrame.Source = pageUri;
Dim pageUri As New Uri("/PageResourceFile.xaml", UriKind.Relative)
Me.pageFrame.Source = pageUri
Contoh berikut adalah markup yang setara dengan contoh sebelumnya.
<Frame Name="pageFrame" Source="PageResourceFile.xaml" />
File Kode Aplikasi sebagai File Sumber Daya
Sekumpulan file kode aplikasi WPF khusus dapat dirujuk menggunakan URI paket, termasuk windows, halaman, dokumen alur, dan kamus sumber daya. Misalnya, Anda dapat mengatur Application.StartupUri properti dengan URI paket yang mereferensikan jendela atau halaman yang ingin Anda muat saat aplikasi dimulai.
<Application
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="SOOPage.xaml" />
Anda dapat melakukan ini ketika file XAML disertakan dalam proyek MSBuild sebagai Page item.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >
...
<ItemGroup>
<Page Include="MainWindow.xaml" />
</ItemGroup>
...
</Project>
Nota
Di Visual Studio, Anda menambahkan Window, NavigationWindow, Page, FlowDocument, atau ResourceDictionary baru ke proyek, Build Action untuk file markup akan default ke Page.
Saat proyek dengan Page item dikompilasi, item XAML dikonversi ke format biner dan dikompilasi ke dalam rakitan terkait. Akibatnya, file-file ini dapat digunakan dengan cara yang sama seperti file sumber daya biasa.
Nota
Jika file XAML dikonfigurasi sebagai Resource item, dan tidak memiliki file code-behind, XAML mentah dikompilasi ke dalam rakitan, bukan versi biner dari XAML mentah.
File Isi
File konten didistribusikan sebagai file terpisah bersama assembly yang dapat dijalankan. Meskipun tidak dikompilasi ke dalam rakitan, rakitan dikompilasi dengan metadata yang membangun asosiasi dengan setiap file konten.
Anda harus menggunakan file konten saat aplikasi Anda memerlukan sekumpulan file data aplikasi tertentu yang ingin Anda perbarui tanpa menyusun ulang rakitan yang mengonsumsinya.
Mengonfigurasi File Konten
Untuk menambahkan file konten ke proyek, file data aplikasi harus disertakan sebagai Content item. Selain itu, karena file konten tidak dikompilasi langsung ke dalam rakitan, Anda perlu mengatur elemen metadata MSBuild CopyToOutputDirectory untuk menentukan bahwa file konten disalin ke lokasi yang relatif terhadap rakitan bawaan. Jika Anda ingin sumber daya disalin ke folder output build setiap kali proyek dibuat, Anda mengatur CopyToOutputDirectory elemen metadata dengan Always nilai . Jika tidak, Anda dapat memastikan bahwa hanya versi terbaru sumber daya yang disalin ke folder output build dengan menggunakan nilai PreserveNewest.
Berikut ini memperlihatkan file yang dikonfigurasi sebagai file konten yang disalin ke folder output build hanya ketika versi baru sumber daya ditambahkan ke proyek.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >
...
<ItemGroup>
<Content Include="ContentFile.xaml">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</Content>
</ItemGroup>
...
</Project>
Nota
Di Visual Studio, Anda membuat file konten dengan menambahkan file ke proyek dan mengatur Build Action ke Content, serta mengatur Copy to Output Directory ke Copy always (sama dengan Always) dan Copy if newer (sama dengan PreserveNewest).
Saat proyek dibangun, sebuah atribut AssemblyAssociatedContentFileAttribute dikompilasikan ke dalam metadata assembly untuk setiap file konten.
[assembly: AssemblyAssociatedContentFile("ContentFile.xaml")]
Nilai AssemblyAssociatedContentFileAttribute menyiratkan jalur ke file konten relatif terhadap posisinya dalam proyek. Misalnya, jika file konten terletak di subfolder proyek, informasi jalur tambahan akan dimasukkan ke dalam nilai AssemblyAssociatedContentFileAttribute.
[assembly: AssemblyAssociatedContentFile("Resources/ContentFile.xaml")]
Nilai AssemblyAssociatedContentFileAttribute ini juga merupakan nilai jalur ke file konten di folder output build.
Menggunakan File Konten
Untuk memuat file konten, Anda dapat memanggil GetContentStream metode Application kelas, meneruskan URI paket yang mengidentifikasi file konten yang diinginkan. GetContentStream StreamResourceInfo mengembalikan objek, yang mengekspos file konten sebagai Stream dan menjelaskan jenis kontennya.
Sebagai contoh, kode berikut menunjukkan cara menggunakan GetContentStream untuk memuat Page file konten dan mengaturnya sebagai konten Frame (pageFrame).
// Navigate to xaml page
Uri uri = new Uri("/PageContentFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetContentStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;
' Navigate to xaml page
Dim uri As New Uri("/PageContentFile.xaml", UriKind.Relative)
Dim info As StreamResourceInfo = Application.GetContentStream(uri)
Dim reader As New System.Windows.Markup.XamlReader()
Dim page As Page = CType(reader.LoadAsync(info.Stream), Page)
Me.pageFrame.Content = page
Saat memanggil GetContentStream memberi Anda akses ke Stream, Anda perlu melakukan pekerjaan tambahan untuk mengonversinya ke jenis properti yang akan Anda atur. Sebagai gantinya, Anda dapat membiarkan WPF menangani pembukaan dan konversi Stream dengan memuat file sumber daya langsung ke properti suatu tipe menggunakan kode.
Contoh berikut menunjukkan cara memuat Page langsung ke dalam Frame (pageFrame) menggunakan kode.
Uri pageUri = new Uri("/PageContentFile.xaml", UriKind.Relative);
this.pageFrame.Source = pageUri;
Dim pageUri As New Uri("/PageContentFile.xaml", UriKind.Relative)
Me.pageFrame.Source = pageUri
Contoh berikut adalah markup yang setara dengan contoh sebelumnya.
<Frame Name="pageFrame" Source="PageContentFile.xaml" />
Situs Sumber Berkas
File sumber daya memiliki hubungan eksplisit dengan rakitan yang didistribusikan bersama, seperti yang didefinisikan oleh AssemblyAssociatedContentFileAttribute. Namun, ada kalanya Anda mungkin ingin membuat hubungan implisit atau tidak ada antara assembly dan file data aplikasi, misalnya ketika:
File tidak ada pada waktu kompilasi.
Anda tidak tahu file apa yang akan diperlukan oleh assembly Anda sampai waktu berjalan.
Anda ingin dapat memperbarui file tanpa menyusun ulang rakitan yang terkait dengannya.
Aplikasi Anda menggunakan file data besar, seperti audio dan video, dan Anda hanya ingin pengguna mengunduhnya jika mereka memilih.
Dimungkinkan untuk memuat jenis file ini dengan menggunakan skema URI tradisional, seperti file:/// skema dan http:// .
<Image Source="file:///C:/DataFile.bmp" />
<Image Source="http://www.datafilewebsite.com/DataFile.bmp" />
Namun, skema file:/// dan http:// mengharuskan aplikasi Anda memiliki tingkat kepercayaan penuh. Jika aplikasi Anda adalah aplikasi browser XAML (XBAP) yang diluncurkan dari Internet atau intranet, dan hanya meminta serangkaian izin yang diizinkan untuk aplikasi yang diluncurkan dari lokasi tersebut, file longgar hanya dapat dimuat dari situs asal aplikasi (lokasi peluncuran). File tersebut dikenal sebagai situs file asal .
Situs file asal adalah satu-satunya opsi untuk aplikasi kepercayaan parsial, meskipun tidak terbatas pada aplikasi kepercayaan parsial. Aplikasi dengan kepercayaan penuh mungkin masih perlu memuat file data aplikasi yang tidak mereka ketahui saat proses build; sementara aplikasi dengan kepercayaan penuh dapat menggunakan file:///, kemungkinan file data aplikasi akan diinstal di folder yang sama dengan, atau subfolder dari, rakitan aplikasi. Dalam hal ini, menggunakan situs referensi asal lebih mudah daripada menggunakan file:///, karena menggunakan file:/// mengharuskan Anda untuk menyelesaikan jalur lengkap file.
Nota
Situs file asal tidak di-cache dengan aplikasi browser XAML (XBAP) pada komputer klien, sementara file konten berada. Akibatnya, mereka hanya diunduh ketika diminta secara khusus. Jika aplikasi browser XAML (XBAP) memiliki file media besar, mengonfigurasinya sebagai situs file asal berarti peluncuran aplikasi awal jauh lebih cepat, dan file hanya diunduh sesuai permintaan.
Mengonfigurasi Situs File Asal
Jika situs file asal Anda tidak ada atau tidak diketahui pada waktu kompilasi, Anda perlu menggunakan mekanisme penyebaran tradisional untuk memastikan file yang diperlukan tersedia pada waktu proses, termasuk menggunakan XCopy program baris perintah atau Alat Penginstal Microsoft Windows.
Jika Anda tahu pada waktu kompilasi file yang ingin Anda letakkan di situs asal, tetapi masih ingin menghindari dependensi eksplisit, Anda dapat menambahkan file tersebut ke proyek MSBuild sebagai None item. Seperti halnya file konten, Anda perlu mengatur atribut MSBuild CopyToOutputDirectory untuk menentukan bahwa asal lokasi file disalin ke lokasi yang relatif terhadap rakitan yang dibangun, dengan menentukan nilai Always atau PreserveNewest.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >
...
<None Include="PageSiteOfOriginFile.xaml">
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>
...
</Project>
Nota
Di Visual Studio, Anda membuat situs file asal dengan menambahkan file ke proyek dan mengaturnya Build Action ke None.
Saat proyek dibangun, MSBuild menyalin file yang ditentukan ke folder output build.
Menggunakan File Situs Asal
Untuk memuat file sumber asal, Anda dapat memanggil metode GetRemoteStream dari kelas Application, meneruskan URI paket yang mengidentifikasi file sumber asal yang diinginkan. GetRemoteStream StreamResourceInfo mengembalikan objek, yang mengekspos situs file asal sebagai Stream dan menjelaskan jenis kontennya.
Sebagai contoh, kode berikut menunjukkan cara menggunakan GetRemoteStream untuk memuat Page situs file asal dan mengaturnya sebagai konten Frame (pageFrame).
// Navigate to xaml page
Uri uri = new Uri("/SiteOfOriginFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetRemoteStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;
' Navigate to xaml page
Dim uri As New Uri("/SiteOfOriginFile.xaml", UriKind.Relative)
Dim info As StreamResourceInfo = Application.GetRemoteStream(uri)
Dim reader As New System.Windows.Markup.XamlReader()
Dim page As Page = CType(reader.LoadAsync(info.Stream), Page)
Me.pageFrame.Content = page
Saat memanggil GetRemoteStream memberi Anda akses ke Stream, Anda perlu melakukan pekerjaan tambahan untuk mengonversinya ke jenis properti yang akan Anda atur. Sebagai gantinya, Anda dapat membiarkan WPF menangani pembukaan dan konversi Stream dengan memuat file sumber daya langsung ke properti suatu tipe menggunakan kode.
Contoh berikut menunjukkan cara memuat Page langsung ke dalam Frame (pageFrame) menggunakan kode.
Uri pageUri = new Uri("pack://siteoforigin:,,,/SiteOfOriginFile.xaml", UriKind.Absolute);
this.pageFrame.Source = pageUri;
Dim pageUri As New Uri("pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml", UriKind.Absolute)
Me.pageFrame.Source = pageUri
Contoh berikut adalah markup yang setara dengan contoh sebelumnya.
<Frame Name="pageFrame" Source="pack://siteoforigin:,,,/SiteOfOriginFile.xaml" />
Membangun Kembali Setelah Mengubah Jenis Build
Setelah mengubah jenis build file data aplikasi, Anda perlu membangun kembali seluruh aplikasi untuk memastikan perubahan tersebut diterapkan. Jika Anda hanya membuat aplikasi, perubahan tidak diterapkan.
Lihat juga
Berkolaborasi dengan kami di GitHub
Sumber untuk konten ini dapat ditemukan di GitHub, yang juga dapat Anda gunakan untuk membuat dan meninjau masalah dan menarik permintaan. Untuk informasi selengkapnya, lihat panduan kontributor kami.
.NET Desktop feedback