Share via


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