Appendix G
Useful Attributes
The .NET Framework defines more than 500 attribute classes, so only a handful of the most commonly used are described here.
The names of attribute classes end with Attribute. If you want to search for an attribute’s class, add Attribute to the end of the name. For example, the ReadOnly attribute class’s name is ReadOnlyAttribute.
To create a custom attribute, simply create a new class derived from the Attribute class. By convention, the custom attribute class’s name should end with Attribute.
For more information about attributes, see msdn.microsoft.com/library/system.attribute.aspx. If you scroll to the bottom, you can see a list of classes that inherit from the Attribute class.
Useful XML Serialization Attributes
The following table lists attributes that are useful when performing XML serializations.
| Attribute | Purpose |
XmlArray | Indicates the name that should be given to an array in an XML serialization. |
XmlArrayItem | Indicates a type that can be in an array in an XML serialization. |
XmlAttribute | Indicates that a property should be serialized as an attribute rather than an element in an XML serialization. Optionally indicates the attribute’s name in the serialization. |
XmlElement | Specifically indicates the field will be serialized as an XML element. This attribute allows you to change the XML element’s name. |
XmlEnum | Enables you to specify the names by which enumeration values are serialized. |
XmlIgnore | Indicates that an XML serialization should not serialize a property. |
XmlRoot | Controls the name and namespace for the element generated for an XML serialization’s root element. |
XmlText | Indicates that a value should be serialized as a text value in an XML serialization. |
XmlType | Controls the name and namespace for the element generated for a class in an XML serialization. |
Useful JSON Serialization Attributes
The following table lists attributes that are useful when performing JSON serializations.
| Attribute | Purpose |
CollectionDataContract | Allows you to control serialization of collections. |
DataContract | Indicates that a type is serializable by a serializer such as a DataContractSerializer. |
DataMember | Indicates that a property should be serialized. |
EnumMember | Indicates that a property is an enumeration and should be serialized. |
IgnoreDataMember | Indicates that a property should not be included in the serialization. |
OptionalField | Indicates that a property is optional in a serialization. |
Binary Serialization Attributes
The BinaryFormatter class understands only one attribute, Serializable, which you should use to mark a class as serializable. The serialization includes all properties and fields, even those with restricted access such as those marked private.
Other Useful Attributes
The following table summarizes particularly useful attributes available to C# programs.
| Attribute | Purpose |
AssemblyCompany | Stores an assembly’s company name. |
AssemblyCopyright | Stores an assembly’s copyright information. |
AssemblyCulture | Stores the culture that an assembly supports. |
AssemblyDescription | Stores an assembly’s description. |
AssemblyProduct | Stores an assembly’s product name. |
AssemblyTitle | Stores an assembly’s title. |
AssemblyTrademark | Stores an assembly’s trademark information. |
AssemblyVersion | Stores an assembly’s version information. |
AttributeUsage | Indicates the kinds of items (class, method, property, and so on) to which a custom attribute may be applied. |
Browsable | Indicates whether a property should be visible to editors such as the Properties window or the PropertyGrid control. |
Category | Indicates the category that should include a property in an editor such as the Properties window. |
Conditional | Hides a method’s body if a compile-time symbol is undefined. The method is still callable; it just doesn’t do anything. |
DebuggerHidden | Indicates a method should be hidden from the debugger. The debugger will not stop inside or step through the method. |
DebuggerStepThrough | Makes the debugger skip over the method if you try to step over or into it. The debugger will still stop inside the method if you set a breakpoint there. |
DefaultEvent | Indicates a class’s default event. |
DefaultProperty | Indicates a class’s default property. |
DefaultValue | Sets a property’s default value for use by editors such as the Properties window. (If you right-click a property in the Properties window and select Reset, the property is given this value.) |
Description | Specifies the description that an editor such as the Properties window should display for an object’s property. (Use XML comments to specify a description for use by IntelliSense.) |
DisplayName | Indicates the name that editors such as the Properties window should display for a property. |
Flags | Indicates that an enumeration should be considered a bit mask, so a variable can include one or more of the enumeration’s values simultaneously. |
Localizable | Indicates that a property is localizable, and its value should be stored in the appropriate resource files. |
Mergable | Indicates an editor such as the Properties window should allow the user to get and set the property for multiple objects at the same time. (For example, if you select two TextBoxes, you can set both of their Text properties at the same time. In contrast, you cannot set their Name properties at the same time.) |
Obsolete | Marks a method as obsolete. The program can still use the method, but Visual Studio flags calls to it with warnings. |
ParenthesizePropertyName | Tells property editors such as the Properties window to display a property’s name surrounded by parentheses. When displayed alphabetically, the property comes at the top of the list. |
ReadOnly | Indicates that a property is read-only to editors such as the PropertyGrid control. |