docs/ecma334/24.1.1.xml

   1 <?xml version="1.0"?>
   2 <clause number="24.1.1" title="Attribute usage">
   3   <paragraph>The attribute AttributeUsage (<hyperlink>24.4.1</hyperlink>) is used to describe how an attribute class can be used. </paragraph>
   4   <paragraph>AttributeUsage has a positional parameter (<hyperlink>24.1.2</hyperlink>) that enables an attribute class to specify the kinds of declarations on which it can be used. <example>[Example: The example <code_example><![CDATA[
   5 using System;
   6 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface)]
   7 public class SimpleAttribute: Attribute
   8 {}
   9 ]]></code_example>defines an attribute class named SimpleAttribute that can be placed on <non_terminal where="17.1">class-declaration</non_terminal>s and  <non_terminal where="20.1">interface-declaration</non_terminal>s only. The example <code_example><![CDATA[
  10 [Simple] class Class1 {...}
  11 [Simple] interface Interface1 {...}
  12 ]]></code_example>shows several uses of the Simple attribute. Although this attribute is defined with the name SimpleAttribute, when this attribute is used, the Attribute suffix may be omitted, resulting in the <keyword>short</keyword> name Simple. Thus, the example above is semantically equivalent to the following <code_example><![CDATA[
  13 [SimpleAttribute] class Class1 {...}
  14 [SimpleAttribute] interface Interface1 {...}
  15 ]]></code_example>end example]</example> </paragraph>
  16   <paragraph>AttributeUsage has a named parameter (<hyperlink>24.1.2</hyperlink>), called AllowMultiple, which indicates whether the attribute can be specified more than once for a given entity. If AllowMultiple for an attribute class is true, then that class is a multi-use attribute class, and can be specified more than once on an entity. If AllowMultiple for an attribute class is false or it is unspecified, then that class is a single-use attribute class, and can be specified at most once on an entity. </paragraph>
  17   <paragraph>
  18     <example>[Example: The example <code_example><![CDATA[
  19 using System;
  20 [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
  21 public class AuthorAttribute: Attribute {
  22    public AuthorAttribute(string name) {
  23       this.name = name;
  24    }
  25    public string Name { get { return name;} }
  26    private string name;
  27 }
  28 ]]></code_example>defines a multi-use attribute class named AuthorAttribute. The example <code_example><![CDATA[
  29 [Author("Brian Kernighan"), Author("Dennis Ritchie")]
  30 class Class1 {...}
  31 ]]></code_example>shows a class declaration with two uses of the Author attribute. end example]</example>
  32   </paragraph>
  33   <paragraph>AttributeUsage has another named parameter (<hyperlink>24.1.2</hyperlink>), called Inherited, which indicates whether the attribute, when specified on a base class, is also inherited by classes that derive from that base class. If Inherited for an attribute class is true, then that attribute is inherited. If Inherited for an attribute class is false or it is unspecified, then that attribute is not inherited. </paragraph>
  34   <paragraph>An attribute class X not having an AttributeUsage attribute attached to it, as in <code_example><![CDATA[
  35 using System;
  36 class X: Attribute { ... }
  37 ]]></code_example>is equivalent to the following: <code_example><![CDATA[
  38 using System;
  39 [AttributeUsage(AttributeTargets.All, AllowMultiple = false, Inherited =
  40 true)]
  41 class X: Attribute { ... }
  42 ]]></code_example></paragraph>
  43 </clause>