Bagikan melalui

Referensi file konfigurasi runtime direktif (rd.xml)

  • Artikel

File arahan runtime (.rd.xml) adalah file konfigurasi XML yang menentukan apakah elemen program yang ditunjuk tersedia untuk refleksi. Untuk informasi tentang cara dan tempat menambahkan arahan runtime ke proyek Anda, dan cara mengenalinya, lihat Pemecah masalah MissingMetadataException.

Berikut adalah contoh file arahan runtime:

<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
  <Application>
    <Namespace Name="Contoso.Cloud.AppServices" Serialize="Required Public" />
    <Namespace Name="ContosoClient.ViewModels" Serialize="Required Public" />
    <Namespace Name="ContosoClient.DataModel" Serialize="Required Public" />
    <Namespace Name="Contoso.Reader.UtilityLib" Serialize="Required Public" />

    <Namespace Name="System.Collections.ObjectModel" >
      <TypeInstantiation Name="ObservableCollection"
            Arguments="ContosoClient.DataModel.ProductItem" Serialize="Public" />
      <TypeInstantiation Name="ReadOnlyObservableCollection"
            Arguments="ContosoClient.DataModel.ProductGroup" Serialize="Public" />
    </Namespace>
  </Application>
</Directives>

Struktur file arahan runtime

File arahan runtime menggunakan http://schemas.microsoft.com/netfx/2013/01/metadata namespace layanan.

Elemen akar adalah elemen Direktif . Ini dapat berisi nol atau lebih elemen Pustaka , dan nol atau satu elemen Aplikasi , seperti yang ditunjukkan dalam struktur berikut. Atribut elemen Aplikasi dapat menentukan kebijakan refleksi runtime aplikasi di seluruh aplikasi, atau dapat berfungsi sebagai kontainer untuk elemen anak. Elemen Pustaka , di sisi lain, hanyalah kontainer. Turunan elemen Aplikasi dan Pustaka menentukan jenis, metode, bidang, properti, dan peristiwa yang tersedia untuk refleksi.

Untuk informasi referensi, pilih elemen dari struktur berikut atau lihat Elemen Arahan Runtime. Dalam hierarki berikut, elipsis menandai struktur rekursif. Informasi dalam tanda kurung menunjukkan apakah elemen tersebut opsional atau diperlukan, dan jika digunakan, berapa banyak instans (satu atau banyak) yang diizinkan.

Elemen Aplikasi tidak dapat memiliki atribut, atau dapat memiliki atribut kebijakan yang dibahas di bagian Arahan runtime dan kebijakan.

Elemen Pustaka memiliki atribut tunggal, Name, yang menentukan nama pustaka atau rakitan, tanpa ekstensi filenya. Misalnya, elemen Pustaka berikut berlaku untuk rakitan bernama Extensions.dll.

<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
  <Application>
     <!-- Child elements go here -->
  </Application>
  <Library Name="Extensions">
     <!-- Child elements go here -->
  </Library>
</Directives>

Arahan dan kebijakan runtime

Elemen Aplikasi itu sendiri dan elemen turunan dari elemen Pustaka dan Aplikasi mengekspresikan kebijakan; yaitu, mereka menentukan cara aplikasi dapat menerapkan refleksi ke elemen program. Jenis kebijakan didefinisikan oleh atribut elemen (misalnya, Serialize). Nilai kebijakan ditentukan oleh nilai atribut (misalnya, Serialize="Required").

Kebijakan apa pun yang ditentukan oleh atribut elemen berlaku untuk semua elemen turunan yang tidak menentukan nilai untuk kebijakan tersebut. Misalnya, jika kebijakan ditentukan oleh elemen Jenis , kebijakan tersebut berlaku untuk semua jenis dan anggota yang terkandung di mana kebijakan tidak ditentukan secara eksplisit.

Kebijakan yang dapat diekspresikan oleh elemen Aplikasi, Assembly, AttributeImplies, Namespace, Subtypes, dan Type berbeda dari kebijakan yang dapat dinyatakan untuk masing-masing anggota (dengan elemen Metode, Properti, Bidang, dan Peristiwa ).

Menentukan kebijakan untuk rakitan, namespace, dan jenis

Elemen Aplikasi, Assembly, AttributeImplies, Namespace, Subtipe, dan Type mendukung jenis kebijakan berikut:

  • Activate. Mengontrol akses runtime ke konstruktor, untuk mengaktifkan aktivasi instans.

  • Browse. Mengontrol kueri untuk informasi tentang elemen program tetapi tidak mengaktifkan akses runtime apa pun.

  • Dynamic. Mengontrol akses runtime ke semua anggota jenis, termasuk konstruktor, metode, bidang, properti, dan peristiwa, untuk mengaktifkan pemrograman dinamis.

  • Serialize. Mengontrol akses runtime ke konstruktor, bidang, dan properti, untuk memungkinkan instans jenis diserialisasikan dan diserialisasikan oleh pustaka pihak ketiga seperti serializer Newtonsoft JSON.

  • DataContractSerializer. Mengontrol kebijakan untuk serialisasi yang menggunakan System.Runtime.Serialization.DataContractSerializer kelas .

  • DataContractJsonSerializer. Mengontrol kebijakan untuk serialisasi JSON yang menggunakan System.Runtime.Serialization.DataContractSerializer kelas .

  • XmlSerializer. Mengontrol kebijakan untuk serialisasi XML yang menggunakan System.Xml.Serialization.XmlSerializer kelas .

  • MarshalObject. Mengontrol kebijakan untuk marshaling jenis referensi ke WinRT dan COM.

  • MarshalDelegate. Mengontrol kebijakan untuk marshaling mendelegasikan jenis sebagai penunjuk fungsi ke kode asli.

  • MarshalStructure . Mengontrol kebijakan untuk marshaling struktur ke kode asli.

Pengaturan yang terkait dengan jenis kebijakan ini adalah:

  • All. Aktifkan kebijakan untuk semua jenis dan anggota yang tidak dihapus oleh rantai alat.

  • Auto. Gunakan perilaku default. (Tidak menentukan kebijakan setara dengan mengatur kebijakan Auto tersebut kecuali kebijakan tersebut ditimpa, misalnya oleh elemen induk.)

  • Excluded. Nonaktifkan kebijakan untuk elemen program.

  • Public. Aktifkan kebijakan untuk jenis publik atau anggota kecuali rantai alat menentukan bahwa anggota tidak perlu dan oleh karena itu menghapusnya. (Dalam kasus terakhir, Anda harus menggunakan Required Public untuk memastikan bahwa anggota disimpan dan memiliki kemampuan refleksi.)

  • PublicAndInternal. Aktifkan kebijakan untuk jenis atau anggota publik dan internal jika rantai alat tidak menghapusnya.

  • Required Public. Wajibkan rantai alat untuk menjaga jenis dan anggota publik apakah mereka digunakan atau tidak, dan mengaktifkan kebijakan untuk mereka.

  • Required PublicAndInternal. Mengharuskan rantai alat untuk menjaga jenis publik dan internal dan anggota apakah mereka digunakan atau tidak, dan mengaktifkan kebijakan untuk mereka.

  • Required All. Wajibkan rantai alat untuk menyimpan semua jenis dan anggota apakah mereka digunakan atau tidak, dan mengaktifkan kebijakan untuk mereka.

Misalnya, file arahan runtime berikut menentukan kebijakan untuk semua jenis dan anggota di DataClasses.dll perakitan. Ini memungkinkan refleksi untuk serialisasi semua properti publik, memungkinkan penjelajahan untuk semua jenis dan anggota jenis, memungkinkan aktivasi untuk semua jenis (karena Dynamic atribut), dan memungkinkan refleksi untuk semua jenis publik dan anggota.

<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
   <Application>
      <Assembly Name="DataClasses" Serialize="Required Public"
                Browse="All" Activate="PublicAndInternal"
                Dynamic="Public"  />
   </Application>
   <Library Name="UtilityLibrary">
     <!-- Child elements go here -->
   </Library>
</Directives>

Menentukan kebijakan untuk anggota

Elemen Properti dan Bidang mendukung jenis kebijakan berikut:

  • Browse - Mengontrol kueri untuk informasi tentang anggota ini tetapi tidak mengaktifkan akses runtime apa pun.

  • Dynamic - Mengontrol akses runtime ke semua anggota jenis, termasuk konstruktor, metode, bidang, properti, dan peristiwa, untuk mengaktifkan pemrograman dinamis. Juga mengontrol kueri untuk informasi tentang jenis yang berisi.

  • Serialize - Mengontrol akses runtime ke anggota untuk memungkinkan instans jenis diserialisasikan dan dideserialisasi oleh pustaka seperti serializer Newtonsoft JSON. Kebijakan ini dapat diterapkan ke konstruktor, bidang, dan properti.

Elemen Metode dan Peristiwa mendukung jenis kebijakan berikut:

  • Browse - Mengontrol kueri untuk informasi tentang anggota ini tetapi tidak mengaktifkan akses runtime apa pun.

  • Dynamic - Mengontrol akses runtime ke semua anggota jenis, termasuk konstruktor, metode, bidang, properti, dan peristiwa, untuk mengaktifkan pemrograman dinamis. Juga mengontrol kueri untuk informasi tentang jenis yang berisi.

Pengaturan yang terkait dengan jenis kebijakan ini adalah:

  • Auto - Gunakan perilaku default. (Tidak menentukan kebijakan setara dengan mengatur kebijakan tersebut kecuali Auto ada sesuatu yang menimpanya.)

  • Excluded - Jangan pernah menyertakan metadata untuk anggota.

  • Included - Aktifkan kebijakan jika jenis induk ada dalam output.

  • Required - Mengharuskan rantai alat untuk menjaga anggota ini bahkan jika tampaknya tidak digunakan, dan mengaktifkan kebijakan untuk itu.

Semantik file arahan runtime

Kebijakan dapat didefinisikan secara bersamaan untuk elemen tingkat yang lebih tinggi dan tingkat bawah. Misalnya, kebijakan dapat didefinisikan untuk perakitan, dan untuk beberapa jenis yang terkandung dalam rakitan tersebut. Jika elemen tingkat bawah tertentu tidak diwakili, elemen tersebut mewarisi kebijakan induknya. Misalnya, jika Assembly elemen ada tetapi Type elemen tidak, kebijakan yang ditentukan dalam Assembly elemen berlaku untuk setiap jenis dalam rakitan. Beberapa elemen juga dapat menerapkan kebijakan ke elemen program yang sama. Misalnya, elemen Assembly terpisah mungkin menentukan elemen kebijakan yang sama untuk rakitan yang sama secara berbeda. Bagian berikut menjelaskan bagaimana kebijakan untuk jenis tertentu diselesaikan dalam kasus tersebut.

Elemen Jenis atau Metode dari jenis atau metode umum menerapkan kebijakannya ke semua instansiasi yang tidak memiliki kebijakannya sendiri. Misalnya, Type elemen yang menentukan kebijakan untuk berlaku untuk List<T> semua instans yang dibangun dari jenis generik tersebut, kecuali jika ditimpa untuk jenis generik tertentu yang dibangun (seperti List<Int32>) oleh TypeInstantiation elemen. Jika tidak, elemen menentukan kebijakan untuk elemen program bernama.

Ketika elemen ambigu, mesin mencari kecocokan, dan jika menemukan kecocokan yang tepat, ia akan menggunakannya. Jika menemukan beberapa kecocokan, akan ada peringatan atau kesalahan.

Jika dua arahan menerapkan kebijakan ke elemen program yang sama

Jika dua elemen dalam file arahan runtime yang berbeda mencoba mengatur jenis kebijakan yang sama untuk elemen program yang sama (seperti rakitan atau jenis) ke nilai yang berbeda, konflik diselesaikan sebagai berikut:

  1. Excluded Jika elemen ada, elemen tersebut memiliki prioritas.

  2. Required lebih diutamakan daripada bukan Required.

  3. All lebih diutamakan daripada PublicAndInternal, yang lebih diutamakan daripada Public.

  4. Setiap pengaturan eksplisit lebih diutamakan daripada Auto.

Misalnya, jika satu proyek menyertakan dua file arahan runtime berikut, kebijakan serialisasi untuk DataClasses.dll diatur ke dan Required Public All. Dalam hal ini, kebijakan serialisasi akan diselesaikan sebagai Required All.

<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
   <Application>
      <Assembly Name="DataClasses" Serialize="Required Public"/>
   </Application>
   <Library Name="DataClasses">
      <!-- any other elements -->
   </Library>
</Directives>

<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
   <Application>
      <Assembly Name="DataClasses" Serialize="All" />
   </Application>
   <Library Name="DataClasses">
      <!-- any other elements -->
   </Library>
</Directives>

Namun, jika dua arahan dalam satu file arahan runtime mencoba mengatur jenis kebijakan yang sama untuk elemen program yang sama, alat Definisi Skema XML menampilkan pesan kesalahan.

Jika elemen turunan dan induk menerapkan jenis kebijakan yang sama

Elemen turunan mengambil alih elemen induknya, termasuk Excluded pengaturan. Penimpaan adalah alasan utama Anda ingin menentukan Auto.

Dalam contoh berikut, pengaturan kebijakan serialisasi untuk semua yang DataClasses tidak ada di DataClasses.ViewModels dalamnya adalah Required Public, dan semua yang ada di keduanya DataClasses dan DataClasses.ViewModels akan menjadi All.

<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
   <Application>
      <Assembly Name="DataClasses" Serialize="Required Public" >
         <Namespace Name="DataClasses.ViewModels" Serialize="All" />
      </Assembly>
   </Application>
   <Library Name="DataClasses">
      <!-- any other elements -->
   </Library>
</Directives>

Jika terbuka generik dan elemen yang dibuat menerapkan jenis kebijakan yang sama

Dalam contoh berikut, Dictionary<int,int> ditetapkan Browse kebijakan hanya jika mesin memiliki alasan lain untuk memberikan Browse kebijakan (yang jika tidak akan menjadi perilaku default); setiap instansiasi Dictionary<TKey,TValue> lainnya akan memiliki semua anggotanya yang dapat ditelusuri.

<Directives xmlns="http://schemas.microsoft.com/netfx/2013/01/metadata">
   <Application>
      <Assembly Name="DataClasses" Serialize="Required Public" >
         <Namespace Name="DataClasses.ViewModels" Serialize="All" />
      </Assembly>
      <Namespace Name="DataClasses.Generics" />
      <Type Name="Dictionary" Browse="All" />
      <TypeInstantiation Name="Dictionary"
                         Arguments="System.Int32,System.Int32" Browse="Auto" />
   </Application>
   <Library Name="DataClasses">
      <!-- any other elements -->
   </Library>
</Directives>

Bagaimana kebijakan disimpulkan

Setiap jenis kebijakan memiliki sekumpulan aturan berbeda yang menentukan bagaimana keberadaan jenis kebijakan tersebut memengaruhi konstruksi lain.

Efek kebijakan Telusuri

Menerapkan kebijakan ke Browse jenis melibatkan perubahan kebijakan berikut:

  • Jenis dasar jenis ditandai dengan Browse kebijakan.

  • Jika jenisnya adalah generik yang dibuat instans, versi jenis yang tidak terinstansiasi ditandai dengan Browse kebijakan.

  • Jika jenisnya adalah delegasi, Invoke metode pada jenis ditandai dengan Dynamic kebijakan.

  • Setiap antarmuka jenis ditandai dengan Browse kebijakan.

  • Jenis setiap atribut yang diterapkan ke jenis ditandai dengan Browse kebijakan.

  • Jika jenisnya umum, setiap jenis batasan ditandai dengan Browse kebijakan.

  • Jika jenisnya generik, jenis di mana jenis dibuat ditandai dengan Browse kebijakan.

Menerapkan kebijakan ke Browse metode melibatkan perubahan kebijakan berikut:

  • Setiap jenis parameter metode ditandai dengan Browse kebijakan.

  • Jenis pengembalian metode ditandai dengan Browse kebijakan.

  • Jenis metode yang berisi ditandai dengan Browse kebijakan.

  • Jika metode ini adalah metode generik yang dibuat instans, metode generik yang tidak terinstansiasi ditandai dengan Browse kebijakan.

  • Jenis setiap atribut yang diterapkan ke metode ditandai dengan Browse kebijakan.

  • Jika metode umum, setiap jenis batasan ditandai dengan Browse kebijakan.

  • Jika metode umum, jenis di mana metode dibuat ditandai dengan Browse kebijakan.

Menerapkan kebijakan ke Browse bidang melibatkan perubahan kebijakan berikut:

  • Jenis setiap atribut yang diterapkan ke bidang ditandai dengan Browse kebijakan.

  • Jenis bidang ditandai dengan Browse kebijakan.

  • Jenis tempat bidang berada ditandai dengan Browse kebijakan.

Efek kebijakan Dinamis

Menerapkan kebijakan ke Dynamic jenis melibatkan perubahan kebijakan berikut:

  • Jenis dasar jenis ditandai dengan Dynamic kebijakan.

  • Jika jenisnya adalah generik yang dibuat instans, versi jenis yang tidak terinstansiasi ditandai dengan Dynamic kebijakan.

  • Jika jenisnya adalah jenis delegasi, Invoke metode pada jenis ditandai dengan Dynamic kebijakan.

  • Setiap antarmuka jenis ditandai dengan Browse kebijakan.

  • Jenis setiap atribut yang diterapkan ke jenis ditandai dengan Browse kebijakan.

  • Jika jenisnya umum, setiap jenis batasan ditandai dengan Browse kebijakan.

  • Jika jenisnya generik, jenis di mana jenis dibuat ditandai dengan Browse kebijakan.

Menerapkan kebijakan ke Dynamic metode melibatkan perubahan kebijakan berikut:

  • Setiap jenis parameter metode ditandai dengan Browse kebijakan.

  • Jenis pengembalian metode ditandai dengan Dynamic kebijakan.

  • Jenis metode yang berisi ditandai dengan Dynamic kebijakan.

  • Jika metode ini adalah metode generik yang dibuat instans, metode generik yang tidak terinstansiasi ditandai dengan Browse kebijakan.

  • Jenis setiap atribut yang diterapkan ke metode ditandai dengan Browse kebijakan.

  • Jika metode umum, setiap jenis batasan ditandai dengan Browse kebijakan.

  • Jika metode umum, jenis di mana metode dibuat ditandai dengan Browse kebijakan.

  • Metode ini dapat dipanggil oleh MethodInfo.Invoke, dan mendelegasikan pembuatan menjadi mungkin oleh MethodInfo.CreateDelegate.

Menerapkan kebijakan ke Dynamic bidang melibatkan perubahan kebijakan berikut:

  • Jenis setiap atribut yang diterapkan ke bidang ditandai dengan Browse kebijakan.

  • Jenis bidang ditandai dengan Dynamic kebijakan.

  • Jenis tempat bidang berada ditandai dengan Dynamic kebijakan.

Efek kebijakan Aktivasi

Menerapkan kebijakan Aktivasi ke jenis melibatkan perubahan kebijakan berikut:

  • Jika jenisnya adalah generik yang dibuat instans, versi jenis yang tidak terinstansiasi ditandai dengan Browse kebijakan.

  • Jika jenisnya adalah jenis delegasi, Invoke metode pada jenis ditandai dengan Dynamic kebijakan.

  • Konstruktor jenis ditandai dengan Activation kebijakan.

Menerapkan kebijakan ke Activation metode melibatkan perubahan kebijakan berikut:

Menerapkan kebijakan ke Activation bidang tidak berpengaruh.

Efek kebijakan Serialisasi

Kebijakan ini Serialize memungkinkan penggunaan serializer berbasis refleksi umum. Namun, karena pola akses refleksi yang tepat dari serializer non-Microsoft tidak diketahui oleh Microsoft, kebijakan ini mungkin tidak sepenuhnya efektif.

Menerapkan kebijakan ke Serialize jenis melibatkan perubahan kebijakan berikut:

  • Jenis dasar jenis ditandai dengan Serialize kebijakan.

  • Jika jenisnya adalah generik yang dibuat instans, versi jenis yang tidak terinstansiasi ditandai dengan Browse kebijakan.

  • Jika jenisnya adalah jenis delegasi, Invoke metode pada jenis ditandai dengan Dynamic kebijakan.

  • Jika jenisnya adalah enumerasi, array jenis ditandai dengan Serialize kebijakan.

  • Jika jenis mengimplementasikan IEnumerable<T>, T ditandai dengan Serialize kebijakan.

  • Jika jenisnya adalah IEnumerable<T>, , ICollection<T>IList<T>, IReadOnlyCollection<T>, atau IReadOnlyList<T>, lalu T[] ditandai List<T> dengan Serialize kebijakan, tetapi tidak ada anggota jenis antarmuka yang ditandai dengan Serialize kebijakan.

  • Jika jenisnya adalah List<T>, tidak ada anggota jenis yang ditandai dengan Serialize kebijakan.

  • Jika jenisnya adalah IDictionary<TKey,TValue>, Dictionary<TKey,TValue> ditandai dengan Serialize kebijakan. tetapi tidak ada anggota jenis yang ditandai dengan Serialize kebijakan.

  • Jika jenisnya adalah Dictionary<TKey,TValue>, tidak ada anggota jenis yang ditandai dengan Serialize kebijakan.

  • Jika jenis mengimplementasikan IDictionary<TKey,TValue>, TKey dan TValue ditandai dengan Serialize kebijakan.

  • Setiap konstruktor, setiap aksesor properti, dan setiap bidang ditandai dengan Serialize kebijakan.

Menerapkan kebijakan ke Serialize metode melibatkan perubahan kebijakan berikut:

  • Jenis yang berisi ditandai dengan Serialize kebijakan.

  • Jenis pengembalian metode ditandai dengan Serialize kebijakan.

Menerapkan kebijakan ke Serialize bidang melibatkan perubahan kebijakan berikut:

  • Jenis yang berisi ditandai dengan Serialize kebijakan.

  • Jenis bidang ditandai dengan Serialize kebijakan.

Efek kebijakan XmlSerializer, DataContractSerializer, dan DataContractJsonSerializer

Serialize Tidak seperti kebijakan, yang ditujukan untuk serializer berbasis refleksi, XmlSerializerkebijakan , DataContractSerializer, dan DataContractJsonSerializer digunakan untuk mengaktifkan sekumpulan serializer yang diketahui oleh rantai alat .NET Native. Serializer ini tidak diimplementasikan dengan menggunakan pantulan, tetapi kumpulan jenis yang dapat diserialisasikan pada waktu proses ditentukan dengan cara yang sama seperti jenis yang dapat direfleksikan.

Menerapkan salah satu kebijakan ini ke jenis memungkinkan jenis diserialisasikan dengan serializer yang cocok. Selain itu, semua jenis yang dapat ditentukan oleh mesin serialisasi secara statis karena membutuhkan serialisasi juga akan dapat diserialisasikan.

Kebijakan ini tidak berpengaruh pada metode atau bidang.

Untuk informasi selengkapnya, lihat bagian "Perbedaan dalam Serializer" di Memigrasikan Aplikasi Windows Store Anda ke .NET Native.

Lihat juga