Atributos CLR relacionados a XAML para tipos e bibliotecas personalizados

  • Artigo

Este tópico descreve os atributos CLR (Common Language Runtime) definidos pelos Serviços XAML do .NET. Ele também descreve outros atributos CLR que são definidos no .NET que têm um cenário relacionado a XAML para aplicativos para assemblies ou tipos. A atribuição de assemblies, tipos ou membros com esses atributos CLR fornece informações do sistema de tipo XAML relacionadas aos seus tipos. As informações são fornecidas a qualquer consumidor XAML que use os Serviços XAML do .NET para processar o fluxo de nós XAML diretamente ou por meio dos leitores XAML dedicados e gravadores XAML.

O uso de atributos CLR implica que você está usando o CLR geral para definir seus tipos, caso contrário, esses atributos não estarão disponíveis. Se você usar o CLR para definir o backup de tipo, o contexto de esquema XAML padrão usado pelos gravadores XAML dos Serviços XAML do .NET poderá ler a atribuição do CLR por meio da reflexão em relação aos assemblies de suporte.

As seções a seguir descrevem os atributos relacionados a XAML que você pode aplicar a tipos personalizados ou membros personalizados. Cada atributo CLR comunica informações relevantes para um sistema de tipo XAML. No caminho de carregamento, as informações atribuídas ajudam o leitor XAML a formar um fluxo de nó XAML válido ou ajudam o gravador XAML a produzir um gráfico de objeto válido. No caminho de salvamento, as informações atribuídas ajudam o leitor XAML a formar um fluxo de nó XAML válido que reconstitui as informações do sistema do tipo XAML; ou declara dicas ou requisitos de serialização para o gravador XAML ou outros consumidores XAML.

AmbientAttribute

Documentação de referência:AmbientAttribute

Aplica-se a: membros de classe, propriedade ou get acessador que oferecem suporte a propriedades anexáveis.

Argumentos: Nenhum

AmbientAttribute indica que a propriedade, ou todas as propriedades que usam o tipo atribuído, devem ser interpretadas sob o conceito de propriedade ambient em XAML. O conceito de ambiente está relacionado a como os processadores XAML determinam os proprietários do tipo dos membros. Uma propriedade ambient é uma propriedade em que se espera que o valor esteja disponível no contexto do analisador ao criar um gráfico de objeto, mas onde a pesquisa típica de membro de tipo é suspensa para o conjunto de nós XAML imediato que está sendo criado.

O conceito de ambiente pode ser aplicado a membros anexáveis, que não são representados como propriedades em termos de como a atribuição CLR define AttributeTargets. O uso de atribuição de método deve ser aplicado somente a um get acessador que ofereça suporte ao uso anexável para XAML.

ConstructorArgumentAttribute

Documentação de referência:ConstructorArgumentAttribute

Aplica-se a: Classe

Argumentos: uma cadeia de caracteres que especifica o nome da propriedade que corresponde a um único argumento do construtor.

ConstructorArgumentAttribute Especifica que um objeto pode ser inicializado usando uma sintaxe de construtor sem parâmetros e que uma propriedade do nome especificado fornece informações de construção. Essas informações são principalmente para serialização XAML. Para obter mais informações, consulte ConstructorArgumentAttribute.

ContentPropertyAttribute

Documentação de referência:ContentPropertyAttribute

Aplica-se a: Classe

Argumentos: uma cadeia de caracteres que especifica o nome de um membro do tipo atribuído.

ContentPropertyAttribute indica que a propriedade nomeada pelo argumento deve servir como a propriedade de conteúdo XAML para esse tipo. A definição da propriedade de conteúdo XAML herda para todos os tipos derivados que são atribuíveis ao tipo definidor. Você pode substituir a definição em um tipo derivado específico aplicando ContentPropertyAttribute no tipo derivado específico.

Para a propriedade que serve como a propriedade de conteúdo XAML, a marcação do elemento de propriedade para a propriedade pode ser omitida no uso de XAML. Normalmente, você designa propriedades de conteúdo XAML que promovem uma marcação XAML simplificada para seus modelos de conteúdo e contenção. Como apenas um membro pode ser designado como a propriedade de conteúdo XAML, às vezes você tem escolhas de design a fazer em relação a qual das várias propriedades de contêiner de um tipo deve ser designada como a propriedade de conteúdo XAML. As outras propriedades de contêiner devem ser usadas com elementos de propriedade explícitos.

No fluxo de nós XAML, as propriedades de conteúdo XAML ainda produzem StartMember e EndMember nós, usando o nome da propriedade para o XamlMember. Para determinar se um membro é a propriedade de conteúdo XAML, examine o XamlTypeStartObject valor da posição e obtenha o valor de ContentProperty.

ContentWrapperAttribute

Documentação de referência:ContentWrapperAttribute

Aplica-se a: Classe, especificamente tipos de coleção.

Argumentos: Um Type que especifica o tipo a ser usado como o tipo de wrapper de conteúdo para conteúdo externo.

ContentWrapperAttribute Especifica um ou mais tipos no tipo de coleção associado que será usado para encapsular conteúdo externo. Conteúdo externo refere-se a casos em que as restrições do sistema de tipo no tipo da propriedade content não capturam todos os casos de conteúdo possíveis que o uso de XAML para o tipo proprietário suportaria. Por exemplo, o suporte a XAML para conteúdo de um tipo específico pode oferecer suporte a cadeias de caracteres em um genérico Collection<T>fortemente tipado. Os wrappers de conteúdo são úteis para migrar convenções de marcação pré-existentes para a concepção de valores atribuíveis para coleções do XAML, como a migração de modelos de conteúdo relacionados a texto.

Para especificar mais de um tipo de wrapper de conteúdo, aplique o atributo várias vezes.

DependsOnAttribute

Documentação de referência:DependsOnAttribute

Aplica-se a: Propriedade

Argumentos: uma cadeia de caracteres que especifica o nome de outro membro do tipo atribuído.

DependsOnAttribute indica que a propriedade atribuída depende do valor de outra propriedade. A aplicação desse atributo a uma definição de propriedade garante que as propriedades dependentes sejam processadas primeiro na gravação de objetos XAML. Os usos de especificam os casos excepcionais de propriedades em tipos em que uma ordem específica de análise deve ser seguida para a criação de DependsOnAttribute objetos válidos.

Você pode aplicar vários DependsOnAttribute casos a uma definição de propriedade.

MarkupExtensionReturnTypeAttribute

Documentação de referência:MarkupExtensionReturnTypeAttribute

Aplica-se a: Classe, que se espera que seja um MarkupExtension tipo derivado.

Argumentos: A Type que especifica o tipo mais preciso a ser esperado como ProvideValue resultado do .MarkupExtension

Para obter mais informações, consulte Visão geral sobre extensões de marcação para XAML.

NameScopePropertyAttribute

Documentação de referência:NameScopePropertyAttribute

Aplica-se a: Classe

Argumentos: Suporta duas formas de atribuição:

  • Uma cadeia de caracteres que especifica o nome de uma propriedade no tipo atribuído.

  • Uma cadeia de caracteres que especifica o nome de uma propriedade e um Type para o tipo que define a propriedade nomeada. Este formulário serve para especificar um membro anexável como a propriedade namescope XAML.

NameScopePropertyAttribute especifica uma propriedade que fornece o valor namescope XAML para a classe atribuída. Espera-se que a propriedade namescope XAML faça referência a um objeto que implementa INameScope e mantém o namescope XAML real, seu armazenamento e seu comportamento.

RuntimeNamePropertyAttribute

Documentação de referência:RuntimeNamePropertyAttribute

Aplica-se a: Classe

Argumentos: uma cadeia de caracteres que especifica o nome da propriedade de nome em tempo de execução no tipo atribuído.

RuntimeNamePropertyAttributerelata uma propriedade do tipo atribuído que mapeia para a diretiva XAML x:Name. A propriedade deve ser do tipo String e deve ser leitura/gravação.

A definição herda para todos os tipos derivados que são atribuíveis ao tipo definidor. Você pode substituir a definição em um tipo derivado específico aplicando RuntimeNamePropertyAttribute no tipo derivado específico.

TrimSurroundingWhitespaceAttribute

Documentação de referência:TrimSurroundingWhitespaceAttribute

Aplica-se a: Tipos

Argumentos: Nenhum.

TrimSurroundingWhitespaceAttribute é aplicado a tipos específicos que podem aparecer como elementos filho dentro de conteúdo significativo de espaço em branco (conteúdo mantido por uma coleção que tem WhitespaceSignificantCollectionAttribute). TrimSurroundingWhitespaceAttribute é principalmente relevante para o caminho de salvamento, mas está disponível no sistema de tipo XAML no caminho de carregamento examinando XamlType.TrimSurroundingWhitespace. Para obter mais informações, consulte Processamento de espaço em branco em XAML.

TypeConverterAttribute

Documentação de referência:TypeConverterAttribute

Aplica-se a: Classe, propriedade, método (o único caso de método válido para XAML é um acessador que oferece suporte a um get membro anexável).

Argumentos: O Type do TypeConverter.

TypeConverterAttribute em um contexto XAML faz referência a um TypeConverterarquivo . Isso TypeConverter fornece comportamento de conversão de tipo para tipos personalizados ou membros desse tipo.

Aplique o atributo ao seu tipo, fazendo referência à implementação do TypeConverterAttribute conversor de tipos. Você pode definir conversores de tipo para XAML em classes, estruturas ou interfaces. Você não precisa fornecer conversão de tipo para enumerações, essa conversão é habilitada nativamente.

Seu conversor de tipo deve ser capaz de converter de uma cadeia de caracteres usada para atributos ou texto de inicialização na marcação para o tipo de destino pretendido. Para obter mais informações, consulte TypeConverters e XAML.

Em vez de se aplicar a todos os valores de um tipo, um comportamento de conversor de tipo para XAML também pode ser estabelecido em uma propriedade específica. Nesse caso, você se aplica TypeConverterAttribute à definição de propriedade (a definição externa, não as definições e set específicasget).

Um comportamento de conversor de tipo para uso XAML de um membro anexável personalizado pode ser atribuído aplicando TypeConverterAttribute ao acessador de método que dá suporte ao uso de get XAML.

Semelhante ao TypeConverter, existia no .NET antes da existência do XAML, TypeConverterAttribute e o modelo de conversor de tipo atendia a outros propósitos. Para referenciar e usar TypeConverterAttribute, você deve qualificá-lo totalmente ou fornecer uma using declaração para System.ComponentModel. Inclua também a montagem do sistema em seu projeto.

UidPropertyAttribute

Documentação de referência:UidPropertyAttribute

Aplica-se a: Classe

Argumentos: uma cadeia de caracteres que faz referência à propriedade relevante por nome.

Indica a propriedade CLR de uma classe que aliases a diretiva x:Uid.

UsableDuringInitializationAttribute

Documentação de referência:UsableDuringInitializationAttribute

Aplica-se a: Classe

Argumentos: Um booleano. Se usado para a finalidade pretendida do atributo, o valor deve ser definido como true.

Indica se o tipo é criado de cima para baixo durante a criação do gráfico de objeto XAML. Este é um conceito avançado, que provavelmente está intimamente relacionado com a definição do seu modelo de programação. Para obter mais informações, consulte UsableDuringInitializationAttribute.

ValueSerializerAttribute

Documentação de referência:ValueSerializerAttribute

Aplica-se a: Classe, propriedade, método (o único caso de método válido para XAML é um acessador que oferece suporte a um get membro anexável).

Argumentos: A Type que especifica a classe de suporte do serializador de valor a ser usada ao serializar todas as propriedades do tipo atribuído ou a propriedade atribuída específica.

ValueSerializer Especifica uma classe de serialização de valor que requer mais estado e contexto do que um TypeConverter faz. ValueSerializer pode ser associado a um membro anexável aplicando o ValueSerializerAttribute atributo no método de acessador estático get para o membro anexável. A serialização de valor também é aplicável para enumerações, interfaces e estruturas, mas não para representantes.

WhitespaceSignificantCollectionAttribute

Documentação de referência:WhitespaceSignificantCollectionAttribute

Aplica-se a: Classe, especificamente tipos de coleção que devem hospedar conteúdo misto, onde o espaço em branco ao redor de elementos de objeto pode ser significativo para a representação da interface do usuário.

Argumentos: Nenhum.

WhitespaceSignificantCollectionAttribute indica que um tipo de coleção deve ser processado como espaço em branco significativo por um processador XAML, o que influencia a construção dos nós de valor do fluxo de nó XAML dentro da coleção. Para obter mais informações, consulte Processamento de espaço em branco em XAML.

XamlDeferLoadAttribute

Documentação de referência:XamlDeferLoadAttribute

Aplica-se a: Classe, propriedade.

Argumentos: Oferece suporte a dois tipos de formulários de atribuição como cadeias de caracteres ou tipos como Type. Consulte XamlDeferLoadAttribute.

Indica que uma classe ou propriedade possui um uso de carregamento adiado para XAML (como um comportamento de modelo) e relata a classe que habilita o comportamento de adiamento e seu tipo de conteúdo/destino.

XamlSetMarkupExtensionAttribute

Documentação de referência:XamlSetMarkupExtensionAttribute

Aplica-se a: Classe

Argumentos: nomeia o retorno de chamada.

Indica que uma classe pode usar uma extensão de marcação para fornecer um valor para uma ou mais de suas propriedades e faz referência a um manipulador que um gravador XAML deve chamar antes de executar uma operação de conjunto de extensões de marcação em qualquer propriedade da classe.

XamlSetTypeConverterAttribute

Documentação de referência:XamlSetTypeConverterAttribute

Aplica-se a: Classe

Argumentos: nomeia o retorno de chamada.

Indica que uma classe pode usar um conversor de tipo para fornecer um valor para uma ou mais de suas propriedades e faz referência a um manipulador que um gravador XAML deve chamar antes de executar uma operação de conjunto de conversores de tipo em qualquer propriedade da classe.

XmlLangPropertyAttribute

Documentação de referência:XmlLangPropertyAttribute

Aplica-se a: Classe

Argumentos: uma cadeia de caracteres que especifica o nome da propriedade para xml:lang alias no tipo atribuído.

XmlLangPropertyAttribute relata uma propriedade do tipo atribuído que mapeia para a diretiva XML lang . A propriedade não é necessariamente de tipo, mas deve ser atribuível a partir de uma cadeia de caracteres (a atribuição pode ser realizada associando um conversor de tipo ao tipo String da propriedade ou à propriedade específica). A propriedade deve ser leitura/gravação.

O cenário para mapeamento xml:lang é para que um modelo de objeto de tempo de execução tenha acesso a informações de linguagem especificadas por XML sem processar especificamente com um XMLDOM.

A definição herda para todos os tipos derivados que são atribuíveis ao tipo definidor. Você pode substituir a definição em um tipo derivado específico aplicando XmlLangPropertyAttribute no tipo derivado específico, embora esse seja um cenário incomum.

As seções a seguir descrevem os atributos relacionados a XAML que não são aplicados a tipos ou definições de membro, mas são aplicados a assemblies. Esses atributos são pertinentes ao objetivo geral de definir uma biblioteca que contenha tipos personalizados a serem usados em XAML. Alguns dos atributos não necessariamente influenciam o fluxo de nó XAML diretamente, mas são transmitidos no fluxo de nó para outros consumidores usarem. Os consumidores das informações incluem ambientes de design ou processos de serialização que precisam de informações de namespace XAML e informações de prefixo associadas. Um contexto de esquema XAML (incluindo o padrão dos Serviços XAML do .NET) também usa essas informações.

XmlnsCompatibleWithAttribute

Documentação de referência:XmlnsCompatibleWithAttribute

Argumentos:

  • Uma cadeia de caracteres que especifica o identificador do namespace XAML a ser subsumido.

  • Uma cadeia de caracteres que especifica o identificador do namespace XAML que pode subsumir o namespace XAML do argumento anterior.

    XmlnsCompatibleWithAttribute especifica que um namespace XAML pode ser subsumido por outro namespace XAML. Normalmente, o namespace de XAML incluído é indicado em um XmlnsDefinitionAttribute definido anteriormente. Essa técnica pode ser usada para controlar o controle de versão de um vocabulário XAML em uma biblioteca e para torná-lo compatível com a marcação definida anteriormente em relação ao vocabulário versionado anteriormente.

XmlnsDefinitionAttribute

Documentação de referência:XmlnsDefinitionAttribute

Argumentos:

  • Uma cadeia de caracteres que especifica o identificador do namespace XAML a ser definido.

  • Uma cadeia de caracteres que nomeia um namespace CLR. O namespace CLR deve definir tipos públicos em seu assembly, e pelo menos um dos tipos de namespace CLR deve ser destinado ao uso de XAML.

    XmlnsDefinitionAttribute especifica um mapeamento por assembly entre um namespace XAML e um namespace CLR, que é usado para resolução de tipos por um gravador de objeto XAML ou contexto de esquema XAML.

    Mais de um XmlnsDefinitionAttribute pode ser aplicado a uma montagem. Isso pode ser feito por qualquer combinação dos seguintes motivos:

  • O design da biblioteca contém vários namespaces CLR para organização lógica do acesso à API em tempo de execução; no entanto, você deseja que todos os tipos nesses namespaces sejam utilizáveis por XAML fazendo referência ao mesmo namespace XAML. Nesse caso, você aplica vários XmlnsDefinitionAttribute atributos usando o mesmo XmlNamespace valor, mas valores diferentes ClrNamespace . Isso é especialmente útil se você estiver definindo mapeamentos para o namespace XAML que sua estrutura ou aplicativo pretende que seja o namespace XAML padrão em uso comum.

  • O design da biblioteca contém vários namespaces CLR e você deseja uma separação deliberada de namespace XAML entre os usos de tipos nesses namespaces CLR.

  • Você define um namespace CLR no assembly e deseja que ele seja acessível por meio de mais de um namespace XAML. Esse cenário ocorre quando você está dando suporte a vários vocabulários com a mesma base de código.

  • Você define o suporte à linguagem XAML em um ou mais namespaces CLR. Nesse caso, o XmlNamespace valor deve ser http://schemas.microsoft.com/winfx/2006/xaml.

XmlnsPrefixAttribute

Documentação de referência:XmlnsPrefixAttribute

Argumentos:

  • Uma cadeia de caracteres que especifica o identificador de um namespace XAML.

  • Uma cadeia de caracteres que especifica um prefixo recomendado.

    XmlnsDefinitionAttribute especifica um prefixo recomendado a ser usado para um namespace XAML. O prefixo é útil ao gravar elementos e atributos em um arquivo XAML serializado pelos Serviços XamlXmlWriterXAML do .NET ou quando uma biblioteca de implementação de XAML interage com um ambiente de design que tem recursos de edição XAML.

    Mais de um XmlnsPrefixAttribute pode ser aplicado a uma montagem. Isso pode ser feito por qualquer combinação dos seguintes motivos:

  • Seu assembly define tipos para mais de um namespace XAML. Nesse caso, defina valores de prefixo diferentes para cada namespace XAML.

  • Você está dando suporte a vários vocabulários e usa prefixos diferentes para cada vocabulário e namespace XAML.

  • Você define o suporte à linguagem XAML no assembly e tem um XmlnsDefinitionAttribute para http://schemas.microsoft.com/winfx/2006/xaml. Nesse caso, você normalmente deve promover o prefixo x.

Observação

Os Serviços XAML do .NET também definem o atributo RootNamespaceAttributerelacionado a XAML. Esse atributo é um atributo de nível de assembly para suporte ao sistema de projeto e não é relevante para tipos personalizados XAML.

Confira também