docs/ecma334/8.14.xml

   1 <?xml version="1.0"?>
   2 <clause number="8.14" title="Attributes" informative="true">
   3   <paragraph>C# is an imperative language, but like all imperative languages it does have some declarative elements. For example, the accessibility of a method in a class is specified by declaring it public, protected, internal, protected internal, or private. C# generalizes this capability, so that programmers can invent new kinds of declarative information, attach this declarative information to various program entities, and retrieve this declarative information at run-time. Programs specify this additional declarative information by defining and using attributes (<hyperlink>24</hyperlink>). </paragraph>
   4   <paragraph>For instance, a framework might define a HelpAttribute attribute that can be placed on program elements such as classes and methods, enabling developers to provide a mapping from program elements to documentation for them. The example <code_example><![CDATA[
   5 using System;
   6 [AttributeUsage(AttributeTargets.All)]
   7 public class HelpAttribute: Attribute
   8 {
   9    public HelpAttribute(string url) {
  10       this.url = url;
  11    }
  12    public string Topic = null;
  13    private string url;
  14    public string Url {
  15       get { return url; }
  16    }
  17 }
  18 ]]></code_example>defines an attribute class named HelpAttribute, or Help for short, that has one positional parameter (string url) and one named parameter (string Topic). Positional parameters are defined by the formal parameters for public instance constructors of the attribute class, and named parameters are defined by public non-static read-write fields and properties of the attribute class. </paragraph>
  19   <paragraph>The example <code_example><![CDATA[
  20 [Help("http://www.mycompany.com/.../Class1.htm")]
  21 public class Class1
  22 {
  23    [Help("http://www.mycompany.com/.../Class1.htm", Topic = "F")]
  24    public void F() {}
  25 }
  26 ]]></code_example>shows several uses of the attribute Help. </paragraph>
  27   <paragraph>Attribute information for a given program element can be retrieved at run-time by using reflection support. The example <code_example><![CDATA[
  28 using System;
  29 class Test
  30 {
  31    static void Main() {
  32       Type type = typeof(Class1);
  33       object[] arr = type.GetCustomAttributes(typeof(HelpAttribute),
  34       true);
  35       if (arr.Length == 0)
  36       Console.WriteLine("Class1 has no Help attribute.");
  37       else {
  38          HelpAttribute ha = (HelpAttribute) arr[0];
  39          Console.WriteLine("Url = {0}, Topic = {1}", ha.Url, ha.Topic);
  40       }
  41    }
  42 }
  43 ]]></code_example>checks to see if Class1 has a Help attribute, and writes out the associated Topic and Url values if the attribute is present. </paragraph>
  44   <paragraph>End of informative text. </paragraph>
  45 </clause>