Bagikan melalui

Sumber Daya Aplikasi WPF, Konten, dan File Data

  • Artikel

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 situs file asal, perakitan mungkin tidak memiliki pengetahuan tentang mereka sama sekali, atau pengetahuan implisit melalui referensi pengidentifikasi sumber daya seragam paket (URI) ; kasus yang terakhir, tidak ada jaminan bahwa situs yang dirujuk dari file asal sebenarnya 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).

Catatan

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, file sumber daya adalah file yang disertakan dalam proyek mesin build Microsoft (MSBuild) sebagai Resource item.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >  
  ...  
  <ItemGroup>  
    <Resource Include="ResourceFile.xaml" />  
  </ItemGroup>  
  ...  
</Project>

Catatan

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. GetResourceStreamStreamResourceInfo 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 mengurus pembukaan dan konversi Stream dengan memuat file sumber daya langsung ke properti jenis 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>

Catatan

Di Visual Studio, Anda menambahkan , , , Page, atau ResourceDictionary baru Windowke proyek, Build Action untuk file markup akan default ke Page. FlowDocumentNavigationWindow

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.

Catatan

Jika file XAML dikonfigurasi sebagai Resource item, dan tidak memiliki file code-behind, XAML mentah dikompilasi ke dalam rakitan daripada versi biner dari XAML mentah.

File Isi

File konten didistribusikan sebagai file longgar bersama rakitan yang dapat dieksekusi. 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 PreserveNewest nilai .

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>

Catatan

Di Visual Studio, Anda membuat file konten dengan menambahkan file ke proyek dan mengaturnya ke , dan mengaturnya Copy to Output Directory ke Copy always (sama dengan Always) dan Copy if newer (sama dengan PreserveNewest).ContentBuild Action

Saat proyek dibangun, AssemblyAssociatedContentFileAttribute atribut dikompilasi ke dalam metadata perakitan 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 AssemblyAssociatedContentFileAttribute dalam nilai .

[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. GetContentStreamStreamResourceInfo 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 mengurus pembukaan dan konversi Stream dengan memuat file sumber daya langsung ke properti jenis 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 File Asal

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, termasuk kapan:

  • File tidak ada pada waktu kompilasi.

  • Anda tidak tahu file apa yang akan diperlukan assembly Anda hingga run time.

  • 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, file:/// skema dan http:// mengharuskan aplikasi Anda memiliki 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 kepercayaan penuh mungkin masih perlu memuat file data aplikasi yang tidak mereka ketahui pada waktu build; sementara aplikasi kepercayaan penuh dapat menggunakan file:///, kemungkinan file data aplikasi akan diinstal di folder yang sama seperti, atau subfolder, rakitan aplikasi. Dalam hal ini, menggunakan situs referensi asal lebih mudah daripada menggunakan file:///, karena menggunakan file:/// mengharuskan Anda untuk menyelesaikan jalur lengkap file.

Catatan

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 situs file asal disalin ke lokasi yang relatif terhadap rakitan bawaan Always , dengan menentukan nilai atau PreserveNewest nilai.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >  
  ...  
  <None Include="PageSiteOfOriginFile.xaml">  
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>  
  </None>  
  ...  
</Project>

Catatan

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 situs file asal, Anda dapat memanggil GetRemoteStream metode Application kelas , meneruskan URI paket yang mengidentifikasi situs file asal yang diinginkan. GetRemoteStreamStreamResourceInfo 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 mengurus pembukaan dan konversi Stream dengan memuat file sumber daya langsung ke properti jenis 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.

Baca juga