Attribute Usage Guidelines

The .NET Framework enables developers to invent new kinds of declarative information, to specify declarative information for various program entities, and to retrieve attribute information in a run-time environment. For example, a framework might define a HelpAttribute attribute that can be placed on program elements such as classes and methods to provide a mapping from program elements to their documentation. New kinds of declarative information are defined through the declaration of attribute classes, which might have positional and named parameters. For more information about attributes, see Writing Custom Attributes.

The following rules outline the usage guidelines for attribute classes:

• Add the Attribute suffix to custom attribute classes, as shown in the following example.

  Public Class ObsoleteAttribute
  

  public class ObsoleteAttribute{}
  

• Specify AttributeUsage on your attributes to define their usage precisely, as shown in the following example.

  <AttributeUsage(AttributeTargets.All, Inherited := False, AllowMultiple := True)>  _
  
  Public Class ObsoleteAttribute
     Inherits Attribute
     ' Insert code here.
  End Class
  

  [AttributeUsage(AttributeTargets.All, Inherited = false, AllowMultiple = true)]
  public class ObsoleteAttribute: Attribute {}
  

• Seal attribute classes whenever possible, so that classes cannot be derived from them.

• Use positional arguments (constructor parameters) for required parameters. Provide a read-only property with the same name as each positional argument, but change the case to differentiate between them. This allows access to the argument at run time.

• Use named arguments for optional parameters and provide a read/write property for each named argument.

• Do not define a parameter with both named and positional arguments. The following code example illustrates this pattern.

  Public Class NameAttribute
     Inherits Attribute
     Private userNameValue as String
     Private ageValue as Integer
  
     ' This is a positional argument.
     Public Sub New(userName As String) 
        userNameValue = userName
     End Sub
  
     Public ReadOnly Property UserName() As String
        Get
           Return userNameValue 
        End Get
     End Property
  
     ' This is a named argument.
     Public Property Age() As Integer
        Get
           Return ageValue 
        End Get
        Set
           ageValue = value
        End Set 
     End Property
  End Class
  

  public class NameAttribute: Attribute 
  {
     string userName;
     int age;
  
     // This is a positional argument.
     public NameAttribute (string userName) 
     { 
         this.userName = userName;
     }
     public string UserName 
     { 
        get 
        {
           return userName; 
        }
     }
     // This is a named argument.
     public int Age 
     { 
        get 
        {
           return age;
        }
        set 
        {
           age = value;
        }
     } 
  }
  

Portions Copyright 2005 Microsoft Corporation. All rights reserved.

Portions Copyright Addison-Wesley Corporation. All rights reserved.

For more information on design guidelines, see the "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley, 2005.

See Also

Concepts

Usage Guidelines

Other Resources

Design Guidelines for Developing Class Libraries