Относящиеся к XAML атрибуты среды CLR для пользовательских типов и библиотек

В этом разделе описываются атрибуты среды CLR, определяемые службами XAML платформы .NET Framework. Также рассматриваются другие определенные в .NET Framework атрибуты среды CLR, которым присущи связанные с XAML сценарии применения к сборкам и типам. Присвоение этих атрибутов среды CLR сборкам, типам или членам предоставляет информацию о системе типов XAML, связанную с пользовательскими типами. Информация предоставляется всем объектам-получателям XAML, использующим службы XAML платформы .NET Framework для обработки потока узлов XAML напрямую или через выделенные средства чтения и записи XAML.

Относящиеся к XAML атрибуты среды CLR для пользовательских типов и пользовательских членов

Использование атрибутов CLR подразумевает использование среды CLR в целом для определения типов, иначе такие атрибуты будут недоступны. При использовании среды CLR для определения резервирования типов контекст схемы XAML по умолчанию, используемый средствами записи XAML служб XAML платформы .NET Framework, может считывать атрибуты среды CLR через отражение в резервных сборках.

В следующих разделах описываются атрибуты, связанные с XAML, которые можно применять к пользовательским типам и пользовательским членам. Каждый атрибут среды CLR передает информацию, относящуюся к системе типов XAML. В пути загрузки информация атрибутов либо помогает средству чтения XAML сформировать допустимый поток узлов XAML, либо помогает средству записи XAML произвести допустимый граф объектов. В пути сохранения информация атрибутов либо помогает средству чтения XAML сформировать допустимый поток узлов XAML, который воссоздает информацию системы типов XAML, либо объявляет подсказки или требования относительно сериализации средству записи XAML и другим объектам-получателям XAML.

Атрибут AmbientAttribute

Справочная документация: AmbientAttribute.

Применяется к: классу, свойству или методам доступа get, поддерживающим присоединяемые свойства.

Аргументы: отсутствуют.

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

Понятие внешнего элемента может применяться к присоединяемым членам, которые не представлены в виде свойств в том смысле, как присвоение атрибутов CLR определяет AttributeTargets. Использование присвоения атрибутов методов должно применяться только в случае поддержки методом доступа get использования присоединения в XAML.

Атрибут ConstructorArgumentAttribute

Справочная документация: ConstructorArgumentAttribute.

Применяется к: классу.

Аргументы: строка, указывающая имя свойства, соответствующее единичному аргументу конструктора.

ConstructorArgumentAttribute указывает, что объект может быть инициализирован с помощью синтаксиса конструктора, не являющегося используемым по умолчанию, и что свойство указанного имени предоставляет информацию о конструкции. Эти сведения предназначены, главным образом, для сериализации XAML. Дополнительные сведения см. в разделе ConstructorArgumentAttribute.

Атрибут ContentPropertyAttribute

Справочная документация: ContentPropertyAttribute.

Применяется к: классу.

Аргументы: строка, указывающая имя члена помеченного атрибутом типа.

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

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

В потоке узлов XAML свойства содержимого XAML продолжают производить узлы StartMember и EndMember, используя имя этого свойства для XamlMember. Чтобы определить, является ли член свойством содержимого XAML, необходимо рассмотреть значение XamlType из позиции StartObject и получить значение свойства ContentProperty.

Атрибут ContentWrapperAttribute

Справочная документация: ContentWrapperAttribute.

Применяется к: классу, в особенности к типам коллекций.

Аргументы: какой-либо Type, указывающий, какой тип необходимо использовать в качестве типа оболочки содержимого для внешнего содержимого.

ContentWrapperAttribute указывает один или несколько типов в соответствующем типе коллекции, которые будут использоваться как оболочка для внешнего содержимого. Под внешним содержимым понимаются случаи, когда ограничения системы типов по типу свойств содержимого не включают все возможные варианты содержимого, которые будут поддерживаться при использовании XAML для типа-владельца. Например, поддержка XAML для содержимого какого-либо конкретного типа может включать строки в строго типизированной универсальной коллекции Collection<T>. Оболочки содержимого удобны при переносе ранее существовавших стандартов разметки в концепцию присваиваемых значений для коллекций языка XAML, например при переносе моделей содержимого, связанных с текстом.

Для задания нескольких типов оболочки содержимого примените атрибут несколько раз.

Атрибут DependsOnAttribute

Справочная документация: DependsOnAttribute.

Применяется к: свойству.

Аргументы: строка, указывающая имя другого члена помеченного атрибутом типа.

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

К определению свойства можно применить несколько вариантов атрибута DependsOnAttribute.

Атрибут MarkupExtensionReturnTypeAttribute

Справочная документация: MarkupExtensionReturnTypeAttribute.

Применяется к: классу, который, предположительно, будет производным типом MarkupExtension.

Аргументы: тип Type, указывающий наиболее точный тип, который следует ожидать в качестве результата метода ProvideValue объекта MarkupExtension, помеченного этим атрибутом.

Дополнительные сведения см. в разделе Общие сведения о расширениях разметки для XAML.

Атрибут NameScopePropertyAttribute

Справочная документация: NameScopePropertyAttribute.

Применяется к: классу.

Аргументы: поддерживает два способа присвоения атрибутов.

• Строка с указанием имени свойства типа с атрибутом.

• Строка с указанием имени свойства и типа Type для типа, определяющего названное этим именем свойство. Данный способ применяется для указания присоединяемого члена в качестве свойства области видимости имен XAML.

NameScopePropertyAttribute указывает свойство, которое предоставляет значение области видимости имен XAML для класса с этим атрибутом. Свойство области видимости имен XAML должно указывать на объект, реализующий класс INameScope и содержит фактическую область видимости имен XAML, ее хранилище и ее поведение.

Атрибут RuntimeNamePropertyAttribute

Справочная документация: RuntimeNamePropertyAttribute.

Применяется к: классу.

Аргументы: строка, указывающая имя свойства имени среды выполнения в помеченном атрибутом типе.

RuntimeNamePropertyAttribute сообщает свойство помеченного атрибутом типа, которое сопоставляется XAML-директиве Директива x:Name. Это свойство должно относиться к типу String и должно быть доступно для чтения и записи.

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

Атрибут TrimSurroundingWhitespaceAttribute

Справочная документация: TrimSurroundingWhitespaceAttribute.

Применяется к: типам.

Аргументы: отсутствуют.

TrimSurroundingWhitespaceAttribute применяется к определенным типам, которые могут отображаться как дочерние элементы в пределах содержимого со значимыми пробелами (содержимого, хранящегося в коллекции с атрибутом WhitespaceSignificantCollectionAttribute). TrimSurroundingWhitespaceAttribute в основном относится к пути сохранения, но также доступен в системе типов XAML в пути загрузки путем проверки свойства XamlType.TrimSurroundingWhitespace. Дополнительные сведения см. в разделе Обработка пробелов в XAML.

Атрибут TypeConverterAttribute

Справочная документация: TypeConverterAttribute.

Применяется к: классу, свойству, методу (единственным допустимым в языке XAML вариантом метода является метод доступа get, поддерживающий присоединяемый член).

Аргументы: тип Type преобразователя TypeConverter.

TypeConverterAttribute в контексте XAML указывает на пользовательский преобразователь TypeConverter. Этот преобразователь TypeConverter предоставляет поведение преобразования для пользовательских типов и членов таких типов.

Атрибут TypeConverterAttribute применяется к пользовательскому типу с указанием реализации преобразователя пользовательского типа. Можно определить преобразователи типов для языка XAML по классам, структурам и интерфейсам. Нет необходимости предоставлять преобразование типов для перечислений, такое преобразование выполняется встроенными средствами.

Пользовательский преобразователь типов должен иметь способность к преобразованию из строки, используемой для текста инициализации или атрибутов в разметке, в желаемый конечный тип. Дополнительные сведения см. в разделе TypeConverters и XAML.

Вместо применения ко всем значениям определенного типа поведение преобразователя типов для языка XAML также можно установить по отдельному свойству. В таком случае примените атрибут TypeConverterAttribute к определению свойства (внешнему определению, а не к конкретным определениям get и set).

Поведение преобразователя типов для использования в языке XAML пользовательского присоединяемого члена можно задать, применив атрибут TypeConverterAttribute к методу доступа get, поддерживающему использование языка XAML.

Как и TypeConverter, атрибут TypeConverterAttribute был представлен в платформе .NET Framework до появления языка XAML, а модель преобразователя типов выполняла другие функции. Для указания и использования атрибута TypeConverterAttribute необходимо полностью уточнить его или предоставить оператор using для модели System.ComponentModel. Также в проект необходимо включить сборку System.

Атрибут UidPropertyAttribute

Справочная документация: UidPropertyAttribute.

Применяется к: классу.

Аргументы: строка с указанием имени соответствующего свойства.

Указывает свойство класса в среде CLR, который присваивает псевдоним директиве Директива x:Uid.

Атрибут UsableDuringInitializationAttribute

Справочная документация: UsableDuringInitializationAttribute.

Применяется к: классу.

Аргументы: логическое значение. При использовании по предназначению атрибута аргумент всегда должен иметь значение true.

Показывает, строится ли данный тип сверху вниз в ходе создания графа объекта XAML. Это более сложное понятие, которое может быть тесно связано с определением пользовательской модели программирования. Дополнительные сведения см. в разделе UsableDuringInitializationAttribute.

Атрибут ValueSerializerAttribute

Справочная документация: ValueSerializerAttribute.

Применяется к: классу, свойству, методу (единственным допустимым в языке XAML вариантом метода является метод доступа get, поддерживающий присоединяемый член).

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

ValueSerializer указывает класс сериализации значений, требующий больше состояний и контекстов, чем преобразователь TypeConverter. ValueSerializer может быть связан с присоединяемым членом путем применения атрибута ValueSerializerAttribute к статическому методу доступа get для присоединяемого члена. Сериализация значений также может применяться к перечислениям, интерфейсам и структурам, но не к делегатам.

Атрибут WhitespaceSignificantCollectionAttribute

Справочная документация: WhitespaceSignificantCollectionAttribute.

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

Аргументы: отсутствуют.

WhitespaceSignificantCollectionAttribute указывает, что обработчик XAML должен обрабатывать тип коллекции с учетом значимости пробелов, что влияет на создание узлов значений потока узлов XAML в пределах коллекции. Дополнительные сведения см. в разделе Обработка пробелов в XAML.

Атрибут XamlDeferLoadAttribute

Справочная документация: XamlDeferLoadAttribute.

Применяется к: классу, свойству.

Аргументы: поддерживает две формы присвоения атрибута: типы как строки или типы как объекты Type. См. раздел XamlDeferLoadAttribute.

Указывает, что классу или свойству соответствует использование отложенной загрузки для XAML (в частности, поведение шаблона), и сообщает о классе, включающем задержку, и о его типе назначения/содержимого.

Атрибут XamlSetMarkupExtensionAttribute

Справочная документация: XamlSetMarkupExtensionAttribute.

Применяется к: классу.

Аргументы: именует обратный вызов.

Указывает, что класс может использовать расширение разметки для предоставления значения одному или нескольким своим свойствам и ссылается на обработчик, который должно вызвать средство записи XAML перед выполнением операции установки расширения разметки над каким-либо свойством этого класса.

Атрибут XamlSetTypeConverterAttribute

Справочная документация: XamlSetTypeConverterAttribute.

Применяется к: классу.

Аргументы: именует обратный вызов.

Указывает, что класс может использовать преобразователь типов для предоставления значения одному или нескольким своим свойствам и ссылается на обработчик, который должно вызвать средство записи XAML перед выполнением операции установки преобразователя типа над каким-либо свойством этого класса.

Атрибут XmlLangPropertyAttribute

Справочная документация: XmlLangPropertyAttribute.

Применяется к: классу.

Аргументы: строка с указанием имени свойства, которое необходимо использовать как псевдоним для xml:lang типа с этим атрибутом.

XmlLangPropertyAttribute сообщает о свойстве типа с этим атрибутом, которое сопоставляется XML-директиве lang. Это свойство не обязательно должно относиться к типу String, но должно быть присваиваемым из строки (этого можно добиться привязкой преобразователя типов к типу свойства или к отдельному свойству). Это свойство должно быть доступным для чтения и записи.

Сценарий сопоставления свойства xml:lang таков, что модель объекта среды выполнения обладает доступом к информации, относящейся к языку XML, без отдельной обработки при помощи XMLDOM.

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

Связанные с XAML атрибуты среды CLR на уровне сборки

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

Атрибут XmlnsCompatibleWithAttribute

Справочная документация: XmlnsCompatibleWithAttribute.

Аргументы:

• строка с указанием идентификатора пространства имен XAML, которое необходимо отнести к какой-либо категории;

• строка с указанием идентификатора пространства имен XAML, которое может включить пространство имен XAML из предыдущего аргумента.

XmlnsCompatibleWithAttribute указывает, что пространство имен XAML может быть включено в другое пространство имен XAML. Обычно поглощающее пространство имен XAML указано в определенном ранее атрибуте XmlnsDefinitionAttribute. Этот метод можно использовать для присвоения номера версии словарю XAML в библиотеке для обеспечения его совместимости с ранее определенной по более старому словарю разметкой.

Атрибут XmlnsDefinitionAttribute

Справочная документация: XmlnsDefinitionAttribute.

Аргументы:

• строка с указанием идентификатора пространства имен XAML, которое необходимо определить;

• строка, называющая пространство имен CLR. Пространство имен среды CLR должно определять открытые типы в сборке, и хотя бы один из типов пространства имен среды CLR должен быть предназначен для употребления в XAML.

XmlnsDefinitionAttribute указывает для каждой сборки сопоставление между пространством имен XAML и пространством имен среды CLR, которое затем используется для разрешения типов средством записи объектов XAML или контекстом схемы XAML.

К сборке можно применять несколько атрибутов XmlnsDefinitionAttribute. Это можно сделать по какой-либо из приведенных ниже причин.

• Архитектура библиотеки содержит несколько пространств имен среды CLR для логической организации доступа к API-интерфейсу среды выполнения, однако требуется обеспечить возможность использования всех типов из этих пространств имен в XAML посредством ссылки на одно и то же пространство имен XAML. В этом случае необходимо применить несколько атрибутов XmlnsDefinitionAttribute, используя одно значение XmlNamespace, но разные значения ClrNamespace. Это особенно полезно при определении сопоставлений для пространства имен XAML, которое в пользовательской платформе или приложении в общем случае будет пространством имен XAML по умолчанию.

• Конструкция библиотеки содержит несколько пространств имен CLR, и необходимо выполнить намеренное разделение пространства имен XAML согласно использованиям типов в этих пространствах имен CLR.

• Пространство имен CLR определяется в сборке, и необходимо обеспечить доступ к нему через несколько пространств имен XAML. Этот сценарий имеет место при поддержке нескольких словарей с одной базой кода.

• Поддержка языка XAML определяется в одном или нескольких пространствах имен CLR. Для этого значение XmlNamespace должно быть таким: https://schemas.microsoft.com/winfx/2006/xaml.

Атрибут XmlnsPrefixAttribute

Справочная документация: XmlnsPrefixAttribute.

Аргументы:

• Строка с указанием идентификатора пространства имен XAML.

• Строка, определяющая рекомендуемый префикс.

XmlnsDefinitionAttribute указывает рекомендуемый для использования в пространстве имен XAML префикс. Такой префикс удобен при записи элементов и атрибутов в XAML-файл, сериализация которого выполняется средством записи XamlXmlWriter служб XAML платформы .NET Framework, или когда реализующая XAML библиотека взаимодействует со средой разработки, снабженной функциями редактирования XAML.

К сборке можно применять несколько атрибутов XmlnsPrefixAttribute. Это можно сделать по какой-либо из приведенных ниже причин.

• Сборка определяет типы для нескольких пространств имен XAML. В таком случае необходимо задать различные значения префиксов для каждого пространства имен XAML.

• Поддерживается несколько словарей, и для каждого словаря и пространства имен XAML используется свой префикс.

• Поддержка языка XAML определяется в сборке, и атрибут XmlnsDefinitionAttribute предназначен для https://schemas.microsoft.com/winfx/2006/xaml. В таком случае обычно необходимо повысить уровень префикса x.

Примечание
Службы XAML платформы .NET Framework также определяют атрибут, связанный с XAML RootNamespaceAttribute.Это атрибут уровня сборки для поддержки системы проектов, и к пользовательским типам XAML он не имеет отношения.

См. также

Ссылки

Attribute

Другие ресурсы

Определение пользовательских типов для использования со службами XAML .NET Framework