24.4 Reserved attributes

A small number of attributes affect the language in some way. These
attributes include:
? System.AttributeUsageAttribute (§24.4.1), which is used to describe the
ways in which an
attribute class can be used.
? System.ConditionalAttribute (§24.4.2), which is used to define
conditional methods.
? System.ObsoleteAttribute (§24.4.3), which is used to mark a member as
obsolete.
24.4.1 The AttributeUsage attribute
The attribute AttributeUsage is used to describe the manner in which the
attribute class can be used.
A class that is decorated with the AttributeUsage attribute must derive
from System.Attribute, either
directly or indirectly. Otherwise, a compile-time error occurs.
[Note: For an example of using this attribute, see §24.1.1. end note]
24.4.2 The Conditional attribute
The attribute Conditional enables the definition of conditional methods.
The Conditional attribute
indicates a condition by testing a conditional compilation symbol. Calls to
a conditional method are either
included or omitted depending on whether this symbol is defined at the
point of the call. If the symbol is
defined, the call is included; otherwise, the call is omitted.
A conditional method is subject to the following restrictions:
? The conditional method must be a method in a class-declaration or
struct-declaration. A compile-time
error occurs if the Conditional attribute is specified on an interface
method.
? The conditional method must have a return type of void.
? The conditional method must not be marked with the override modifier. A
conditional method may be
marked with the virtual modifier, however. Overrides of such a method are
implicitly conditional,
and must not be explicitly marked with a Conditional attribute.
? The conditional method must not be an implementation of an interface
method. Otherwise, a compiletime
error occurs.
In addition, a compile-time error occurs if a conditional method is used in
a delegate-creation-expression.
[Example: The example
#define DEBUG
Chapter 24 Attributes
313
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();
}
}
declares Class1.M as a conditional method. Class2’s Test method calls this
method. Since the
conditional compilation symbol DEBUG is defined, if Class2.Test is called,
it will call M. If the symbol
DEBUG had not been defined, then Class2.Test would not call Class1.M. end
example]
It is important to understand that the inclusion or exclusion of a call to
a conditional method is controlled by
the conditional compilation symbols at the point of the call. [Example: In
the example
// Begin class1.cs
using System;
using System.Diagnostics;
class Class1
{
[Conditional("DEBUG")]
public static void F() {
Console.WriteLine("Executed Class1.F");
}
}
// End class1.cs
// Begin class2.cs


#define DEBUG
class Class2
{
public static void G() {
Class1.F(); // F is called
}
}
// End class2.cs
// Begin class3.cs
#undef DEBUG
class Class3
{
public static void H() {
Class1.F(); // F is not called
}
}
// End class3.cs
the classes Class2 and Class3 each contain calls to the conditional method
Class1.F, which is
conditional based on whether or not DEBUG is defined. Since this symbol is
defined in the context of Class2
but not Class3, the call to F in Class2 is included, while the call to F in
Class3 is omitted. end example]
The use of conditional methods in an inheritance chain can be confusing.
Calls made to a conditional
method through base, of the form base.M, are subject to the normal
conditional method call rules.
[Example: In the example
C# LANGUAGE SPECIFICATION
314
// Begin class1.cs
using System;
using System.Diagnostics;
class Class1
{
[Conditional("DEBUG")]
public virtual void M() {
Console.WriteLine("Class1.M executed");
}
}
// End class1.cs
// Begin class2.cs
using System;
class Class2: Class1
{
public override void M() {
Console.WriteLine("Class2.M executed");
base.M(); // base.M is not called!
}
}
// End class2.cs
// Begin class3.cs
#define DEBUG
using System;
class Class3
{
public static void Test() {
Class2 c = new Class2();
c.M(); // M is called
}
}
// End class3.cs
Class2 includes a call to the M defined in its base class. This call is
omitted because the base method is
conditional based on the presence of the symbol DEBUG, which is undefined.
Thus, the method writes to the
console ?Class2.M executed? only. Judicious use of pp-declarations can
eliminate such problems. end
example]
24.4.3 The Obsolete attribute
The attribute Obsolete is used to mark types and members of types that
should no longer be used.
using System;
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct |
AttributeTargets.Enum | AttributeTargets.Interface |
AttributeTargets.Delegate | AttributeTargets.Method |
AttributeTargets.Constructor | AttributeTargets.Property |
AttributeTargets.Field | AttributeTargets.Event)]
public class ObsoleteAttribute: Attribute
{
public ObsoleteAttribute() {?}
public ObsoleteAttribute(string message) {?}
public ObsoleteAttribute(string message, bool error) {?}
public string Message { get {?} }
public bool IsError{ get {?} }
}
If a program uses a type or member that is decorated with the Obsolete
attribute, then the compiler shall
issue a warning or error in order to alert the developer, so the offending
code can be fixed. Specifically, the
compiler shall issue a warning if no error parameter is provided, or if the
error parameter is provided and has
the value false. The compiler shall issue a compile-time error if the error
parameter is specified and has the
value true.
Chapter 24 Attributes
315
[Example: In the example
[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();
}
}
the class A is decorated with the Obsolete attribute. Each use of A in Main
results in a warning that
includes the specified message, ?This class is obsolete; use class B
instead.?
end example]