Start Microsoft Visual Studio 2012 and create a new CLR Console Application project named Hello.

Add a new managed class to the application.

ref class Hello
{
public:
    static void SayHello()
    {
        Console::WriteLine("Hello, world");
    }
};

The class doesn’t really have to do anything particular; it is simply here so that you can disassemble it to look at the metadata.

Build the application to generate the executable.

Run ILDASM. To do so, on the Tools menu, click Visual Studio Command Prompt, and then type ildasm on the command line.

On the ILDASM File menu, click Open, navigate to the Hello.exe executable, and then open it.

A window opens that should look similar to the following:

We’re interested in the managed type Hello, which is indicated by the blue component symbol. Click the plus sign (+) to expand the tree for Hello and display the details of the class, as depicted in the following screen shot:

The type has three entries: the details of the class, and the entries for two methods, which are the SayHello method you added and the default constructor provided by the compiler.

Double-click the red triangle to bring up the class information.

A window similar to the following appears:

Create a new CLR Console Application project named AssemblyAttributes.

Open the AssemblyInfo.cpp file and examine its contents.

Observe that the file contains a number of entries of the following form:

[assembly:AssemblyTitleAttribute("AssemblyAttributes")];

Many of these have empty strings as arguments.

Find the version number attribute and edit it to produce a new version, such as in the following example:

[assembly:AssemblyVersionAttribute("1.1.105.3")];

This number would correspond to version 1.1, build 105, revision 3.

Compile and build the application. If you now look at the assembly by using ILDASM, you can see the version in two places. First, it will show in the pane at the bottom of the ILDASM main window, as demonstrated here:

You can also see it by double-clicking the MANIFEST entry in the main window and scrolling down to the bottom of the data window that opens. The line within the .assembly Assembly Attributes block that begins with .ver is the one that lists the version metadata:

.ver 1:1:105:3

Create a new CLR Console application named UseAttributes.

You’ll add code to this project later on in the exercise.

You create DLLs by using a Class Library project. In Solution Explorer, right-click the solution name. On the shortcut menu that appears, point to Add, and then click New Project.

When the Add New Project dialog box appears, select Class Library, call the project MyDll, and then click OK

The MyDll.h file opens in the editor.

Edit the class definition so that it looks like this:

namespace MyDll {

    public ref class TestClass
    {
        int val;
    public:
        TestClass(int n) : val(n) { }

        int getVal() { return val; }

        property int Val {
            int get() { return val; }
        }
    };
}

You can see that in addition to the class having a getter function, it now also has a property that does the same job.

You don’t want to remove the getter function because that might break existing client code, so you mark it as obsolete by using the Obsolete attribute:

[Obsolete("Use the Val property instead", false)]
int getVal() { return val; }

The Obsolete attribute alerts the compiler that this function shouldn’t be used, and the message should be used to inform developers why and what to do instead. The second argument directs the compiler as to whether to treat use of this function as an error or to only issue a warning.

Build the application to ensure that you have no coding errors.

To use the DLL from the console application, you must add a reference to the console project. Open the project properties dialog box for the UseAttributes project by right-clicking the project name (not the solution name!) and then, on the shortcut menu, click Properties. In the dialog box, click Common Properties, and then, in the pane on the left, click Framework And References.

Click the Add New Reference button to open the Add Reference dialog box. In the pane on the left, click the Solution entry. Doing so shows all the projects in the current solution. You should see MyDll listed in the center pane: select the check box adjacent to it, and then click OK twice to dismiss the dialog boxes. If you expand the External Dependencies entry under the UseAttributes project, you should see that it now displays an entry for MyDll.

Open the UseAttributes.cpp source file and add a using directive for the MyDll namespace.

using namespace MyDll;

Edit the main function to create an object and call its obsolete get method, as shown here:

int main(array<System::String ^> ^args)
{
    TestClass ^tc = gcnew TestClass(4);

    int n = tc->getVal();

    return 0;
}

Build the application.

You should see the following warning from the compiler:

UseAttributes.cpp(12): warning C4947: 'MyDll::TestClass::getVal' : marked as obsolete
          Message: 'Use the Val property instead'

Create a new CLR Class Library project named CustomAttributes.

The custom attribute needs to be created as a DLL so that it can be used in other projects.

Open the CustomAttributes.h header file and edit the skeleton class as follows:

namespace CustomAttributes
{
    [AttributeUsageAttribute(AttributeTargets::Method |
                   AttributeTargets::Property)]
    public ref class DocumentationAttribute : Attribute
    {
    };
}

Our class is called DocumentationAttribute and inherits from System::Attribute. The name follows the convention of having the class name for an attribute end with “Attribute.” The class is tagged with an AttributeUsage attribute that limits its use to class methods and properties. Note how you can use more than one member of the AttributeTargets enumeration by combining them with the bitwise OR operator.

The attribute will include three pieces of data: the documentation text (which will be a positional parameter), and author and date strings (which will be optional—and thus implemented as named parameters). Add the declarations for the three members to the class.

namespace CustomAttributes
{
    [AttributeUsageAttribute(AttributeTargets::Method |
                   AttributeTargets::Property)]
    public ref class DocumentationAttribute : Attribute
    {
        String ^text;     // documentation text
        String ^author;   // optional author field
        String ^date;     // optional date field
    };
}

Add the constructor.

public:
    DocumentationAttribute(String ^txt) : text(txt) { }

The constructor takes a string as its only argument, saved away as the documentation text.

Add a read-only property so that users can retrieve the text at run time.

// Read-only property to return the text
property String^ Text {
    String^ get() { return text; }
}

Add read/write properties to allow access to the two named parameters.

// Properties for the positional parameters
property String^ Author
{
    String^ get() { return author; }
    void set(String ^au) { author = au; }
}

property String^ Date
{
    String^ get() { return date; }
    void set(String ^dt) { date = dt; }
}

Choose the names for the properties carefully because these are going to be used in client code when using the attribute.

Build the application to check that you haven’t made any errors.

Add some code that will use the new attribute. In Solution Explorer, right-click the solution name. On the shortcut menu that appears, point to Add, and then select New Project. Ensure that the project type is set to CLR Console Application and call the project TestAtts.

Add an external reference to the CustomAttributes DLL, just as you did in steps 7 and 8 of the previous exercise.

Open the TestAtts.cpp file and add a using namespace line to the top of the file:

using namespace CustomAttributes;

Define a managed class that uses the new custom attribute, as demonstrated here:

// A class to test the attribute
ref class TestAtts
{
    int val;
public:
    [DocumentationAttribute(
      "The TestAtts class constructor takes an integer",
      Author="julian", Date="10/10/01")]
    TestAtts(int v)
    {
        val = v;
    }
    [DocumentationAttribute(
      "The read-only Value property returns the value of"
      " the int class member", Author="julian")]
    property int Value
    {
        int get() { return val; }
    }
};

The Documentation attribute has been attached to the two members of this class. The constructor uses all three possible parameters, whereas the property uses only the text and the Author named parameter.

Build the application to ensure that it compiles cleanly.

You can now use ILDASM to see how the attribute data is held in the class.

Run ILDASM, as described earlier, and open the TestAtts.exe file.

Click the plus sign (+) next to the blue component symbol labeled TestAtts and then double-click the .ctor entry.

This opens the disassembly for the constructor, as shown here:

You can see how the code creates a DocumentationAttribute object, which then forms part of the TestAtts object. You can access this attribute object from code. (You’ll see how to do this in the next section.)

Before leaving this exercise, try adding the Documentation attribute to the class, like this:

[DocumentationAttribute("The TestAtts class", Author="julian")]
ref class TestAtts
{
    ...
}

When you compile this code, the compiler will throw the following error message because the attribute cannot be applied to classes:

TestAtts.cpp(8): error C3115: 'CustomAttribute::DocumentationAttribute': this attribute
is not allowed on 'TestAtts'
          c:usersjuliandocumentssbscustomattributedebugcustomattribute.dll : see
declaration of 'CustomAttribute::DocumentationAttribute'
          attribute can only be applied to: 'member function', 'property'

Continue with the project from the previous exercise.

All classes dealing with reflection reside in the System::Reflection namespace, so add the following using declaration to the others at the top of the source:

using namespace System::Reflection;

You need to create a Type object to use reflection to find out about custom attributes, so add this code to the start of the main function:

int main(array<String^>^ args)
{
    Console::WriteLine("Testing Attributes");

    // Create an object and get its type
    TestAtts ^ta = gcnew TestAtts(3);
    Type ^tt = ta->GetType();

    return 0;
}

You obtain a Type object by using the GetType method that every .NET type inherits from System::Object.

You can check whether there are any custom attributes on a class by using the GetCustom Attributes method on the Type object, like this:

// See if there are any custom attributes on the class
array<Object^> ^atts = tt->GetCustomAttributes(true);
Console::WriteLine("Custom attributes on the class: {0}",
                          atts->Length);

We know that the class doesn’t have any custom attributes, so you’d expect a count of 0. Note the second Boolean argument, which specifies that we want to include any attributes inherited from base classes.

Build and run the application and check the output.

To run the console application, you will need to set it as the startup project. In Solution Explorer, right-click the project name, and then, on the shortcut menu, click Set As Startup Project.

The project name should now be displayed in bold. This will be the project that is started when you instruct Visual Studio to run the projects in the solution.

The attributes are actually on the class members, not on the class itself, so get a list of the class members and query them, as shown in the following:

// Get info on the class members
array<MemberInfo^> ^mi = tt->GetMembers();
Console::WriteLine("Class members: {0}", mi->Length);

Calling GetMembers on the Type object returns an array of MemberInfo objects that describe the members. Running this code on the TestAtts class informs you that there are seven members.

Loop over the list of class members and get the custom attributes for each one.

for each (MemberInfo ^m in mi)
{
    array<Object^> ^atts = m->GetCustomAttributes(true);

    if (atts->Length > 0)
    {
        Console::WriteLine("Attributes for member {0}:", m->Name);
        for each(Object ^att in atts)
        {
            Console::WriteLine(" attribute is {0}", att->ToString());
        }
    }
}

The outer loop considers each member in turn and calls GetCustomAttributes on the Member Info object to get a list of attribute objects. If there are any attribute objects for this member, we print them out.

There are several ways to figure out whether a member has the Documentation custom attribute, and the following code shows one of them. Modify the code for the inner loop in the previous step so that it looks like this:

for each (Object ^att in atts)
{
    Console::WriteLine("  attribute is {0}", att->ToString());
    DocumentationAttribute ^da =
        dynamic_cast<DocumentationAttribute^>(att);
    if (da != nullptr)
    {
        Console::WriteLine("Doc attribute: {0}", da->Text);
    }
}

The loop first uses dynamic_cast to cast the current attribute as a DocumentationAttribute handle. If that returns a non-null value, you know that the cast worked, and so you can retrieve the Text.

Build and run the application.

You should see console output similar to that shown in the screen shot that follows, with a listing of the attributes present on class members and a showing of documentation text values.