Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
23.1 Generalidades
Grande parte da linguagem C# permite que o programador especifique informações declarativas sobre as entidades definidas no programa. Por exemplo, a acessibilidade de um método em uma classe é especificada decorando-a com os method_modifiers public, protected, internale private.
O C# permite que os programadores inventem novos tipos de informações declarativas, chamados atributoss. Os programadores podem então anexar atributos a várias entidades do programa e recuperar informações de atributos em um ambiente de tempo de execução.
Nota: Por exemplo, um framework pode definir um
HelpAttributeatributo que pode ser atribuído a certos elementos do programa (como classes e métodos) para fornecer um mapeamento desses elementos do programa para a sua documentação. Nota final
Os atributos são definidos através da declaração de classes de atributos (§23.2), que podem ter parâmetros posicionais e nomeados (§23.2.3). Os atributos são anexados a entidades em um programa C# usando especificações de atributo (§23.3) e podem ser recuperados em tempo de execução como instâncias de atributo (§23.4).
23.2 Classes de atributos
23.2.1 Generalidades
Uma classe que deriva da classe System.Attributeabstrata , direta ou indiretamente, é uma classe de atributo. A declaração de uma classe de atributo define um novo tipo de atributo que pode ser colocado em entidades de programa. Por convenção, as classes de atributos são nomeadas com um sufixo de Attribute. Os usos de um atributo podem incluir ou omitir esse sufixo.
Uma classe de atributo pode ser genérica. Quando um attribute_name faz referência a uma classe de atributo genérica, cada argumento de tipo está sujeito às mesmas restrições que se aplicam a um argumento de tipo do typeof operador (§12.8.18); por exemplo, dynamic, um tipo de tupla com nomes de elementos, um tipo de referência anulável, nint, e nuint não são permitidos como argumentos de tipo. (Além disso, um parâmetro de tipo da declaração circundante não deve ser usado como argumento de tipo; ver §8.5.)
Exemplo:
public class Attr<T> : Attribute { } // OK – generic attribute class [Attr<int>] // OK public class C1 { }Exemplo final
23.2.2 Utilização de atributos
O atributo AttributeUsageAttribute (§23.5.2) é usado para descrever como uma classe de atributo pode ser usada.
AttributeUsageAttribute tem um parâmetro posicional (§23.2.3) que permite a uma classe de atributo especificar os tipos de entidades do programa sobre as quais pode ser utilizada.
Exemplo: O exemplo seguinte define uma classe de atributos chamada
SimpleAttributeque pode ser colocada apenas em class_declarations e interface_declarations, e mostra várias utilizações doSimpleatributo.[AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface)] public class SimpleAttribute : Attribute { ... } [Simple] class Class1 {...} [Simple] interface Interface1 {...}Embora este atributo seja definido com o nome
SimpleAttribute, quando este atributo é usado, o sufixoAttributepode ser omitido, resultando no nomeSimplecurto . Assim, o exemplo acima é semanticamente equivalente ao seguinte[SimpleAttribute] class Class1 {...} [SimpleAttribute] interface Interface1 {...}Exemplo final
AttributeUsageAttribute tem um parâmetro nomeado (§23.2.3), chamado AllowMultiple, que indica se o atributo pode ser especificado mais do que uma vez para uma dada entidade. Se AllowMultiple para uma classe de atributo for true, essa classe de atributo será uma classe de atributo de uso múltiplo e poderá ser especificada mais de uma vez em uma entidade. Se AllowMultiple uma classe de atributo for false ou não for especificada, essa classe de atributo será uma classe de atributo de uso único e poderá ser especificada no máximo uma vez em uma entidade.
Nota: Para uma classe de atributos genérica, a multiplicidade é determinada pela definição de classe de atributos genérica não limitada, não por construções fechadas individuais. Portanto, quando
AllowMultipleé falso ou não especificado, duas aplicações de atributos que diferem apenas nos seus argumentos de tipo não deverão aparecer ambas na mesma entidade. Nota final
Exemplo: O exemplo seguinte define uma classe de atributo multiuso nomeada
AuthorAttributee mostra uma declaração de classe com duas utilizações doAuthoratributo:[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)] public class AuthorAttribute : Attribute { public string Name { get; } public AuthorAttribute(string name) => Name = name; } [Author("Brian Kernighan"), Author("Dennis Ritchie")] class Class1 { ... }Exemplo final
AttributeUsageAttribute tem outro parâmetro nomeado (§23.2.3), chamado Inherited, que indica se o atributo, quando especificado numa classe base, também é herdado por classes que derivam dessa classe base. Se Inherited para uma classe de atributo for true, esse atributo será herdado. Se Inherited para uma classe de atributo é falso, então esse atributo não é herdado. Se não for especificado, seu valor padrão será true.
Uma classe X de atributo que não tem um AttributeUsageAttribute atributo anexado a ela, como em
class X : Attribute { ... }
é equivalente ao seguinte:
[AttributeUsage(
AttributeTargets.All,
AllowMultiple = false,
Inherited = true)
]
class X : Attribute { ... }
23.2.3 Parâmetros posicionais e nomeados
As classes de atributos podem ter parâmetrosposicionais s e parâmetrosnomeados. Cada construtor de instância pública para uma classe de atributo define uma sequência válida de parâmetros posicionais para essa classe de atributo. Cada campo público de leitura-escrita não estático e propriedade pública de leitura-escrita ou read-init não estática para uma classe de atributos define um parâmetro nomeado para a classe de atributo. Para que uma propriedade defina um parâmetro nomeado, essa propriedade deve ter tanto um acessório público como um conjunto público ou acessório init.
Exemplo: O exemplo seguinte define uma classe de atributos chamada
HelpAttributeque tem um parâmetro posicional,url, e um parâmetro nomeado,Topic. Embora seja não estática e pública, a propriedadeUrlnão define um parâmetro nomeado, pois não é leitura-escrita nem leitura-entrada. Dois usos desse atributo também são mostrados:[AttributeUsage(AttributeTargets.Class)] public class HelpAttribute : Attribute { public HelpAttribute(string url) // url is a positional parameter { ... } // Topic is a named parameter public string Topic { get; set; } public string Url { get; } } [Help("http://www.mycompany.com/xxx/Class1.htm")] class Class1 { } [Help("http://www.mycompany.com/xxx/Misc.htm", Topic ="Class2")] class Class2 { }Exemplo final
23.2.4 Tipos de parâmetros de atributo
Os tipos de parâmetros posicionais e nomeados para uma classe de atributo são limitados aos tipos de parâmetro de atributos, que são:
- Um dos seguintes tipos:
bool,byte, ,char,doublefloat,int,long,sbyte,short,stringuintulongushort. - O tipo
object. - O tipo
System.Type. - Tipos de enum.
- Matrizes unidimensionais dos tipos acima.
- Um argumento de construtor ou campo público que não tenha um desses tipos, não deve ser usado como um parâmetro posicional ou nomeado em uma especificação de atributo.
23.3 Especificação de atributos
A aplicação de um atributo previamente definido a uma entidade de programa é chamada de especificação de atributo. Um atributo é uma parte de informações declarativas adicionais que é especificada para uma entidade de programa. Os atributos podem ser especificados no âmbito global (para especificar atributos no conjunto ou módulo que o contém) e para type_declarations (§14.8), class_member_declarations (§15.3), interface_member_declarations (§19.4), struct_member_declarations (§16.3), enum_member_declarations (§20.2), accessor_declarations (§15.7.3), event_accessor_declarations (§15.8),local_function_declarations (§13.6.4), elementos de parameter_lists (§15.6.2), elementos de type_parameter_lists (§15.2.3), lambda_expressions (§12.22.1) e elementos de explicit_anonymous_function_parameters e implicit_anonymous_function_parameters (§12.22.1).
Os atributos são especificados na seção de atributos. Uma seção de atributos consiste em um par de colchetes, que cercam uma lista separada por vírgulas de um ou mais atributos. A ordem em que os atributos são especificados em tal lista e a ordem em que as seções anexadas à mesma entidade do programa são organizadas não é significativa. Por exemplo, as especificações [A][B]de atributo , [B][A], [A, B], e [B, A] são equivalentes.
global_attributes
: global_attribute_section+
;
global_attribute_section
: '[' global_attribute_target_specifier attribute_list ']'
;
global_attribute_target_specifier
: global_attribute_target ':'
;
global_attribute_target
: identifier
;
attributes
: attribute_section+
;
attribute_section
: '[' attribute_target_specifier? attribute_list ']'
;
attribute_target_specifier
: attribute_target ':'
;
attribute_target
: identifier
| keyword
;
attribute_list
: attribute (',' attribute)* ','?
;
attribute
: attribute_name attribute_arguments?
;
attribute_name
: type_name
;
attribute_arguments
: '(' ')'
| '(' positional_argument_list (',' named_argument_list)? ')'
| '(' named_argument_list ')'
;
positional_argument_list
: positional_argument (',' positional_argument)*
;
positional_argument
: argument_name? attribute_argument_expression
;
named_argument_list
: named_argument (',' named_argument)*
;
named_argument
: identifier '=' attribute_argument_expression
;
attribute_argument_expression
: non_assignment_expression
;
Para o global_attribute_target de produção, e no texto abaixo, o identificador deve ter uma grafia igual a ou assembly, onde igualdade é a definida no module. Para a produção attribute_target, e no texto abaixo, identificador deve ter uma grafia que não é igual a assembly ou module, usando a mesma definição de igualdade como acima.
Um atributo consiste em um attribute_name e uma lista opcional de argumentos posicionais e nomeados. Os argumentos posicionais (se houver) precedem os argumentos nomeados. Um argumento posicional consiste em um attribute_argument_expression, um argumento nomeado consiste em um nome, seguido por um sinal de igual, seguido por um attribute_argument_expression, que, juntos, são limitados pelas mesmas regras que a atribuição simples. A ordem dos argumentos nomeados não é significativa.
Nota: Para conveniência, uma vírgula final é permitida numa global_attribute_section e numa attribute_section, tal como é permitida numa array_initializer (§17.7). Nota final
O attribute_name identifica uma classe de atributo.
Quando um atributo é colocado no nível global, uma global_attribute_target_specifier é necessária. Quando o global_attribute_target for igual a:
-
assembly— o alvo é o conjunto de contenção -
module— o alvo é o módulo de contenção
Não são permitidos outros valores para global_attribute_target .
Os nomes attribute_target padronizados Estas denominações-alvo só podem ser utilizadas nos seguintes contextos:
-
event— um evento. -
field— um campo. Um evento semelhante a um campo (ou seja, um evento sem acessadores) (§15.8.2) e uma propriedade implementada automaticamente (§15.7.4) também podem ter um atributo com esse destino. -
method— um construtor; finalizador; método; função local; operador; proprietários get, set e init; indexador acessórios get, set e init; event add e remove accessors; e expressões lambda. Um evento semelhante a um campo (ou seja, um sem acessadores) também pode ter um atributo com esse destino. -
param— conjunto de propriedades e acessores init, conjuntos indexadores e acessores init, acessores de adição e remoção de eventos, e um parâmetro num construtor, método, função local e operador. -
property— uma propriedade e um indexador. -
return— um delegado, método, função local, operador, accessor property get, indexer get accessor e expressão lambda. -
type— um delegado, classe, struct, enum e interface. -
typevar— um parâmetro de tipo.
Certos contextos permitem a especificação de um atributo em mais de um destino. Um programa pode especificar explicitamente o destino incluindo um attribute_target_specifier. Sem um attribute_target_specifier um padrão é aplicado, mas um attribute_target_specifier pode ser usado para afirmar ou substituir o padrão. Os contextos são resolvidos da seguinte forma:
- Para um atributo em uma declaração de delegado, o destino padrão é o delegado. Caso contrário, quando o attribute_target for igual a:
-
type— o alvo é o delegado -
return— o alvo é o valor de retorno
-
- Para um atributo em uma declaração de método, o destino padrão é o método. Caso contrário, quando o attribute_target for igual a:
-
method— o alvo é o método -
return— o alvo é o valor de retorno
-
- Para um atributo numa declaração de função local, o alvo padrão é a função local. Caso contrário, quando o attribute_target for igual a:
-
method— o alvo é a função local -
return— o alvo é o valor de retorno
-
- Para um atributo em uma declaração de operador, o destino padrão é o operador. Caso contrário, quando o attribute_target for igual a:
-
method— o alvo é o operador -
return— o alvo é o valor de retorno
-
- Para um atributo em uma declaração get accessor para uma declaração de propriedade ou indexador, o destino padrão é o método associado. Caso contrário, quando o attribute_target for igual a:
-
method— o alvo é o método associado -
return— o alvo é o valor de retorno
-
- Para um atributo especificado num acessório conjunto ou init para uma declaração de propriedade ou indexador, o alvo padrão é o método associado. Caso contrário, quando o attribute_target for igual a:
-
method— o alvo é o método associado -
param— o alvo é o único parâmetro implícito
-
- Para um atributo em uma declaração de propriedade implementada automaticamente, o destino padrão é a propriedade. Caso contrário, quando o attribute_target for igual a:
-
field— o alvo é o campo de apoio gerado pelo compilador para a propriedade
-
- Para um atributo especificado em uma declaração de evento que omite event_accessor_declarations o destino padrão é a declaração de evento. Caso contrário, quando o attribute_target for igual a:
-
event— o alvo é a declaração do evento -
field— o alvo é o campo -
method— os alvos são os métodos
-
- No caso de uma declaração de evento que não omite event_accessor_declarations o destino padrão é o método.
-
method— o alvo é o método associado -
param— o alvo é o único parâmetro
-
- Para um atributo numa lambda_expression o alvo padrão é o método. Caso contrário, quando o attribute_target for igual a:
-
method— o alvo é o método -
return— o alvo é o valor de retorno
-
Em todos os outros contextos, a inclusão de um attribute_target_specifier é permitida, mas desnecessária.
Exemplo: uma declaração de classe pode incluir ou omitir o especificador
type:[type: Author("Brian Kernighan")] class Class1 {} [Author("Dennis Ritchie")] class Class2 {}Fim do exemplo.
Uma implementação pode aceitar outros attribute_targets, cujos objetivos são de implementação definidos. Uma implementação que não reconheça tal attribute_target deve emitir um aviso e ignorar o attribute_section contido.
Por convenção, as classes de atributos são nomeadas com um sufixo de Attribute. Um attribute_name pode incluir ou omitir esse sufixo. Especificamente, uma attribute_name é resolvida da seguinte forma:
- Se o identificador mais à direita do attribute_name for um identificador literal (§6.4.3), então o attribute_name é resolvido como um type_name (§7.7). Se o resultado não for um tipo derivado de , ocorrerá um erro em tempo de
System.Attributecompilação. - Caso contrário,
- O attribute_name é resolvido como um type_name (§7.7), exceto que quaisquer erros são suprimidos. Se essa resolução for bem-sucedida e resultar em um tipo derivado
System.Attribute, o tipo será o resultado desta etapa. - Os caracteres
Attributesão adicionados ao identificador mais à direita no attribute_name e a cadeia resultante de tokens é resolvida como um type_name (§7.7), exceto que quaisquer erros são suprimidos. Se essa resolução for bem-sucedida e resultar em um tipo derivadoSystem.Attribute, o tipo será o resultado desta etapa.
- O attribute_name é resolvido como um type_name (§7.7), exceto que quaisquer erros são suprimidos. Se essa resolução for bem-sucedida e resultar em um tipo derivado
Se exatamente uma das duas etapas acima resultar em um tipo derivado de System.Attribute, então esse tipo é o resultado do attribute_name. Caso contrário, ocorrerá um erro em tempo de compilação.
Exemplo: Se uma classe de atributo for encontrada tanto com como sem este sufixo, existe uma ambiguidade e resulta um erro em tempo de compilação. Se o attribute_name estiver escrito de tal forma que o seu identificador mais à direita seja um identificador literal (§6.4.3), apenas um atributo sem sufixo é correspondido, permitindo assim resolver tal ambiguidade. O exemplo
[AttributeUsage(AttributeTargets.All)] public class Example : Attribute {} [AttributeUsage(AttributeTargets.All)] public class ExampleAttribute : Attribute {} [Example] // Error: ambiguity class Class1 {} [ExampleAttribute] // Refers to ExampleAttribute class Class2 {} [@Example] // Refers to Example class Class3 {} [@ExampleAttribute] // Refers to ExampleAttribute class Class4 {}mostra duas classes de atributos denominadas
ExampleeExampleAttribute. O atributo[Example]é ambíguo, uma vez que pode referir-se a qualquer umExampleouExampleAttribute. O uso de um identificador literal permite que a intenção exata seja especificada em casos tão raros. O atributo[ExampleAttribute]não é ambíguo (embora fosse se houvesse uma classe de atributo chamadaExampleAttributeAttribute!). Se a declaração para a classeExamplefor removida, ambos os atributos se referem à classe de atributo chamadaExampleAttribute, da seguinte maneira:[AttributeUsage(AttributeTargets.All)] public class ExampleAttribute : Attribute {} [Example] // Refers to ExampleAttribute class Class1 {} [ExampleAttribute] // Refers to ExampleAttribute class Class2 {} [@Example] // Error: no attribute named “Example” class Class3 {}Exemplo final
É um erro em tempo de compilação usar uma classe de atributo de uso único mais de uma vez na mesma entidade.
Exemplo: O exemplo
[AttributeUsage(AttributeTargets.Class)] public class HelpStringAttribute : Attribute { public HelpStringAttribute(string value) { Value = value; } public string Value { get; } } [HelpString("Description of Class1")] [HelpString("Another description of Class1")] // multiple uses not allowed public class Class1 {}resulta em um erro em tempo de compilação porque ele tenta usar
HelpStringAttribute, que é uma classe de atributo de uso único, mais de uma vez na declaração deClass1.Exemplo final
Uma expressão E é um attribute_argument_expression se todas as seguintes instruções forem verdadeiras:
- O tipo de é um tipo de parâmetro de
Eatributo (§23.2.4). - Em tempo de compilação, o valor de
Epode ser resolvido para um dos seguintes:
Exemplo:
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Field)] public class TestAttribute : Attribute { public int P1 { get; set; } public Type P2 { get; set; } public object P3 { get; set; } } [Test(P1 = 1234, P3 = new int[]{1, 3, 5}, P2 = typeof(float))] class MyClass {} class C<T> { [Test(P2 = typeof(T))] // Error – T not a closed type. int x1; [Test(P2 = typeof(C<T>))] // Error – C<;T>; not a closed type. int x2; [Test(P2 = typeof(C<int>))] // Ok int x3; [Test(P2 = typeof(C<>))] // Ok int x4; }Exemplo final
Os atributos de um tipo declarado em várias partes são determinados pela combinação, em uma ordem não especificada, dos atributos de cada uma de suas partes. Se o mesmo atributo for colocado em várias partes, é equivalente a especificar esse atributo várias vezes no tipo.
Exemplo: As duas partes:
[Attr1, Attr2("hello")] partial class A {} [Attr3, Attr2("goodbye")] partial class A {}são equivalentes à seguinte declaração única:
[Attr1, Attr2("hello"), Attr3, Attr2("goodbye")] class A {}Exemplo final
Os atributos nos parâmetros de tipo combinam-se da mesma maneira.
23.4 Instâncias de atributos
23.4.1 Generalidades
Uma ocorrência de atributo é uma instância que representa um atributo em tempo de execução. Um atributo é definido com uma classe de atributo, argumentos posicionais e argumentos nomeados. Uma ocorrência de atributo é uma instância da classe de atributo que é inicializada com os argumentos posicionais e nomeados.
A recuperação de uma instância de atributo envolve processamento em tempo de compilação e em tempo de execução, conforme descrito nas subcláusulas a seguir.
23.4.2 Compilação de um atributo
A compilação de um das seguintes etapas:
- Siga as etapas de processamento em tempo de compilação para compilar uma object_creation_expression do novo formulário
T(P). Essas etapas resultam em um erro em tempo de compilação ou determinam um construtorCde instância queTpode ser invocado em tempo de execução. - Se
Cnão tiver acessibilidade pública, ocorrerá um erro em tempo de compilação. - Para cada named_argument
ArgemN:- Seja
Nameo identificador do named_argumentArg. -
Namedeve identificar um campo público de leitura-escrita não estático ou uma propriedade pública de leitura-escrita ou leitura-init emT. SeTnão tiver esse campo ou propriedade, ocorrerá um erro em tempo de compilação.
- Seja
- Se qualquer um dos valores dentro de positional_argument_list
Pou um dos valores dentro de named_argument_listNfor do tipoSystem.Stringe o valor não estiver bem formado conforme definido pelo Padrão Unicode, será definido pela implementação se o valor compilado é igual ao valor de tempo de execução recuperado (§23.4.3).Nota: Por exemplo, uma cadeia que contém uma unidade de código substituto UTF-16 elevada e que não é imediatamente seguida por uma unidade de código substituto baixa não está bem formada. Nota final
- Armazene as seguintes informações (para instanciação em tempo de execução do atributo) na saída do assembly pelo compilador como resultado da compilação do programa que contém o atributo: a classe
Tde atributo , o construtorCde instância emT, o positional_argument_listP, o named_argument_listNe a entidadeEde programa associada , com os valores resolvidos completamente em tempo de compilação.
23.4.3 Recuperação em tempo de execução de uma instância de atributo
Usando os termos definidos em §23.4.2, a instância de atributo representada por T, C, Pe , e Nassociada a E pode ser recuperada em tempo de execução do assembly A usando as seguintes etapas:
- Siga as etapas de processamento em tempo de execução para executar um de compilação. Essas etapas resultam em uma exceção ou produzem uma instância
OdeT. - Para cada named_argument
ArgemN, pela ordem:- Seja
Nameo identificador do named_argumentArg. SeNamenão identificar um campo de leitura-escrita público não estático ou uma propriedade de leitura-escrita pública ou read-init não estática emO, então é lançada uma exceção. - Sejamos
Valueo resultado da avaliação do attribute_argument_expression deArg. - Se
Nameidentificar um campo noO, defina este campo comoValue. - Caso contrário, Name identifica uma propriedade em
O. Defina esta propriedade como Value. - O resultado é
O, uma instância da classeTde atributo que foi inicializada com o positional_argument_listPe o named_argument_listN.
- Seja
Nota: O formato para armazenar
T,C,P,N(e associá-lo aE) emAe o mecanismo para especificarEe recuperarT,C,P,NdeA(e, portanto, como uma instância de atributo é obtida em tempo de execução) está fora do âmbito desta especificação. Nota final
23.5 Atributos reservados
23.5.1 Generalidades
Vários atributos afetam a linguagem de alguma forma. Estes atributos incluem:
-
System.AttributeUsageAttribute(§23.5.2), que é usada para descrever as formas como uma classe de atributo pode ser utilizada. -
System.Diagnostics.ConditionalAttribute(§23.5.3), é uma classe de atributos multiutilização utilizada para definir métodos condicionais e classes de atributos condicionais. Este atributo indica uma condição testando um símbolo de compilação condicional. -
System.ObsoleteAttribute(§23.5.4), que é usada para marcar um membro como obsoleto. -
System.Runtime.CompilerServices.AsyncMethodBuilderAttribute(§23.5.5), que é usada para estabelecer um construtor de tarefas para um método assíncrono. -
System.Runtime.CompilerServices.CallerLineNumberAttribute(§23.5.6.2),System.Runtime.CompilerServices.CallerFilePathAttribute(§23.5.6.3),System.Runtime.CompilerServices.CallerMemberNameAttribute(§23.5.6.4) eSystem.Runtime.CompilerServices.CallerArgumentExpressionAttribute(§23.5.6.5), que são usados para fornecer informação sobre o contexto de chamada a parâmetros opcionais. -
System.Runtime.CompilerServices.EnumeratorCancellationAttribute(§23.5.10), que é usado para especificar o parâmetro do token de cancelamento num iterador assíncrono. -
System.Runtime.CompilerServices.ModuleInitializerAttribute(§23.5.11), que é usada para marcar um método como inicializador de módulo. -
System.Runtime.CompilerServices.InterpolatedStringHandlerAttributeeSystem.Runtime.CompilerServices.InterpolatedStringHandlerArgumentAttribute, que são usados para declarar um manipulador de expressões de strings interpolado personalizado (§23.5.11.1) e para chamar um dos seus construtores, respetivamente. - System.Diagnostics.CodeAnalysis.UnscopedRefAttribute (§23.5.8), que permite que uma ref de outra forma implicitamente definida seja tratada como não estando com scopo.
-
System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute(§23.5.12.1) eSystem.Runtime.CompilerServices.RequiredMemberAttribute(§23.5.12.2), que são usados em contextos de membros obrigatórios (§15.7.1). -
System.Runtime.CompilerServices.CollectionBuilderAttribute(§23.5.13), que designa um tipo de coleção como tendo um método de criação de coleções. -
System.Runtime.CompilerServices.InlineArrayAttribute(§23.5.14), que marca um tipo de struct como um tipo de array em linha (§16.6). -
System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute(§23.5.15), que especifica a prioridade de um membro durante a resolução de sobrecarga.
Os atributos de análise estática anulável (§23.5.7) podem melhorar a correção dos avisos gerados para anulabilidades e estados nulos (§8.9.5).
Um ambiente de execução pode fornecer atributos adicionais definidos pela implementação que afetam a execução de um programa em C#.
23.5.2 O atributo AttributeUsage
O atributo AttributeUsageAttribute é usado para descrever a maneira como a classe de atributo pode ser usada.
Uma classe decorada com o AttributeUsageAttribute atributo deve derivar de System.Attribute, direta ou indiretamente. Caso contrário, ocorrerá um erro em tempo de compilação.
Nota: Para um exemplo de utilização deste atributo, veja §23.2.2. Nota final
23.5.3 O atributo Condicional
23.5.3.1 Generalidades
O atributo ConditionalAttribute permite a definição de métodos condicionaiss, função local condicionals e classe de atributos condicionales.
23.5.3.2 Métodos condicionais
Um método decorado com ConditionalAttribute é um método condicional. Cada método condicional está assim associado aos símbolos de compilação condicional declarados no seu ConditionalAttributes.
Exemplo:
class Eg { [Conditional("ALPHA")] [Conditional("BETA")] public static void M() { // ... } }declara
Eg.Mcomo um método condicional associado aos dois símbolosALPHAde compilação condicional eBETA.Exemplo final
Uma chamada para um método condicional é incluída se um ou mais de seus símbolos de compilação condicional associados forem definidos no ponto de chamada, caso contrário, a chamada será omitida.
Um método condicional está sujeito às seguintes restrições:
- O método condicional deve ser um método de class_declaration ou struct_declaration. Ocorre um erro em tempo de compilação se
ConditionalAttributefor especificado num método numa declaração de interface. - O método condicional não deve ser um acessório de uma propriedade, indexador ou evento.
- O método condicional deve ter um tipo de retorno de
void. - O método condicional não deve ser marcado com o
overridemodificador. No entanto, um método condicional pode ser marcado com ovirtualmodificador. As sobreposições de tal método são implicitamente condicionais e não devem ser explicitamente marcadas comConditionalAttribute. - O método condicional não deve ser uma aplicação de um método de interface. Caso contrário, ocorrerá um erro em tempo de compilação.
- Os parâmetros do método condicional não devem ser parâmetros de saída.
Nota: Atributos com um
AttributeUsageAttribute(§23.2.2) incluindoAttributeTargets.Methodpodem normalmente ser aplicados a acessores de propriedades, indexadores e eventos. As restrições acima proíbem este uso deConditionalAttribute. Nota final
Além disso, um erro em tempo de compilação ocorre se um delegado é criado a partir de um método condicional.
Exemplo: O exemplo
#define DEBUG using System; using System.Diagnostics; class Class1 { [Conditional("DEBUG")] public static void M() { Console.WriteLine("Executed Class1.M"); } } class Class2 { public static void Test() { Class1.M(); } }declara
Class1.Mcomo um método condicional.Class2chamaTesta este método. Uma vez que o símboloDEBUGde compilação condicional é definido, seClass2.Testfor chamado, ele chamaráM. Se o símboloDEBUGnão tivesse sido definido, entãoClass2.Testnão chamariaClass1.M.Exemplo final
É importante entender que a inclusão ou exclusão de uma chamada para um método condicional é controlada pelos símbolos de compilação condicional no ponto da chamada.
Exemplo: No código seguinte
// File Class1.cs: using System; using System.Diagnostics; class Class1 { [Conditional("DEBUG")] public static void F() { Console.WriteLine("Executed Class1.F"); } } // File Class2.cs: #define DEBUG class Class2 { public static void G() { Class1.F(); // F is called } } // File Class3.cs: #undef DEBUG class Class3 { public static void H() { Class1.F(); // F is not called } }As classes
Class2eClass3cada uma contêm chamadas para o métodoClass1.Fcondicional , que é condicional com base na definição ou nãoDEBUG. Uma vez que este símbolo é definido no contexto deClass2, mas nãoClass3, a chamada paraFdentroClass2é incluída, enquanto a chamada paraFdentroClass3é omitida.Exemplo final
O uso de métodos condicionais em uma cadeia de herança pode ser confuso. As chamadas feitas para um método condicional através basede , do formulário base.M, estão sujeitas às regras normais de chamada de método condicional.
Exemplo: No código seguinte
// File Class1.cs using System; using System.Diagnostics; class Class1 { [Conditional("DEBUG")] public virtual void M() => Console.WriteLine("Class1.M executed"); } // File Class2.cs class Class2 : Class1 { public override void M() { Console.WriteLine("Class2.M executed"); base.M(); // base.M is not called! } } // File Class3.cs #define DEBUG class Class3 { public static void Main() { Class2 c = new Class2(); c.M(); // M is called } }
Class2inclui uma chamada aoMdefinido na sua classe base. Esta chamada é omitida porque o método base é condicional com base na presença do símboloDEBUG, que é indefinido. Assim, o método grava apenas no console "Class2.M executed". O uso judicioso de pp_declarations pode eliminar tais problemas.Exemplo final
23.5.3.3 Funções locais condicionais
Uma função local estática pode ser tornada condicional no mesmo sentido que um método condicional (§23.5.3.2).
Ocorre um erro em tempo de compilação se uma função local não estática for condicional.
23.5.3.4 Classes de atributos condicionais
Uma classe de atributo (§23.2) decorada uma ConditionalAttribute ou mais vezes é uma classe de atributo condicional. Uma classe de atributo condicional está assim associada aos símbolos de compilação condicional declarados no seu ConditionalAttributes.
Exemplo:
[Conditional("ALPHA")] [Conditional("BETA")] public class TestAttribute : Attribute {}declara
TestAttributecomo uma classe de atributo condicional associada aos símbolosALPHAde compilações condicionais eBETA.Exemplo final
As especificações de atributo (§23.3) de um atributo condicional são incluídas se um ou mais dos seus símbolos de compilação condicional associados forem definidos no ponto de especificação, caso contrário, a especificação do atributo será omitida.
É importante notar que a inclusão ou exclusão de uma especificação de atributo de uma classe de atributo condicional é controlada pelos símbolos de compilação condicional no ponto da especificação.
Exemplo: No exemplo
// File Test.cs: using System; using System.Diagnostics; [Conditional("DEBUG")] public class TestAttribute : Attribute {} // File Class1.cs: #define DEBUG [Test] // TestAttribute is specified class Class1 {} // File Class2.cs: #undef DEBUG [Test] // TestAttribute is not specified class Class2 {}as classes
Class1eClass2são cada uma decorada com atributoTest, que é condicional com base em se é definido ou nãoDEBUG. Uma vez que este símbolo é definido no contexto deClass1, mas nãoClass2, a especificação do atributo Test onClass1é incluída, enquanto a especificação doTestatributo onClass2é omitida.Exemplo final
23.5.4 O atributo Obsoleto
O atributo ObsoleteAttribute é usado para marcar tipos e membros de tipos que não devem mais ser usados.
Se um programa usar um tipo ou membro decorado com ObsoleteAttribute, um compilador deverá emitir um aviso ou um erro. Especificamente, um compilador deve emitir um aviso se nenhum parâmetro de erro for fornecido, ou se o parâmetro de erro for fornecido e tiver o valor false. Um compilador deve emitir um erro se o parâmetro error for especificado e tiver o valor true.
Exemplo: No código seguinte
[Obsolete("This class is obsolete; use class B instead")] class A { public void F() {} } class B { public void F() {} } class Test { static void Main() { A a = new A(); // Warning a.F(); } }A turma
Aestá decorada comObsoleteAttribute. Cada uso deAinMainresulta em um aviso que inclui a mensagem especificada, "Esta classe está obsoleta; use a classeBem vez disso".Exemplo final
23.5.5 O atributo AsyncMethodBuilder
Este atributo associa um construtor a um tipo de tarefa (§15.14.1) ou seleciona um construtor para uma função assíncrona (§15.14.5).
23.5.6 Atributos de informações do chamador
23.5.6.1 Generalidades
Para fins como registro em log e relatórios, às vezes é útil para um membro da função obter certas informações em tempo de compilação sobre o código de chamada. Os atributos caller-info fornecem uma maneira de passar essas informações de forma transparente.
Quando um parâmetro opcional é anotado com um dos atributos caller-info, omitir o argumento correspondente em uma chamada não faz necessariamente com que o valor do parâmetro padrão seja substituído. Em vez disso, se as informações especificadas sobre o contexto de chamada estiverem disponíveis, essas informações serão passadas como o valor do argumento.
Exemplo:
public void Log( [CallerLineNumber] int line = -1, [CallerFilePath] string path = null, [CallerMemberName] string name = null ) { Console.WriteLine((line < 0) ? "No line" : "Line "+ line); Console.WriteLine((path == null) ? "No file path" : path); Console.WriteLine((name == null) ? "No member name" : name); }Uma chamada para
Log()sem argumentos imprimiria o número da linha e o caminho do arquivo da chamada, bem como o nome do membro no qual a chamada ocorreu.Exemplo final
Os atributos calller-info podem ocorrer em parâmetros opcionais em qualquer lugar, inclusive em declarações de delegado. No entanto, os atributos específicos caller-info têm restrições sobre os tipos dos parâmetros que podem atribuir, de modo que sempre haverá uma conversão implícita de um valor substituído para o tipo de parâmetro.
É um erro ter o mesmo atributo caller-info num parâmetro tanto da parte definidora como da implementação de uma declaração de método parcial ou indexador parcial. Somente os atributos caller-info na parte definidora são aplicados, enquanto os atributos caller-info que ocorrem apenas na parte de implementação são ignorados.
As informações do chamador não afetam a resolução da sobrecarga. Como os parâmetros opcionais atribuídos ainda são omitidos do código-fonte do chamador, a resolução de sobrecarga ignora esses parâmetros da mesma forma que ignora outros parâmetros opcionais omitidos (§12.6.4).
As informações do chamador só são substituídas quando uma função é explicitamente invocada no código-fonte. Invocações implícitas, como chamadas implícitas do construtor pai, não têm um local de origem e não substituirão as informações do chamador. Além disso, as chamadas vinculadas dinamicamente não substituirão as informações do chamador. Quando um parâmetro caller-info atribuído é omitido nesses casos, o valor padrão especificado do parâmetro é usado em vez disso.
Uma exceção são as expressões de consulta. Estas são consideradas expansões sintáticas e, se as chamadas forem expandidas para omitir parâmetros opcionais com atributos caller-info, as informações do chamador serão substituídas. O local usado é o local da cláusula de consulta a partir da qual a chamada foi gerada.
Se mais do que um atributo de informação do chamador for especificado num dado parâmetro, eles são reconhecidos pela seguinte ordem: CallerLineNumberAttribute, CallerFilePathAttribute, CallerMemberNameAttribute, CallerArgumentExpressionAttribute. Considere a seguinte declaração de parâmetro:
[CallerMemberName, CallerFilePath, CallerLineNumber] object p = ...
CallerLineNumberAttribute tem prioridade, e os outros três atributos são ignorados. Se CallerLineNumberAttribute forem omitidos, CallerFilePathAttribute teriam prioridade, e CallerMemberNameAttribute e CallerArgumentExpressionAttribute seriam ignorados. A ordenação lexical desses atributos é irrelevante.
23.5.6.2 O atributo CallerLineNumber
O atributo CallerLineNumberAttribute é permitido em parâmetros opcionais quando há uma conversão implícita padrão (§10.4.2) do valor int.MaxValue constante para o tipo do parâmetro. Isso garante que qualquer número de linha não negativo até esse valor possa ser passado sem erros.
Se uma invocação de função de um local no código-fonte omitir um parâmetro opcional com o CallerLineNumberAttribute, então um literal numérico representando o número de linha desse local será usado como um argumento para a invocação em vez do valor do parâmetro padrão.
Se a invocação se estender por várias linhas, a linha escolhida dependerá da implementação.
O número da linha pode ser afetado pelas #line diretivas (§6.5.8).
23.5.6.3 O atributo CallerFilePath
O atributo CallerFilePathAttribute é permitido em parâmetros opcionais quando há uma conversão implícita padrão (§10.4.2) do tipo do string parâmetro.
Se uma invocação de função a partir de uma localização no código-fonte omitir um parâmetro opcional com o CallerFilePathAttribute, então uma string literal UTF-16 que representa o caminho do ficheiro dessa localização é usada como argumento para a invocação em vez do valor padrão do parâmetro.
O formato do caminho do arquivo depende da implementação.
O caminho do arquivo pode ser afetado por #line diretivas (§6.5.8).
23.5.6.4 O atributo CallerMemberName
O atributo CallerMemberNameAttribute é permitido em parâmetros opcionais quando há uma conversão implícita padrão (§10.4.2) do tipo do string parâmetro.
Se uma invocação de função a partir de uma localização dentro do corpo de um membro da função ou dentro de um atributo aplicado ao próprio membro da função ou ao seu tipo, parâmetros ou parâmetros de tipo de retorno no código-fonte omitir um parâmetro opcional com o CallerMemberNameAttribute, então uma literal de string UTF-16 representando o nome desse membro é usada como argumento para a invocação em vez do valor padrão do parâmetro.
Nota: No caso de uma invocação de função a partir de uma instrução de topo, a cadeia é uma representação do nome fornecido pela implementação (§7.1.3). Nota final
Para invocações que ocorrem dentro de métodos genéricos, apenas o próprio nome do método é usado, sem a lista de parâmetros type.
Para invocações que ocorrem em implementações explícitas de membro da interface, somente o nome do método em si é usado, sem a qualificação de interface anterior.
Para invocações que ocorrem dentro de acessadores de propriedade ou evento, o nome do membro usado é o da propriedade ou evento em si.
Para invocações que ocorrem dentro de acessadores indexadores, o nome de membro usado é aquele fornecido por um IndexerNameAttribute (§23.6) no membro indexador, se presente, ou o nome Item padrão de outra forma.
Para invocações que ocorrem dentro de inicializadores de campo ou evento, o nome de membro usado é o nome do campo ou evento que está sendo inicializado.
Para invocações que ocorrem em declarações de construtores de instância, construtores estáticos, finalizadores e operadores, o nome de membro usado depende da implementação.
Para uma invocação que ocorre dentro de uma função local ou anónima, é usado o nome do método membro que chama essa função.
Exemplo: Considere o seguinte:
class Program { static void Main() { F1(); Action anonymousFunction = () => F2(); anonymousFunction(); void F1([CallerMemberName] string? name = null) { Console.WriteLine($"F1 MemberName: |{name}|"); F2(); } static void F2([CallerMemberName] string? name = null) { Console.WriteLine($"F2 MemberName: |{name}|"); } } }que produz a saída
F1 MemberName: |Main| F2 MemberName: |Main| F2 MemberName: |Main|Este atributo fornece o nome do membro da função chamadora, que para função
F1local é o métodoMain. E mesmo queF2seja chamado porF1, uma função local não é um membro da função, pelo que o chamador reportado dessa invocação deF2também éMain. De forma semelhante, quandoF2é chamado pela função anónima atribuída aanonymousFunction, o chamador reportado é o métodoMain, que chama essa função anónima. Exemplo final
23.5.6.5 O atributo ExpressãoArgumentoChamada
O atributo CallerArgumentExpressionAttribute é aplicado a um parâmetro alvo e pode resultar na captura do texto do código-fonte do argumento de um parâmetro irmão como uma cadeia, aqui referida como cadeia capturada.
O parâmetro alvo deve ter um default_argument. Se o parâmetro irmão nomeado pelo atributo for o primeiro parâmetro de um método de extensão, uma invocação de método de extensão captura o texto fonte da expressão receptora. Se o método for invocado usando a sintaxe estática do método, o texto fonte do argumento correspondente a esse primeiro parâmetro é capturado.
Considere a seguinte declaração de método:
using System;
using System.Runtime.CompilerServices;
#nullable enable
class Test
{
public static void M(int val = 0, [CallerArgumentExpression("val")] string? text = null)
{
Console.WriteLine($"val = {val}, text = <{text}>");
}
}
em que o parâmetro alvo é text e o parâmetro irmão é val, cujo texto do código-fonte do argumento correspondente pode ser capturado em text quando M é chamado.
O construtor de atributos toma um argumento de tipo string. Essa corda
- Deverá conter o nome de um parâmetro irmão; caso contrário, o atributo é ignorado.
- Deve omitir o início
@de um nome de parâmetro que tenha esse prefixo.
Um parameter_list pode conter múltiplos parâmetros alvo.
Deverá haver uma conversão implícita padrão (§10.4.2) do string tipo do parâmetro alvo.
Nota: Isto exclui conversões definidas pelo utilizador de
string. Na prática, o tipo de parâmetro éstring,object,dynamic, ou uma interface implementada porstring. Umdynamictipo de parâmetro não torna, por si só, uma invocação dinamicamente limitada; a substituição de informação do chamador para invocações dinamicamente limitadas é regida pelo §23.5.6.1. Nota final
Se um argumento explícito for passado para o parâmetro alvo, nenhuma cadeia é capturada, e esse parâmetro assume o valor desse argumento. Caso contrário, o texto do argumento correspondente ao parâmetro irmão é convertido numa cadeia capturada, de acordo com as seguintes regras:
- A expressão ou variable_reference fonte fornecida para o parâmetro irmão é selecionada. Para um argumento de atributo, a sua expressão é selecionada; para um receptor de método de extensão, a sua expressão receptora é selecionada. Qualquer nome de argumento e qualquer palavra-chave do modo de passagem de argumentos (
ref,in, ouout) são excluídos. - Qualquer parenthesized_expression mais externa (§12.8.5) é substituída pela sua expressão contida, repetidamente até que o resultado não seja um parenthesized_expression. Parênteses pertencentes a um tuple_literal (§12.8.6) não são removidos.
- A cadeia capturada começa no primeiro carácter do primeiro token da expressão ou variable_reference resultante e termina no último carácter do seu último token. Espaços em branco iniciais e posteriores, terminadores de linha, comentários e diretivas do pré-processador fora destes limites são excluídos.
- Todo o texto fonte dentro destes limites é mantido literalmente, incluindo espaços em branco, terminadores de linha, comentários, diretivas do pré-processador, Unicode_Escape_Sequences e
@prefixos nos identificadores.
A cadeia capturada é então passada como argumento correspondente ao parâmetro alvo. No entanto, se o argumento para o parâmetro irmão for omitido, o parâmetro alvo assume o seu valor default_argument .
Exemplo: Dada a declaração de
Macima, considere as seguintes chamadas paraM:Test.M(); Test.M(123); Test.M(123, null); Test.M(123, "xyz"); Test.M( 1 + 2 ); Test.M(( ( (123) + 0) ) ); int local = 10; Test.M(l\u006fcal /*...*/ + // xxx 5);A saída produzida é
val = 0, text = <> val = 123, text = <123> val = 123, text = <> val = 123, text = <xyz> val = 3, text = <1 + 2> val = 123, text = <(123) + 0> val = 15, text = <l\u006fcal /*...*/ + // xxx 5>Exemplo final
Exemplo: Um parâmetro alvo opcional pode capturar o recetor de um método de extensão nomeando o primeiro parâmetro. Ambas as formas de invocação abaixo capturam
value:using System; using System.Runtime.CompilerServices; int value = 5; value.Show(); Extensions.Show(value); static class Extensions { public static void Show(this int value, [CallerArgumentExpression("value")] string text = "") { Console.WriteLine(text); } }A saída é:
value valueExemplo final
Exemplo: Comentários de fronteira e parênteses de agrupamento são excluídos, mas as tuplas entre parênteses e o texto de origem entre os tokens, incluindo diretivas, são mantidos. Os nomes dos argumentos e as palavras-chave do modo de passagem não fazem parte do texto capturado:
using System; using System.Runtime.CompilerServices; Capture(value: /*outer*/ ( /*before*/ 1 /*inside*/ + 2 /*after*/ ) /*outer*/); Capture(((1, 2))); int value = 5; CaptureRef(ref value); CaptureIn(in value); CaptureOut(out value); Capture(1 + #if true 2 #endif ); static void Capture<T>(T value, [CallerArgumentExpression("value")] string text = "") => Console.WriteLine(text); static void CaptureRef(ref int value, [CallerArgumentExpression("value")] string text = "") => Console.WriteLine(text); static void CaptureIn(in int value, [CallerArgumentExpression("value")] string text = "") => Console.WriteLine(text); static void CaptureOut(out int value, [CallerArgumentExpression("value")] string text = "") { value = 0; Console.WriteLine(text); }A saída é:
1 /*inside*/ + 2 (1, 2) value value value 1 + #if true 2O fecho
#endifestá fora do token de última expressão e, portanto, é excluído.Exemplo final
23.5.7 Atributos de análise de código
23.5.7.1 Generalidades
Os atributos nesta subcláusula são usados para fornecer informações adicionais para dar suporte a um compilador que fornece diagnóstico de anulabilidade e estado nulo (§8.9.5). Um compilador não é obrigado a realizar quaisquer diagnósticos de estado nulo. A presença ou ausência desses atributos não afetam a linguagem nem o comportamento de um programa. Um compilador que não forneça diagnósticos de estado nulo deve ler e ignorar a presença destes atributos. Um compilador que fornece diagnósticos de estado nulo deve usar o significado definido nesta subcláusula para qualquer um desses atributos que ele usa para informar seus diagnósticos.
Os atributos de análise de código são declarados no namespace System.Diagnostics.CodeAnalysis.
| Atributo | Significado |
|---|---|
AllowNullAttribute (§23.5.7.2) |
Um argumento não anulável pode ser null. |
DisallowNullAttribute (§23.5.7.3) |
Um argumento anulável nunca deve ser nulo. |
MaybeNullAttribute (§23.5.7.6) |
Um valor de retorno não anulável pode ser null. |
NotNullAttribute (§23.5.7.10) |
Um valor de retorno anulável nunca será nulo. |
MaybeNullWhenAttribute (§23.5.7.7) |
Um argumento não anulável pode ser nulo quando o método retorna o valor especificado bool . |
NotNullWhenAttribute (§23.5.7.12) |
Um argumento anulável não será nulo quando o método devolve o valor especificado bool . |
NotNullIfNotNullAttribute (§23.5.7.11) |
Um valor de retorno não é nulo se o argumento para o parâmetro especificado não for nulo. |
MemberNotNullAttribute (§23.5.7.8) |
O membro listado não será nulo quando o método regressar. |
MemberNotNullWhenAttribute (§23.5.7.9) |
O membro listado não será nulo quando o método devolver o valor especificado bool . |
DoesNotReturnAttribute (§23.5.7.4) |
Este método nunca retorna. |
DoesNotReturnIfAttribute (§23.5.7.5) |
Esse método nunca retorna se o parâmetro associado bool tiver o valor especificado. |
As seguintes suborações no §23.5.7 são condicionalmente normativas.
23.5.7.2 O atributo AllowNull
Especifica que um valor nulo é permitido como uma entrada, mesmo que o tipo correspondente não o permita.
Exemplo: Considere a seguinte propriedade de leitura/escrita que nunca retorna
nullporque tem um valor padrão razoável. No entanto, um usuário pode dar null ao acessador de conjunto para definir a propriedade para esse valor padrão.#nullable enable public class X { [AllowNull] public string ScreenName { get => _screenName; set => _screenName = value ?? GenerateRandomScreenName(); } private string _screenName = GenerateRandomScreenName(); private static string GenerateRandomScreenName() => ...; }Dado o seguinte uso do acessador de conjunto dessa propriedade:
var v = new X(); v.ScreenName = null; // may warn without attribute AllowNullSem o atributo, um compilador pode gerar um aviso porque a propriedade non-nullable-typed parece estar definida como um valor nulo. A presença do atributo suprime esse aviso. Exemplo final
23.5.7.3 O atributo DisallowNull
Especifica que um valor nulo não é permitido como uma entrada, mesmo que o tipo correspondente o permita.
Exemplo: Considere a seguinte propriedade em que nulo é o valor padrão, mas os clientes só podem defini-lo para um valor não nulo.
#nullable enable public class X { [DisallowNull] public string? ReviewComment { get => _comment; set => _comment = value ?? throw new ArgumentNullException(nameof(value), "Cannot set to null"); } private string? _comment = default; }O acessador get pode retornar o valor padrão de
null, portanto, um compilador pode avisar que ele deve ser verificado antes do acesso. Além disso, avisa os chamadores que, embora possa ser nulo, não devem defini-lo explicitamente como null. Exemplo final
23.5.7.4 O atributo DoesNotReturn
Especifica que um determinado método nunca retorna.
Exemplo: Considere o seguinte:
public class X { [DoesNotReturn] private void FailFast() => throw new InvalidOperationException(); public void SetState(object? containedField) { if ((!isInitialized) || (containedField == null)) { FailFast(); } // null check not needed. _field = containedField; } private bool isInitialized = false; private object _field; }A presença do atributo ajuda um compilador de várias maneiras. Primeiro, um compilador pode emitir um aviso se houver um caminho onde o método pode sair sem lançar uma exceção. Em segundo lugar, um compilador pode suprimir avisos anuláveis em qualquer código após uma chamada para esse método, até que uma cláusula catch apropriada seja encontrada. Em terceiro lugar, o código inacessível não afetará quaisquer estados nulos.
O atributo não altera a acessibilidade (§13.2) ou a análise de atribuição definida (§9.4) com base na presença deste atributo. Ele é usado apenas para afetar avisos de anulabilidade. Exemplo final
23.5.7.5 O atributo DoesNotReturnIf
Especifica que um determinado método nunca retorna se o parâmetro associado bool tiver o valor especificado.
Exemplo: Considere o seguinte:
#nullable enable public class X { private void ThrowIfNull([DoesNotReturnIf(true)] bool isNull, string paramName) { if (isNull) { throw new ArgumentException(paramName, $"argument for {paramName} cannot be null"); } } public void SetFieldState(object containedField) { ThrowIfNull(containedField == null, nameof(containedField)); // unreachable code when "isInitialized" is false: _field = containedField; } private bool isInitialized = false; private object _field = default!; }Exemplo final
23.5.7.6 O atributo MaybeNull
Especifica que um valor de retorno não anulável pode ser nulo.
Exemplo: Considere o seguinte método genérico:
#nullable enable [return: MaybeNull] public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate) { ... }Sem o atributo, o compilador pode gerar um aviso se o método puder devolver
null. A presença do atributo suprime esse aviso. Exemplo final
23.5.7.7 O atributo MaybeNullWhen
Especifica que um argumento não anulável pode ser null quando o método retorna o valor especificado bool . Isto é semelhante ao MaybeNullAttribute (§23.5.7.6), mas inclui um parâmetro para o valor de retorno especificado.
23.5.7.8 O atributo MemberNotNull
Especifica que o membro dado não estará null quando o método regressar.
Exemplo: Um método auxiliar pode incluir o
MemberNotNullatributo para listar quaisquer campos atribuídos a um valor não nulo nesse método. Um compilador que analisa construtores para determinar se todos os campos de referência não anuláveis foram inicializados pode então usar este atributo para descobrir quais os campos definidos por esses métodos auxiliares. Considere o seguinte exemplo:#nullable enable public class Container { private string _uniqueIdentifier; // must be initialized. private string? _optionalMessage; public Container() { Helper(); } public Container(string message) { Helper(); _optionalMessage = message; } [MemberNotNull(nameof(_uniqueIdentifier))] private void Helper() { _uniqueIdentifier = DateTime.Now.Ticks.ToString(); } }Vários nomes de campos podem ser dados como argumentos para o construtor do atributo. Exemplo final
23.5.7.9 O atributo MemberNotNullWhen
Especifica que o membro listado não estará null quando o método devolver o valor especificado bool .
Exemplo: Este atributo é como
MemberNotNull(§23.5.7.8), exceto queMemberNotNullWhentoma umboolargumento.MemberNotNullWhendestina-se a ser usado em situações em que um método auxiliar retorna umboolque indica se inicializou campos. Exemplo final
23.5.7.10 O atributo NotNull
Especifica que um valor anulável nunca será null se o método retornar (em vez de lançar).
Exemplo: Considere o seguinte:
#nullable enable public static void ThrowWhenNull([NotNull] object? value, string valueExpression = "") => _ = value ?? throw new ArgumentNullException(valueExpression); public static void LogMessage(string? message) { ThrowWhenNull(message, nameof(message)); Console.WriteLine(message.Length); }Quando os tipos de referência anuláveis estão ativados, o método
ThrowWhenNullcompila sem avisos. Quando esse método retorna, ovalueargumento é garantido como nãonull. No entanto, é aceitável chamarThrowWhenNullcom uma referência nula. Exemplo final
23.5.7.11 O atributo NotNullIfNotNull
Especifica que um valor de retorno não null é se o argumento para o parâmetro especificado não nullfor .
Exemplo: O estado nulo de um valor de retorno pode depender do estado nulo de um ou mais argumentos. Para ajudar na análise de um compilador, quando um método retorna sempre um valor não nulo quando certos argumentos não
nullsão , o método pode ser decorado comNotNullIfNotNullAttribute. Considere o seguinte método:#nullable enable string GetTopLevelDomainFromFullUrl(string url) { ... }Se o argumento
urlnãonullfor ,nullnão é devolvido. Quando as referências anuláveis estão habilitadas, essa assinatura funciona corretamente, desde que a API nunca aceite um argumento nulo. No entanto, se o argumento pode ser null, então o valor de retorno também pode ser null. Para expressar esse contrato corretamente, anote este método da seguinte forma:#nullable enable [return: NotNullIfNotNull("url")] string? GetTopLevelDomainFromFullUrl(string? url) { ... }Exemplo final
23.5.7.12 O atributo NotNullWhen
Especifica que um argumento anulável não será null quando o método devolve o valor especificado bool .
Exemplo: O método
String.IsNullOrEmpty(String)da biblioteca retornatruequando o argumento énullou uma cadeia vazia. É uma forma de verificação nula: os chamadores não precisam de verificar o argumento se o método devolverfalse. Para tornar um método anulável como este consciente, faça do tipo de parâmetro um tipo de referência anulável e decore-o comNotNullWhenAttribute:#nullable enable bool IsNullOrEmpty([NotNullWhen(false)] string? value) { ... }Exemplo final
23.5.8 O atributo UnscopedRef
Existem vários casos em que uma referência é tratada como estando implicitamente enquadrada (§9.7.3); ou seja, o árbitro não pode escapar a um método. Por exemplo:
-
thisPara métodos de instância estrutural. - parâmetros de referência que se referem a tipos de struct de ref.
- Nossos parâmetros.
Este atributo é usado nas situações em que o árbitro deve poder escapar.
Este atributo pode ser aplicado a qualquer ref um e altera o ref-safe-context para ser um nível mais largo do que o seu padrão. Por exemplo:
| UnscopedRef aplicado a | Ref-safe-context original | Novo ref-safe-context |
|---|---|---|
| Membro da instância | membro de função | somente retorno |
in
/
ref Parâmetro |
somente retorno | contexto do chamador |
out parâmetro |
membro de função | somente retorno |
Ao aplicar este atributo a um método de instância de uma struct, modifica o parâmetro implícito this ; ou seja, this atua como um não anotado ref do mesmo tipo.
Um método de instância ou propriedade anotada com UnscopedRefAttribute tem o contexto ref-safe-de de this definido para o contexto do chamador.
Um membro anotado com UnscopedRefAttribute não pode implementar uma interface.
É um erro para usar UnscopedRefAttribute em
- Um membro que não é declarado num
struct. - Um
staticmembro,initmembro ou construtor numstruct. - Um parâmetro marcado
scopedcomo . - Um parâmetro passado por valor.
- Um parâmetro passado por referência que não é implicitamente englobado.
Consulte o §9.7.3 para mais informações.
23.5.9 O atributo ScopedRef
O nome System.Runtime.CompilerServices.ScopedRefAttribute é reservado para uso em compiladores. O compilador emite este atributo num parâmetro quando a anotação do scoped parâmetro difere do seu estado padrão, para codificar o scoped modificador (§9.7.3) nos metadados. Este atributo não é permitido na fonte.
23.5.10 O atributo EnumeratorCancelamento
Especifica o parâmetro que representa o para um iterador assíncrono CancellationToken (§15.15). O argumento a favor deste parâmetro deve ser combinado com o argumento transmitido a IAsyncEnumerable<T>.GetAsyncEnumerator(CancellationToken). Este token combinado deve ser pesquisado por IAsyncEnumerator<T>.MoveNextAsync() (§15.15.5.2). As fichas devem ser combinadas num único símbolo como se fossem da CancellationToken.CreateLinkedTokenSource sua Token propriedade. O token combinado será cancelado se qualquer um dos dois tokens de origem for cancelado. O token combinado é visto como o argumento para o método iterador assíncrono (§15.15) no corpo desse método.
É um erro se o EnumeratorCancellationAttribute atributo for aplicado a mais de um parâmetro. O compilador pode produzir um aviso se:
-
EnumeratorCancellationAttributeé aplicado a um parâmetro de um tipo diferente deCancellationToken, - ou se
EnumeratorCancellationAttributefor aplicado a um parâmetro num método que não é um iterador assíncrono (§15.15), - ou se
EnumeratorCancellationAttributefor aplicado a um parâmetro num método que devolve uma interface enumeradora assíncrona (§15.15.2) em vez de uma interface enumerável assíncrona (§15.15.3).
O iterador não terá acesso ao CancellationToken argumento de GetAsyncEnumerator quando nenhum atributo possui este parâmetro.
Exemplo: O método
GetStringsAsync()é um iterador assíncrono. Antes de fazer qualquer trabalho para recuperar o próximo valor, ele verifica o token de cancelamento para determinar se a iteração deve ser cancelada. Se o cancelamento for solicitado, nenhuma outra ação será tomada.public static async Task ExampleCombination() { var sourceOne = new CancellationTokenSource(); var sourceTwo = new CancellationTokenSource(); await using (IAsyncEnumerator<string> enumerator = GetStringsAsync(sourceOne.Token).GetAsyncEnumerator(sourceTwo.Token)) { while (await enumerator.MoveNextAsync()) { string number = enumerator.Current; if (number == "8") sourceOne.Cancel(); if (number == "5") sourceTwo.Cancel(); Console.WriteLine(number); } } } static async IAsyncEnumerable<string> GetStringsAsync( [EnumeratorCancellation] CancellationToken token) { for (int i = 0; i < 10; i++) { if (token.IsCancellationRequested) yield break; await Task.Delay(1000, token); yield return i.ToString(); } }Exemplo final
23.5.11 O atributo ModuleInitializer
O atributo ModuleInitializerAttribute é usado para marcar um método como inicializador de módulo. Tal método é chamado durante a inicialização do módulo que contém. Um módulo pode ter múltiplos inicializadores, que são chamados numa ordem definida pela implementação.
Não existem limitações quanto ao código permitido num inicializador de módulo.
Um inicializador de módulo deve ter as seguintes características:
- O method_modifier
static. - Sem parameter_list.
- Uma return_type de
void. - Sem type_parameter_list.
- Não ser declarado numa class_declaration ter uma type_parameter_list.
- Ser acessível a partir do módulo que contém (ou seja, ter um modificador
internalde acesso oupublic). - Não ser uma função local.
23.5.11.1 Manipuladores personalizados de expressões de strings interpoladas
23.5.11.1.1 Declarar um manipulador personalizado
Considere o seguinte programa, que implementa um registo de mensagens simples:
using System;
public class Logger
{
public void LogMessage(string msg)
{
Console.WriteLine(msg);
}
}
public class Program
{
static void Main()
{
var logger = new Logger();
int val = 255;
logger.LogMessage($"val = {{{val,4:X}}}; 2 * val = {2 * val}.");
}
}
O resultado produzido é, o seguinte:
val = { FF}; 2 * val = 510.
Na chamada para LogMessage, o alvo do argumento de expressão de cadeia interpolada é o parâmetro msg, que tem tipo string. Como descrito no §12.8.3, o compilador pode usar o handler de string interpolado por defeito quando este está disponível e o contexto o suporta. O exemplo seguinte mostra como usar um handler personalizado.
Para fornecer processamento personalizado ao programa acima, é necessário um manipulador de expressões de strings interpolado personalizado . Aqui está o registador de mensagens com um handler personalizado adicionado, ilustrando uma possível implementação:
using System;
using System.Text;
using System.Runtime.CompilerServices;
[InterpolatedStringHandler]
public ref struct LogInterpolatedStringHandler
{
StringBuilder builder; // Storage for the built-up string
public LogInterpolatedStringHandler(int literalLength, int formattedCount)
{
builder = new StringBuilder(literalLength);
}
public void AppendLiteral(string s)
{
builder.Append(s);
}
public void AppendFormatted<T>(T t)
{
builder.Append(t?.ToString());
}
public void AppendFormatted<T>(T t, string format) where T : IFormattable
{
builder.Append(t?.ToString(format, null));
}
public void AppendFormatted<T>(T t, int alignment)
{
builder.Append(String.Format("{0," + alignment + "}", t));
}
public void AppendFormatted<T>(T t, int alignment, string format)
where T : IFormattable
{
builder.Append(String.Format("{0" + "," + alignment + ":" + format + "}", t));
}
public override string ToString() => builder.ToString();
}
public class Logger
{
public void LogMessage(string msg)
{
Console.WriteLine(msg);
}
public void LogMessage(LogInterpolatedStringHandler builder)
{
Console.WriteLine(builder.ToString());
}
}
public class Program
{
static void Main()
{
var logger = new Logger();
int val = 255;
logger.LogMessage($"val = {{{val,4:X}}}; 2 * val = {2 * val}.");
}
}
O resultado produzido é, o seguinte:
val = { FF}; 2 * val = 510.
Diz-se que um tipo com o atributo InterpolatedStringHandlerAttribute é um tipo de handler de string interpolado aplicável.
Uma conversão implícita interpolada de handler de string (§10.2.5) para uma classe ou tipo T de struct é atribuída da seguinte forma. A presença do atributo estabelece a aplicabilidade da conversão; a validação do método construtor e do método de adição é realizada após a resolução de sobrecarga selecionar a conversão.
A lista de argumentos do construtor consiste em:
- Duas
intconstantes: a soma dos comprimentos dos segmentos literais e o número de interpolações na interpolated_string_handler_expression (§12.8.3). Os comprimentos literais são calculados após a decodificação de escapes, incluindo a substituição{{e}}com braçadeiras simples. Para$"val = {{{val,4:X}}}; 2 * val = {2 * val}.", estes valores são 21 e 2, respetivamente. - Quaisquer argumentos adicionais especificados por
InterpolatedStringHandlerArgumentAttribute, na ordem especificada (§23.5.11.1.3). - Um argumento final
outdo tipobool.
A ligação de construtores é realizada usando T esta lista de argumentos e as regras normais para criação de objetos (§12.8.17.2), incluindo resolução de sobrecarga, acessibilidade e validação final. Se esta ligação falhar, incluindo porque é ambígua, a ligação é novamente tentada sem o argumento final out bool . É um erro em tempo de compilação se nenhuma das tentativas selecionar um construtor válido.
Exemplo: A ambiguidade entre construtores que aceitam o
out boolargumento não impede a seleção de um construtor sem esse argumento:Handler handler = $""; [System.Runtime.CompilerServices.InterpolatedStringHandler] struct Handler { public Handler(int literalLength, int formattedCount) => Console.WriteLine("ungated"); public Handler(int literalLength, int formattedCount, out bool enabled, int optional = 0) { enabled = true; } public Handler(int literalLength, int formattedCount, out bool enabled, long optional = 0) { enabled = true; } }Exemplo final
Os métodos de append são resolvidos apenas para componentes presentes no interpolated_string_handler_expression:
- Para cada segmento literal não vazio, uma invocação de
AppendLiteralé resolvida com um argumento de valor do tipostring. - Para cada interpolação, uma invocação de
AppendFormattedé resolvida. O seu primeiro argumento é a expressão da interpolação, passada por valor. Se um interpolation_minimum_width estiver presente, o seu valor constante é fornecido como um argumentoalignmentnomeado . Se um especificador de formato estiver presente, o seu texto é fornecido como um argumentoformatnomeado .
A pesquisa de membro e a resolução de sobrecarga utilizam as regras ordinárias para invocação através de uma instância de T (§12.8.10.2). Cada método de anexação selecionado será um método de instância acessível; métodos de extensão não são considerados. Parâmetros opcionais, inferência genérica e conversões de argumentos aplicam-se como habitualmente. Cada método de adição selecionado deverá devolver ou voidbool por valor, e todos os métodos de adição selecionados deverão devolver o mesmo tipo. Um método obrigatório em falta, ambíguo ou inválido é um erro em tempo de compilação.
Nota: Não é necessário adicionar sobrecarga ou
ToStringsobreposição não utilizada. Os métodos de anexação não precisam de ser públicos ou genéricos, e não é necessária nenhuma restrição genérica particular. Um manipulador não precisa de produzir uma corda. Nota final
A avaliação de uma conversão encadenada bem-sucedida procede da seguinte forma:
- Os valores previamente avaliados do recetor e dos argumentos ou localizações de armazenamento são mantidos conforme especificado na §23.5.11.1.3. Componentes anteriores de uma expressão contendo são avaliados primeiro, preservando a sua ordem habitual de avaliação.
- O construtor selecionado é invocado com o comprimento literal, contagem de interpolações, argumentos encaminhados e
out boolargumento, se selecionado. O seu resultado é armazenado num temporário do tipoT. - Se um
out boolargumento foi selecionado e o seu valor éfalse, não é executada nenhuma chamada de append e nenhuma expressão de interpolação é avaliada. - Caso contrário, os componentes são processados por ordem lexical, ao longo de toda a interpolated_string_handler_expression. Cada segmento literal é decodificado e fornecido ao seu método selecionado
AppendLiteral. Cada expressão de interpolação é avaliada, convertida e fornecida com os seus argumentos de alinhamento e formato ao método selecionadoAppendFormatted. Se um método de append devolverfalse, todas as chamadas de append e expressões de interpolação subsequentes são saltadas. - O resultado da conversão é o handler construído, incluindo quaisquer alterações feitas pelas chamadas de append.
A invocação envolvente, se existir, ainda ocorre quando a construção inibe o processamento ou um método de adição devolve false. Argumentos ordinários posteriores continuam a ser avaliados na sua ordem normal. Não existe uma eliminação implícita do manipulador.
A conversão de handler não invoca ToString implicitamente nem exige que um handler produza uma cadeia. A preferência entre uma sobrecarga de handler e uma sobrecarga de string está especificada no §12.6.4.5.
Exemplo: Um handler pode usar métodos append não genéricos, não públicos, que retornam bools, sem sobrescrever
ToString. Também pode ser transmitido por referência sem um argumento explícitoref:class Program { static int Hole() { Console.WriteLine("hole"); return 1; } static void Write(ref Handler handler, params int[] values) => Console.WriteLine("body:" + values.Length); static void Main() { Write(($"prefix{Hole()}" + ($"{Hole()}"!)), 1, 2); Write($"{Hole(),4:X}", new[] { 1 }); } } [System.Runtime.CompilerServices.InterpolatedStringHandler] struct Handler { internal Handler(int literalLength, int formattedCount) => Console.WriteLine($"construct:{literalLength}:{formattedCount}"); internal bool AppendLiteral(string text) { Console.WriteLine("literal:" + text); return false; } internal bool AppendFormatted(int value, int alignment = 0, string format = null) { Console.WriteLine($"formatted:{value}:{alignment}:{format}"); return false; } }O primeiro anexo literal suprime ambos os buracos na primeira invocação. A segunda invocação avalia o seu primeiro buraco e passa o alinhamento e o formato pelo nome. Ambas as invocações executam
Write.Exemplo final
23.5.11.1.2 Inibição de um manipulador personalizado
Se a resolução do construtor selecionar um construtor com um out bool argumento, o valor desse argumento é testado após a construção. Se for true, inicia-se o processamento de componentes. Se for false, o manipulador é inibido: não é avaliada a expressão de interpolação e não é chamado método de adição. Este teste é separado do curto-circuito realizado após cada chamada append que retorna bools.
public LogInterpolatedStringHandler(int literalLength, int formattedCount,
out bool processString)
{
if (some_condition)
{
processString = false;
return;
}
else
{
processString = true;
// continue construction
}
}
Nota: Expressões de interpolação podem conter efeitos secundários, por exemplo de
++,--, atribuições e chamadas de método. A inibição do construtor ignora todas essas expressões. Um falso resultado de adição ignora apenas as expressões restantes. A atribuição definida tem em conta estes caminhos condicionais (§9.4.4.23). Nota final
23.5.11.1.3 Passar informação para/de um manipulador personalizado
Pode ser útil passar outra informação para o handler personalizado e receber informação de volta. Isto é feito através do atributo InterpolatedStringHandlerArgument. Considere as seguintes novas sobrecargas no programa de registo de mensagens:
public class Logger
{
// …
public void LogMessage(bool flag, int count,
[InterpolatedStringHandlerArgument("count","flag","")]
LogInterpolatedStringHandler builder)
{
// …
}
}
public ref struct LogInterpolatedStringHandler
{
// …
public LogInterpolatedStringHandler(int literalLength, int formattedCount,
int count, bool flag, Logger logger)
{
// …
}
}
InterpolatedStringHandlerArgumentAttribute é aplicado ao parâmetro handler. Os seus argumentos especificam uma lista ordenada de nomes de parâmetros para encaminhar para o construtor handler. Uma lista vazia não encaminha nada. Uma cadeia vazia designa o recetor da invocação que contém.
Cada nome não vazio deve identificar outro parâmetro do membro que o contém. Um nome desconhecido, o nome próprio do parâmetro do handler, ou um pedido para um recetor indisponível, incluindo o de um método estático, é um erro em tempo de compilação. Uma declaração pode produzir um aviso se um parâmetro nomeado for declarado após o parâmetro handler; isto não torna a declaração inválida.
Ao utilizar a conversão do handler, cada argumento encaminhado deve ocorrer lexicamente antes do interpolated_string_handler_expression na lista de argumentos da invocação. Um argumento encaminhado não pode ser omitido e fornecido pelo valor padrão de um parâmetro. Estes requisitos dependem da ordem do local da chamada, não da ordem da declaração; argumentos nomeados podem, portanto, tornar uma declaração avisada utilizável. Um pedido para encaminhar um recetor indexador quando este é um initializer_target numa member_initializer é um erro em tempo de compilação.
A resolução de sobrecarga de construtores utiliza os tipos de parâmetros do elemento que o contém após a substituição dos seus argumentos de tipos, e não as expressões originais do argumento. Os argumentos encaminhados mantêm os seus modos de passagem de parâmetros. Em tempo de execução, o recetor já avaliado e os valores de argumento já convertidos ou as localizações de armazenamento avaliadas são reutilizados pela construção do handler e pela invocação contendora, preservando a semântica de referência. São aplicadas conversões adicionais necessárias pelo construtor a estes valores mantidos; as expressões originais não são avaliadas nem limitadas novamente.
Nota: Em particular, um lambda encaminhado não está independentemente ligado a um tipo de delegado diferente para o construtor. Os tipos de parâmetros do construtor handler não contribuem para a inferência genérica para a invocação que contém. A análise anulável dos argumentos do construtor não faz as alterações fluídas de volta para os slots originais do recetor ou argumento. Nota final
23.5.12 Atributos obrigatórios dos membros
23.5.12.1 O atributo SetsRequiredMembers
Este atributo indica que o construtor que decora define todos os membros necessários para o tipo atual, pelo que os invocadores não precisam de definir quaisquer membros necessários eles próprios. No entanto, o compilador não verifica se o construtor inicializa realmente todos os membros necessários.
Exemplo:
public class Person { public Person() { } [SetsRequiredMembers] public Person(string firstName, string lastName) => (FirstName, LastName) = (firstName, lastName); public required string FirstName { get; init; } public required string LastName { get; init; } public int? Age { get; set; } } public class Student : Person { public Student() : base() { } [SetsRequiredMembers] public Student(string firstName, string lastName) : base(firstName, lastName) { } public double GPA { get; set; } } public class Test { public static void M() { var p1 = new Student(); // error: doesn't set required members var p2 = new Student("Jane", "Williams"); // OK } }Exemplo final
Nota: Como o construtor
Student(string, string)do tipo derivado se encadeia ao construtorPerson(string, string)do tipo base , que tem este atributo, o construtor do tipo derivado também deve ter esse atributo (§15.11.1). Nota final
23.5.12.2 O atributo Membro Obrigatório
Este atributo indica que o tipo atual tem um ou mais membros necessários (§15.7.1), ou que é necessário um membro específico desse tipo. No entanto, é um erro que este atributo seja usado explicitamente. Em vez disso, a presença do modificador required faz com que o tipo ou membro seja tratado como se estivesse decorado com este atributo.
23.5.13 O atributo CollectionBuilder
Este atributo designa um tipo de coleção como tendo um método de criação de coleção (§15.17.1).
O construtor assume um tipo construtor e o nome do método a invocar para construir uma instância do tipo de coleção.
O atributo pode ser aplicado a uma classe, struct, ref struct ou interface. O atributo não é herdado, embora possa ser aplicado a uma classe base ou a uma classe abstrata.
O tipo de construtor deve ser uma classe ou struct não genérico.
23.5.14 O atributo InlineArray
Este atributo é usado para identificar uma estrutura não-registo como um tipo de array inline. Para mais informações e exemplos da sua utilização, ver §16.6.
23.5.15 O atributo OverloadResolutionPriority
O atributo OverloadResolutionPriority é usado para especificar a prioridade de um membro durante a resolução de sobrecarga, como int argumento para o construtor. A ausência deste atributo é equivalente à sua presença com um argumento de 0. Quanto maior o número, maior a prioridade. Todas as sobrecargas com prioridade inferior à prioridade de sobrecarga mais alta são removidas do conjunto de correspondências aplicáveis.
Um autor de biblioteca pode usar este atributo para garantir que uma nova sobrecarga melhor é preferida em vez de uma existente, para reduzir a alocação de memória, por exemplo. Este atributo informa o compilador qual a sobrecarga que deve ser preferida.
Exemplo: Considere o seguinte:
class Program { static void Main() { var c = new C(); int[] arr = [1, 2, 3]; c.M(arr); // Prints "Span" } } class C { [OverloadResolutionPriority(1)] public void M(params ReadOnlySpan<int> s) => Console.WriteLine("Span"); public void M(params int[] a) => Console.WriteLine("Array"); }O segundo método tem uma prioridade implícita de zero e, na ausência do atributo explícito, a segunda das sobrecargas seria invocada. No entanto, com o atributo presente, o primeiro é invocado em vez disso.
Certos usos deste atributo podem tornar um membro impossível de chamar, da seguinte forma:
class Program { static void Main() { var c = new C(); c.M1(1); // Calls C3.M1(long), not M1(int) c.M2(1); // Calls C3.M2(int, string), not M2(int) c.M3("abc"); // Calls C3.M3(object), not M3(string) } } class C { public void M1(int i) { } [OverloadResolutionPriority(1)] public void M1(long l) { } [Conditional("DEBUG")] public void M2(int i) { } [OverloadResolutionPriority(1), Conditional("DEBUG")] public void M2(int i, [CallerArgumentExpression(nameof(i))] string s = "") { } public void M3(string s) { } [OverloadResolutionPriority(1)] public void M3(object o) { } }Exemplo final
23.6 Atributos para interoperação
Para interoperação com outros idiomas, um indexador pode ser implementado usando propriedades indexadas. Se o indexador não estiver decorado com IndexerNameAttribute, então o nome Item é usado por defeito.
IndexerNameAttribute permite ao programador sobrepor este padrão e especificar um nome diferente.
Exemplo: Por defeito, o nome de um indexador é
Item. Isso pode ser substituído, da seguinte forma:[System.Runtime.CompilerServices.IndexerName("TheItem")] public int this[int index] { get { ... } set { ... } }Agora, o nome do indexador é
TheItem.Exemplo final
ECMA C# draft specification