Share via

Справочник по файлу конфигурации директив среды выполнения (rd.xml)

  • Статья

Файл директив среды выполнения (. rd.xml) — это файл конфигурации XML, который определяет, доступны ли элементы в указанной программе для отражения. Сведения о том, как и где добавлять директивы среды выполнения в проект и как его распознать, см. в статье Средство устранения неполадок MissingMetadataException.

Ниже приведен пример файла директив среды выполнения:

<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>

Структура файла директив среды выполнения

Файл директив среды выполнения использует пространство имен http://schemas.microsoft.com/netfx/2013/01/metadata.

Корневой элемент — элемент Directives. Он может содержать ноль или больше элементов Library и ноль или один элемент Application, как показано в следующей структуре. Атрибуты элемента Application могут определять политику отражения среды выполнения для приложения или служить контейнером для дочерних элементов. Элемент Library, с другой стороны, это просто контейнер. Дочерние элементы элементов Application и Library определяют типы, методы, поля, свойства и события, доступные для отражения.

Для получения справочной информации выберите элементы из приведенной ниже структуры или см. раздел Элементы директив среды выполнения. В следующей иерархии многоточие отмечает рекурсивную структуру. Информация в скобках указывает, является этот элемент необязательным или обязательным, и если он используется, сколько экземпляров (один или несколько) разрешено.

Элемент Application может не иметь атрибутов или иметь атрибуты политики, рассмотренные в разделе Директивы и политика среды выполнения.

Элемент Library имеет один атрибут Name, который определяет имя библиотеки или сборки без расширения файла. Например, следующий элемент Library применяется к сборке с именем 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>

Директивы и политики среды выполнения

Сам элемент Application, а также дочерние элементы элементов Library и Application определяют политику, то есть способ, с помощью которого приложение может применять отражение к программному элементу. Тип политики определяется с помощью атрибута элемента (например, Serialize). Значение политики определяется значением атрибута (например, Serialize="Required").

Любая политика, заданная атрибутом элемента, применяется ко всем дочерним элементам, которые не указывают значение для этой политики. Например, если политика определяется элементом Type, эта политика применяется для всех вложенных типов и членов, для которых политика не указана явно.

Политика, которая может быть определена элементами Application, Assembly, AttributeImplies, Namespace, Subtypes и Type, отличается от политики, которая может быть определена для отдельных членов (элементами Method, Property, Field и Event).

Задание политики для сборок, пространств имен и типов

Элементы Application, Assembly, AttributeImplies, Namespace, Subtypes и Type поддерживают следующие типы политик:

  • Activate. Управляет доступом среды выполнения к конструкторам для включения активации экземпляров.

  • Browse. Управляет запросами для получения сведений об элементах программы, но не включает доступ среды выполнения.

  • Dynamic. Управляет доступом среды выполнения ко всем членам типа, включая конструкторы, методы, поля, свойства и события, чтобы включить динамическое программирование.

  • Serialize. Управляет доступом среды выполнения к конструкторам, полям и свойствам, позволяющим сериализовать и десериализовать экземпляры типа с помощью таких библиотек сторонних поставщиков, как сериализатор Newtonsoft JSON.

  • DataContractSerializer. Определяет политику для сериализации, в которой используется класс System.Runtime.Serialization.DataContractSerializer.

  • DataContractJsonSerializer. Определяет политику для сериализации JSON, в которой используется класс System.Runtime.Serialization.DataContractSerializer.

  • XmlSerializer. Определяет политику для сериализации XML, в которой используется класс System.Xml.Serialization.XmlSerializer.

  • MarshalObject. Определяет политику для маршалинга ссылочных типов в WinRT и COM.

  • MarshalDelegate. Определяет политики для маршалинга типов делегатов как указателей функции на машинный код.

  • MarshalStructure . Определяет политику для маршалинга структуры в машинный код.

Параметры, связанные с этими типами политики:

  • All. Включить политику для всех типов и членов, которые не удаляет цепочка инструментов.

  • Auto. Использовать поведение по умолчанию. (Отсутствие назначения политики эквивалентно установке политики Auto, если только эта политика не переопределяется, например, родительским элементом.)

  • Excluded. Выключить политику для программного элемента.

  • Public. Включить политику для открытых типов и членов, если только цепочка средство не определяет, что элемент является необязательным и поэтому удаляет его. (В последнем случае необходимо использовать Required Public чтобы обеспечить сохранение элемента с возможностями отражения.)

  • PublicAndInternal. Включить политику для открытых и внутренних типов и членов, если цепочка инструментов не удаляет их.

  • Required Public. Требует, чтобы цепочка инструментов поддерживала открытые типы и члены, независимо то того, используются они или нет, и включала для них политику.

  • Required PublicAndInternal. Требует, чтобы цепочка инструментов поддерживала открытые и закрытые типы и члены, независимо то того, используются они или нет, и включала для них политику.

  • Required All. Требует, чтобы цепочка инструментов поддерживала все типы и члены, независимо то того, используются они или нет, и включала для них политику.

Например, следующий файл директив среды выполнения определяет политику для всех типов и членов в сборке DataClasses.dll. Он включает отражение для сериализации все открытых свойств, обзор для всех типов и членов типа, активацию для всех типов (из-за атрибута Dynamic атрибут), а также отражение для всех открытых типов и членов.

<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>

Задание политики для членов

Элементы Property и Field поддерживают следующие типы политик:

  • Browse — Управляет запросами для получения сведений о члене, но не включает доступ среды выполнения.

  • Dynamic — Управляет доступом среды выполнения ко всем членам типа, включая конструкторы, методы, поля, свойства и события, чтобы включить динамическое программирование. Также управляет запросами сведений о содержащем типе.

  • Serialize — Управляет доступом среды выполнения к членам, позволяющим сериализовать и десериализовать экземпляры типа с помощью таких библиотек, как, например, сериализатор Newtonsoft JSON. Эта политика может применяться для конструкторов, полей и свойств.

Элементы Method и Event поддерживают следующие типы политик:

  • Browse — управляет запросами сведений об этом элементе, но не включает доступ к среде выполнения.

  • Dynamic — Управляет доступом среды выполнения ко всем членам типа, включая конструкторы, методы, поля, свойства и события, чтобы включить динамическое программирование. Также управляет запросами сведений о содержащем типе.

Параметры, связанные с этими типами политики:

  • Auto — Использовать поведение по умолчанию. (Отсутствие назначения политики эквивалентно установке политики Auto, если только что-то ее не переопределяет.)

  • Excluded — никогда не включать метаданные для члена.

  • Included- включить политику, если родительский тип присутствует в выходных данных.

  • Required — Требует, чтобы цепочка инструментов поддерживала этот член, даже если он не используется, и включала для него политику.

Семантика файла директив среды выполнения

Политики могут быть определены одновременно для элементов более высокого уровня и более низкого уровня. Например, можно определить политики для сборки, а также для некоторых типов, содержащегося в этой сборке. Если конкретный элемент нижнего уровня не представлен, он наследует политику родительского элемента. Например, если элемент Assembly присутствует, а элементы Type нет, то политика, указанная в элементе Assembly, применяется для каждого типа в сборке. Несколько элементов могут также применить политику к одному и тому же программному элементу. Например, отдельные элементы Assembly могут определять один и тот же элемент политики для одной сборки по-разному. В следующих разделах объясняется, как политики для конкретного типа разрешается в таких случаях.

Элемент Type или Method универсального типа или метода применяет свою политику для всех экземпляров, которые не имеют собственной политики. Например, элемент Type, который определяет политику для List<T>, применяется для всех сконструированных экземпляров универсального типа, если только он переопределяется для определенного сконструированного универсального типа (например, List<Int32>) элементом TypeInstantiation . В противном случае, элементы определяют политику для именованного программного элемента.

Если элемент является неоднозначным, ядро ищет совпадения и при обнаружении точного совпадения, будет ее использовать. При обнаружении нескольких совпадений будет предупреждение или ошибка.

Если две директивы применяют политику к одному и тому же программному элементу

Если два элемента в разных файлах директив среды выполнения пытаются установить один и тот же тип политики для одного программного элемента (например, сборки или типа) в разные значения, конфликт разрешается следующим образом:

  1. Если элемент Excluded присутствует, он имеет приоритет.

  2. Requiredимеет приоритет над не Required.

  3. Allимеет приоритет перед PublicAndInternal, который имеет приоритет над Public.

  4. Любой явный параметр имеет приоритет над Auto.

Например, если один проект включает следующие два файла директив среды выполнения, устанавливается политика сериализации для DataClasses.dll на Required Public и All. В этом случае политика сериализации будет разрешаться как 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>

Однако, если две директивы в файле директив среды выполнения пытаются задать один и тот же тип политики одному программному элементу, то инструмент определения схемы XML отображает сообщение об ошибке.

Если один и тот же тип политики применяется дочерними и родительскими элементами

Дочерние элементы переопределяют свои родительские элементы, в том числе параметр Excluded. Переопределение — основная причина, по которой требуется указать Auto.

В следующем примере параметр политики сериализации для всего, DataClasses что не находится в DataClasses.ViewModels , будет иметь значение Required Public, а все, что находится в и DataClassesDataClasses.ViewModels , будет иметь значение 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>

Если открытые универсальные типы и элементы экземпляра применяют один и тот же тип политики

В следующем примере Dictionary<int,int> назначается как политика Browse, только если ядро имеет еще одну причину присвоить политику Browse (что было бы в противном случае поведением по умолчанию); В каждом экземпляре Dictionary<TKey,TValue> все члены будут доступны для просмотра.

<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>

Как определяется политика

Каждый тип политики имеет разный набор правил, определяющих, как присутствие этого типа политики влияет на другие конструкции.

Эффект политики Browse (Просмотр)

Применение политики Browse для типа включает в себя следующие изменения политики:

  • Базовый тип типа помечается политикой Browse.

  • Если экземпляр универсального типа, версия типа без создания экземпляра помечается политикой Browse.

  • Если тип является делегатом, метод Invoke типа помечается политикой Dynamic.

  • Каждый интерфейс типа помечается политикой Browse.

  • Тип каждого атрибута примененного к типу помечается политикой Browse.

  • Если тип является универсальным, каждое ограничение типа помечается политикой Browse.

  • Если тип универсален, типы, по которым создается экземпляр типа, помечаются политикой Browse.

Применение политики Browse для метода включает в себя следующие изменения политики:

  • Каждый тип параметра метода помечается политикой Browse.

  • Возвращаемый тип метода помечается политикой Browse.

  • Содержащий тип метода помечается политикой Browse.

  • Если метод является экземпляром универсального метода, универсальный метод без экземпляра помечается политикой Browse.

  • Тип каждого атрибута, примененного к методу, помечается политикой Browse.

  • Если метод является универсальным, каждое ограничение типа помечается политикой Browse.

  • Если метод универсален, типы, по которым создается экземпляр метода, помечаются политикой Browse.

Применение политики Browse для поля включает в себя следующие изменения политики:

  • Тип каждого атрибута, примененного к полю, помечается политикой Browse.

  • Тип поля помечается политикой Browse.

  • Тип, к которому принадлежит поле помечается политикой Browse.

Эффект политики Dynamic (Динамическая)

Применение политики Dynamic для типа включает в себя следующие изменения политики:

  • Базовый тип типа помечается политикой Dynamic.

  • Если экземпляр универсального типа, версия типа без создания экземпляра помечается политикой Dynamic.

  • Если тип является делегатом, метод Invoke типа помечается политикой Dynamic.

  • Каждый интерфейс типа помечается политикой Browse.

  • Тип каждого атрибута примененного к типу помечается политикой Browse.

  • Если тип является универсальным, каждое ограничение типа помечается политикой Browse.

  • Если тип универсален, типы, по которым создается экземпляр типа, помечаются политикой Browse.

Применение политики Dynamic для метода включает в себя следующие изменения политики:

  • Каждый тип параметра метода помечается политикой Browse.

  • Возвращаемый тип метода помечается политикой Dynamic.

  • Содержащий тип метода помечается политикой Dynamic.

  • Если метод является экземпляром универсального метода, универсальный метод без экземпляра помечается политикой Browse.

  • Тип каждого атрибута, примененного к методу, помечается политикой Browse.

  • Если метод является универсальным, каждое ограничение типа помечается политикой Browse.

  • Если метод универсален, типы, по которым создается экземпляр метода, помечаются политикой Browse.

  • Этот метод может вызываться MethodInfo.Invoke, а создание делегата становится возможным с помощью MethodInfo.CreateDelegate.

Применение политики Dynamic для поля включает в себя следующие изменения политики:

  • Тип каждого атрибута, примененного к полю, помечается политикой Browse.

  • Тип поля помечается политикой Dynamic.

  • Тип, к которому принадлежит поле помечается политикой Dynamic.

Эффект от политики Activation (активация)

Применение политики Activation для типа включает в себя следующие изменения политики:

  • Если экземпляр универсального типа, версия типа без создания экземпляра помечается политикой Browse.

  • Если тип является делегатом, метод Invoke типа помечается политикой Dynamic.

  • Конструкторы типа помечаются политикой Activation.

Применение политики Activation для метода включает в себя следующие изменения политики:

  • Конструктор может вызываться методами ConstructorInfo.Invoke и Activator.CreateInstance. Для методов политика Activation оказывает действие только на конструкторы.

Применение политики Activation к полю не оказывает влияния.

Эффект политики Serialize (сериализация)

Политика Serialize позволяет использовать общие сериализаторы, основанные на отражении. Тем не менее, поскольку точные шаблоны доступа к отражению сериализаторов сторонних разработчиков неизвестны Microsoft, эта политика может оказаться не совсем эффективной.

Применение политики Serialize для типа включает в себя следующие изменения политики:

  • Базовый тип типа помечается политикой Serialize.

  • Если экземпляр универсального типа, версия типа без создания экземпляра помечается политикой Browse.

  • Если тип является делегатом, метод Invoke типа помечается политикой Dynamic.

  • Если тип является перечислением, массив типа помечается политикой Serialize.

  • Если тип реализует IEnumerable<T>, T помечается политикой Serialize.

  • Если тип является типом IEnumerable<T>, IList<T>, ICollection<T>, IReadOnlyCollection<T> или IReadOnlyList<T>, тогда T[] и List<T> помечаются политикой Serialize, однако ни один из членов типа интерфейса не помечаются политикой Serialize.

  • Если тип является типом List<T>, то его члены не помечаются политикой Serialize.

  • Если тип является типом IDictionary<TKey,TValue>, Dictionary<TKey,TValue> помечается политикой Serialize. Но члены типа не помечаются политикой Serialize.

  • Если тип является типом Dictionary<TKey,TValue>, то его члены не помечаются политикой Serialize.

  • Если тип реализует IDictionary<TKey,TValue>, TKey и TValue помечаются политикой Serialize.

  • Каждый конструктор, каждый метод доступа к свойству и каждое поле помечается политикой Serialize.

Применение политики Serialize для метода включает в себя следующие изменения политики:

  • Содержащий тип помечается политикой Serialize.

  • Возвращаемый тип метода помечается политикой Serialize.

Применение политики Serialize для поля включает в себя следующие изменения политики:

  • Содержащий тип помечается политикой Serialize.

  • Тип поля помечается политикой Serialize.

Влияние политик XmlSerializer, DataContractSerializer и DataContractJsonSerializer

Serialize В отличие от политики, предназначенной для сериализаторов на основе отражения, XmlSerializerполитики , DataContractSerializerи DataContractJsonSerializer используются для включения набора сериализаторов, известных .NET Native цепочке инструментов. Эти сериализаторы не реализуются с помощью отражения, но наборы типов, которые могут быть сериализованы во время выполнения определяются так же, как типы, которые могут отражаться.

Применение одной из этих политик для типа позволяет сериализовать тип с помощью соответствующего сериализатора. Все типы, которые обработчик сериализации может статически определить, как нуждающиеся в сериализации, будут также сериализуемыми.

Эти политики не оказывают влияния на методы или поля.

Подробнее см. в подразделе "Различия в сериализаторах" раздела Миграция приложения для Магазина Windows в .NET Native.

См. также раздел