Some attributes are supplied as part of the CLR, some by the . NET Framework class libraries, and some by other libraries. In addition, you are free to define custom attributes for your own purposes.

Most programmers will use only the attributes provided by existing libraries, though creating your own custom attributes can be a powerful tool when combined with reflection, as described later in this chapter.

[assembly: AssemblyDelaySign(false)]
[assembly: AssemblyKeyFile(".\keyFile.snk")]

[assembly: AssemblyDelaySign(false),
 assembly: AssemblyKeyFile(".\keyFile.snk")]

You are free to create your own custom attributes and use them at runtime as you see fit. Suppose, for example, that your development organization wants to keep track of bug fixes. You already keep a database of all your bugs, but you’d like to tie your bug reports to specific fixes in the code.

You might add comments to your code along the lines of:

// Bug 323 fixed by Jesse Liberty 1/1/2010.

This would make it easy to see in your source code, but since comments get stripped out at compile time this information won’t make it into the compiled code. If we wanted to change that, we could use a custom attribute. We would replace the comment with something like this:

[BugFixAttribute(323, "Jesse Liberty", "1/1/2010",
                 Comment="Off by one error")]

You could then write a program to read through the metadata to find these bug-fix annotations, and perhaps it might go on to update a bug database. The attribute would serve the purposes of a comment, but would also allow you to retrieve the information programmatically through tools you’d create.

public class BugFixAttribute : System.Attribute

[AttributeUsage(AttributeTargets.Class |
    AttributeTargets.Constructor |
    AttributeTargets.Field |
    AttributeTargets.Method |
    AttributeTargets.Property,
    AllowMultiple = true)]

[BugFix(123, "Jesse Liberty", "01/01/08", Comment="Off by one")]

public BugFixAttribute(int bugID, string programmer,
string date)
{
    this.BugID = bugID;
    this.Programmer = programmer;
    this.Date = date;
}

public string Comment    { get; set; }

public int BugID    { get; private set; }

[BugFixAttribute(121,"Jesse Liberty","01/03/08")]
[BugFixAttribute(107,"Jesse Liberty","01/04/08",
                 Comment="Fixed off by one errors")]
public class MyMath

using System;

namespace CustomAttributes
{
    // create custom attribute to be assigned to class members
    [AttributeUsage(AttributeTargets.Class |
                    AttributeTargets.Constructor |
                    AttributeTargets.Field |
                    AttributeTargets.Method |
                    AttributeTargets.Property,
                    AllowMultiple = true)]
    public class BugFixAttribute : System.Attribute
    {
        // attribute constructor for positional parameters
        public BugFixAttribute
        (
            int bugID,
            string programmer,
            string date
        )
        {
            this.BugID = bugID;
            this.Programmer = programmer;
            this.Date = date;
        }

        // accessors
        public int BugID { get; private set; }
        public string Date { get; private set; }
        public string Programmer { get; private set; }

        // property for named parameter
        public string Comment { get; set; }
    }

    // ********* assign the attributes to the class ********

    [BugFixAttribute(121, "Jesse Liberty", "01/03/08")]
    [BugFixAttribute(107, "Jesse Liberty", "01/04/08",
                        Comment = "Fixed off by one errors")]
    public class MyMath
    {
        public double DoFunc1(double param1)
        {
            return param1 + DoFunc2(param1);
        }

        public double DoFunc2(double param1)
        {
            return param1 / 3;
        }
    }

    public class Tester
    {
        static void Main(string[] args)
        {
            MyMath mm = new MyMath();
            Console.WriteLine("Calling DoFunc(7). Result: {0}",
            mm.DoFunc1(7));
        }
    }
}

Output:
Calling DoFunc(7). Result: 9.3333333333333333

In this section, we will use the C# reflection support to read the metadata in the MyMath class.

The reflection system defines numerous classes, each designed to provide information about a particular kind of metadata. For example, the ConstructorInfo provides access to all the metadata for a constructor, while PropertyInfo gives us the metadata for a property. Our custom attribute in Example 17-1 can be applied to a wide range of targets, so we’re going to encounter several different metadata types. However, all of our supported targets have something in common—they are all things that can be members of classes. (That’s plainly true for properties, methods, fields, and constructors. Our attribute can also be applied to classes, which seems like an exception because they’re often not members of other types, but the point is that they can be.) And so, the metadata types for all our supported target types derive from a common base class, MemberInfo.

MemberInfo is defined in the System.Reflection namespace. We can use it to discover the attributes of a member and to provide access to the metadata. We’ll start by getting hold of the metadata for a particular type:

System.Reflection.MemberInfo inf = typeof(MyMath);

We’re using the typeof operator on the MyMath type, which returns an object of type Type, which derives from MemberInfo.

The next step is to call GetCustomAttributes on this MemberInfo object, passing in the type of the attribute we want to find. It returns an array of objects, each of type BugFixAttribute:

object[] attributes;
attributes =
    inf.GetCustomAttributes(typeof(BugFixAttribute),false);

You can now iterate through this array, printing out the properties of the BugFixAttribute object. Example 17-2 replaces the Main method in the Tester class from Example 17-1.

public static void Main(string[] args)
{
    MyMath mm = new MyMath();
    Console.WriteLine("Calling DoFunc(7). Result: {0}",
                      mm.DoFunc1(7));

    // get the member information and use it to
    // retrieve the custom attributes
    System.Reflection.MemberInfo inf = typeof(MyMath);
    object[] attributes;
    attributes = inf.GetCustomAttributes(
                     typeof(BugFixAttribute), false);

    // iterate through the attributes, retrieving the
    // properties
    foreach (Object attribute in attributes)
    {
        BugFixAttribute bfa = (BugFixAttribute)attribute;
        Console.WriteLine("
BugID: {0}", bfa.BugID);
        Console.WriteLine("Programmer: {0}", bfa.Programmer);
        Console.WriteLine("Date: {0}", bfa.Date);
        Console.WriteLine("Comment: {0}", bfa.Comment);
    }
}

Output:
Calling DoFunc(7). Result: 9.3333333333333333

BugID: 121
Programmer: Jesse Liberty
Date: 01/03/08
Comment:

BugID: 107
Programmer: Jesse Liberty
Date: 01/04/08
Comment: Fixed off by one errors

When you put this replacement code into Example 17-1 and run it, you can see the metadata printed as you’d expect.

You can use reflection to explore and examine the contents of an assembly. You can find the types it contains. You can discover the methods, fields, properties, and events associated with a type, as well as the signatures of each of the type’s methods. You can also discover the interfaces supported by the type, and the type’s base class.

If we were using this to support a plug-in system for extending our application, we’d need to load at runtime assemblies we didn’t know about when we wrote our application. We can load an assembly dynamically with the Assembly.Load() static method. The Assembly class encapsulates the actual assembly itself, for purposes of reflection. One signature for the Load method is:

public static Assembly Load(string assemblyName)

For example, Mscorlib.dll has the core classes of the .NET Framework, so we can pass that to the Load() method:

Assembly a = Assembly.Load("Mscorlib");

(In fact Mscorlib.dll will already be loaded, but this method doesn’t mind—it returns the assembly we asked for, loading it first if necessary.) There’s also a LoadFrom method that takes a file path. Once the assembly is loaded, we can call GetTypes() to return an array of Type objects. A Type object represents a specific type declaration, such as a class, interface, array, struct, delegate, or enumeration:

Type[] types = a.GetTypes();

The assembly returns an array of types that we can display in a foreach loop, as shown in Example 17-3. Because this example uses the Type class, you will want to add a using directive for the System.Reflection namespace.

using System;
using System.Reflection;

namespace ReflectingAnAssembly
{
    public class Tester
    {
        public static void Main()
        {
            // what is in the assembly
            Assembly a = Assembly.Load("Mscorlib");
            Type[] types = a.GetTypes();
            foreach (Type t in types)
            {
                Console.WriteLine("Type is {0}", t);
            }
            Console.WriteLine(
                "{0} types found", types.Length);
        }
    }
}

The output from this would fill many pages. Here is a short excerpt:

Type is System.Object
Type is ThisAssembly
Type is AssemblyRef
Type is System.ICloneable
Type is System.Collections.IEnumerable
Type is System.Collections.ICollection
Type is System.Collections.IList
Type is System.Array

This example obtained an array filled with the types from the core library and printed them one by one. The array contained 2,779 entries when run against .NET version 4.0.

Instead of iterating through all the types, you can ask the reflection system for a single specific one. This may seem odd—if you already know what type you want, why would you need to use reflection to find things out about it at runtime? In fact, this can be useful for several reasons—some applications let users put the name of a type in a configuration file, so the program only discovers the name of the type it requires at runtime, and wants to look up just that one type. To do so, you extract a type from the assembly with the GetType() method, as shown in Example 17-4.

using System;
using System.Reflection;

namespace ReflectingOnAType
{
    public class Tester
    {
        public static void Main()
        {
            // examine a single type
            Assembly a = Assembly.Load("Mscorlib");
            Type theType = a.GetType("System.Reflection.Assembly");
            Console.WriteLine("
Single Type is {0}
", theType);
        }
    }
}

Output:
Single Type is System.Reflection.Assembly

It can sometimes be useful to get hold of the Type object for a specific type known to you at compile time. This may seem odd, for the reasons described earlier, but the usual reason for doing this is not so that you can learn more about the type. You may need to do it to compare one type object with another. For example, if we wanted to find all of the types in mscorlib that derive from the MemberInfo class, we would need to get hold of the Type object for MemberInfo. Example 17-5 does this.

using System;
using System.Linq;
using System.Reflection;

namespace UsingASpecificType
{
    public class Tester
    {
        public static void Main()
        {
            // examine a single type
            Assembly a = Assembly.Load("Mscorlib");

            var matchingTypes = from t in a.GetTypes()
                                where typeof(MemberInfo).IsAssignableFrom(t)
                                select t;

            foreach (Type t in matchingTypes)
            {
                Console.WriteLine(t);
            }
        }
    }
}

This uses a LINQ query to find the matching types. It illustrates one of the things you can do with a Type object—its IsAssignableFrom method tells you whether it’s possible to assign an instance of one type into a field or variable of another type. So this code looks at every type, and asks whether it can be assigned into a variable of type MemberInfo. (This casts the net slightly wider than merely looking at the base class—this query will find all types that derive either directly or indirectly from MemberInfo.) Since we know exactly what target type we’re interested in, we use the C# typeof operator to get the Type object for that exact type.

using System;
using System.Reflection;

namespace ReflectingOnMembersOfAType
{
    public class Tester
    {
        public static void Main()
        {
            // examine a single type
            Assembly a = Assembly.Load("Mscorlib");
            Type theType = a.GetType("System.Reflection.Assembly");
            Console.WriteLine("
Single Type is {0}
", theType);

            // get all the members
            MemberInfo[] mbrInfoArray = theType.GetMembers();
            foreach (MemberInfo mbrInfo in mbrInfoArray)
            {
                Console.WriteLine("{0} is a {1}",
                        mbrInfo, mbrInfo.MemberType);
            }
        }
    }
}

System.Type GetType(System.String, Boolean, Boolean) is a Method
System.Type[] GetExportedTypes() is a Method
System.Reflection.Module GetModule(System.String) is a Method
System.String get_FullName() is a Method

MemberInfo[] mbrInfoArray =
    theType.GetMembers();

mbrInfoArray = theType.GetMethods();

Output (excerpt):
Boolean Equals(System.Object) is a Method
System.String ToString() is a Method
System.String CreateQualifiedName(
System.String, System.String) is a Method
Boolean get_GlobalAssemblyCache() is a Method

Once you find a method, you can invoke it using reflection. For example, you might like to invoke the Cos() method of System.Math, which returns the cosine of an angle.

To invoke Cos(), first get the Type information for the System.Math class:

Type theMathType = typeof(System.Math);

Once we have type information, we could dynamically create an instance of the type using a static method of the Activator class. However, we don’t need to here because Cos() is static. In fact, all members of System.Math are static, and even if you wanted to create an instance, you can’t because System.Math has no public constructor. However, since you will come across types that need to be instantiated so that you can call their nonstatic members, it’s important to know how to create new objects with reflection.

The Activator class contains three methods, all static, which you can use to create objects. The methods are as follows:

Back to the Cos() example. Our theMathType variable now refers to a Type object which we obtained by calling GetType.

Before we can invoke a method on the type, we must get the method we need from the Type object. To do so, we call GetMethod(), passing the method name:

MethodInfo cosineInfo =
 theMathType.GetMethod("Cos");

You now have an object of type MethodInfo which provides an Invoke method that calls the method this MethodInfo represents. Normally, the first argument to Invoke would be the object on which we want to invoke the method. However, because this is a static method, there is no object, so we just pass null. And then we pass the arguments for the function. Invoke is capable of calling any method, regardless of how many arguments it has, so it expects the arguments to be wrapped in an array, even if there’s only one:

Object[] parameters = new Object[1];
parameters[0] = 45 * (Math.PI/180); // 45 degrees in radians
Object returnVal = cosineInfo.Invoke(null, parameters);

Example 17-7 shows all the steps required to call the Cos() method dynamically.

using System;
using System.Reflection;

namespace DynamicallyInvokingAMethod
{
    public class Tester
    {
        public static void Main()
        {
            Type theMathType = Type.GetType("System.Math");
            // Since System.Math has no public constructor, this
            // would throw an exception.
            // Object theObj =
            //     Activator.CreateInstance(theMathType);

            // array with one member
            Type[] paramTypes = new Type[1];
            paramTypes[0] = Type.GetType("System.Double");

            // Get method info for Cos()
            MethodInfo CosineInfo =
                theMathType.GetMethod("Cos", paramTypes);

            // fill an array with the actual parameters
            Object[] parameters = new Object[1];
            parameters[0] = 45 * (Math.PI / 180); // 45 degrees in radians
            Object returnVal =
                CosineInfo.Invoke(theMathType, parameters);
            Console.WriteLine(
                "The cosine of a 45 degree angle {0}",
                returnVal);
        }
    }
}

Output:
The cosine of a 45 degree angle 0.707106781186548

That was a lot of work just to invoke a single method. The power, however, is that you can use reflection to discover an assembly on the user’s machine, to query what methods are available, and to invoke one of those members dynamically. Chapter 18 will show how you can use the dynamic keyword to automate this for certain scenarios.