GField Class

In This Topic

A PostSharp aspect used to monitor the state of a field (member variable), recording a log message and metric when it changes.

Enables the logging of method entry and exit at runtime complete with parameter information and results.

Syntax

Visual Basic
C#

'Declaration
 
<DebuggerNonUserCodeAttribute()>
<PostSharp.Extensibility.MulticastAttributeUsageAttribute(MulticastTargets.Field, TargetMemberAttributes=MulticastAttributes.NonLiteral)>
<PostSharp.Extensibility.HasInheritedAttributeAttribute(Mono.Cecil.CustomAttributeArgument[])>
<XmlTypeAttribute("http://schemas.postsharp.net/2.0/aspects")>
<AttributeUsageAttribute(AttributeTargets.Assembly Or  _
    AttributeTargets.Class Or  _
    AttributeTargets.Field Or  _
    AttributeTargets.Interface Or  _
    AttributeTargets.Property Or  _
    AttributeTargets.Struct, 
   AllowMultiple=True)>
<PostSharp.Serialization.SerializerAttribute()>
<PostSharp.Aspects.Configuration.AspectConfigurationAttributeTypeAttribute(PostSharp.Aspects.Configuration.LocationInterceptionAspectConfigurationAttribute)>
<SerializableAttribute()>
Public Class GField 
   Inherits PostSharp.Aspects.LocationInterceptionAspect
   Implements Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.ILocationInterceptionAspect, PostSharp.Aspects.ILocationLevelAspect, PostSharp.Aspects.ILocationLevelAspectBuildSemantics, PostSharp.Extensibility.IValidableAnnotation

[DebuggerNonUserCode()]
[PostSharp.Extensibility.MulticastAttributeUsage(MulticastTargets.Field, TargetMemberAttributes=MulticastAttributes.NonLiteral)]
[PostSharp.Extensibility.HasInheritedAttribute(Mono.Cecil.CustomAttributeArgument[])]
[XmlType("http://schemas.postsharp.net/2.0/aspects")]
[AttributeUsage(AttributeTargets.Assembly | 
    AttributeTargets.Class | 
    AttributeTargets.Field | 
    AttributeTargets.Interface | 
    AttributeTargets.Property | 
    AttributeTargets.Struct, 
   AllowMultiple=true)]
[PostSharp.Serialization.Serializer()]
[PostSharp.Aspects.Configuration.AspectConfigurationAttributeType(PostSharp.Aspects.Configuration.LocationInterceptionAspectConfigurationAttribute)]
[Serializable()]
public class GField : PostSharp.Aspects.LocationInterceptionAspect, Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.ILocationInterceptionAspect, PostSharp.Aspects.ILocationLevelAspect, PostSharp.Aspects.ILocationLevelAspectBuildSemantics, PostSharp.Extensibility.IValidableAnnotation

Remarks

GField is a PostSharp aspect used to monitor changes to fields within classes. It writes a message to the whenever an associated member variable is changed. Additionally:

The previous value is recorded in the log message
The source code location that caused the change is recorded with the log message if source code location information is available.
A sampled metric is recorded for numeric or boolean fields to enable graphing and quantitative analysis in the Gibraltar Analyst.

Categorization

Each log message is recorded in an automatically generated category in the form {BaseCategory}.Trace Exit. See the BaseCategory property for more information on changing the log message category.

Each metric is automatically recorded in a category in the form {BaseCategory}.Field Monitoring.{Category}. See the BaseCategory property for more information on changing the category root and the Category property for more information on how the full category name is determined.

Enabling and Disabling at Runtime

Because GField messages are voluminous and detailed it's often useful to enable and disable them at runtime. To do this just set the Enabled property which will affect all methods instrumented with GField in the current process. When disabled GField has minimal performance impact even in high volume scenarios.

Differentiating Between Instances

Since the GField attribute is applied to a field it will be tracked for all instances of the related class. With the exception of static classes this may be a potentially unbounded set of different objects. By default, every object has a unique runtime identifier which is recorded with the metric value to enable correlation during analysis but this value is not predictable or consistent. Instead, if an object has a property that represents a more useful, unique name for the object then that can be specified in the InstanceNamer property. Doing so will produce more useful log messages and graphs.

Refining Data Captured

You can turn down the amount of information captured for a given method by GField in log messages by setting the EnableSourceLookup property to false. This will reduce the performance overhead of GField at the expense of losing the information on what class & method caused the value to change.

You can supply a Unit caption for fields that represent values in a common unit you want to enable comparative graphing of. For example, you might specify "ms" for times in milliseconds or "%" for percentages. This improves the overall experience graphing the values in Analyst.

Advanced Usage

You can supply your own methods for formatting individual values, captions, and descriptions by creating a new object that derives from GField and overriding the appropriate methods:

FormatValue: Overrides how objects are translated to strings for insertion into messages.
FormatCaption: Overrides how log message captions are generated.
FormatDescription: Overrides how log message descriptions are generated.

Example

You can associate the GField attribute with a single field or an entire class to trace all methods in that class. You can also use attribute multicasting to apply it to all matching fields or classes in your assembly (not generally recommended)

Track changes for one field within a class

public class SampleApplication
{
    [GField]
    private int m_TrackedField;
    private void InterestingMethod(int valueOne, String anotherValue)
    {
        //Do something interesting here
        m_TrackedField = valueOne;
    }
}

Inheritance Hierarchy

System.Object
   System.Attribute
      PostSharp.Extensibility.MulticastAttribute
         PostSharp.Aspects.Aspect
            PostSharp.Aspects.LocationLevelAspect
               PostSharp.Aspects.LocationInterceptionAspect
                  Gibraltar.Agent.PostSharp.GField

Requirements

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

GField Members
Gibraltar.Agent.PostSharp Namespace

Send Feedback