GException Class

In This Topic

A PostSharp aspect that logs exceptions after they are thrown when they cause a method to exit. This allows for logging of handled as well as unhandled exceptions.

Syntax

Visual Basic
C#

'Declaration
 
<DebuggerNonUserCodeAttribute()>
<PostSharp.Extensibility.HasInheritedAttributeAttribute(Mono.Cecil.CustomAttributeArgument[])>
<PostSharp.Extensibility.MulticastAttributeUsageAttribute(MulticastTargets.Constructor Or  _
    MulticastTargets.InstanceConstructor Or  _
    MulticastTargets.Method Or  _
    MulticastTargets.StaticConstructor, 
   AllowMultiple=True, 
   TargetMemberAttributes=MulticastAttributes.NonAbstract)>
<PostSharp.Serialization.SerializerAttribute()>
<PostSharp.Aspects.Configuration.AspectConfigurationAttributeTypeAttribute(PostSharp.Aspects.Configuration.OnMethodBoundaryAspectConfigurationAttribute)>
<AttributeUsageAttribute(AttributeTargets.Assembly Or  _
    AttributeTargets.Class Or  _
    AttributeTargets.Constructor Or  _
    AttributeTargets.Event Or  _
    AttributeTargets.Interface Or  _
    AttributeTargets.Method Or  _
    AttributeTargets.Property Or  _
    AttributeTargets.Struct, 
   AllowMultiple=True, 
   Inherited=False)>
<XmlTypeAttribute("http://schemas.postsharp.net/2.0/aspects")>
<SerializableAttribute()>
Public Class GException 
   Inherits GAspectBase
   Implements Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.IMethodLevelAspect, PostSharp.Aspects.IMethodLevelAspectBuildSemantics, PostSharp.Aspects.IOnMethodBoundaryAspect, PostSharp.Extensibility.IValidableAnnotation

[DebuggerNonUserCode()]
[PostSharp.Extensibility.HasInheritedAttribute(Mono.Cecil.CustomAttributeArgument[])]
[PostSharp.Extensibility.MulticastAttributeUsage(MulticastTargets.Constructor | 
    MulticastTargets.InstanceConstructor | 
    MulticastTargets.Method | 
    MulticastTargets.StaticConstructor, 
   AllowMultiple=true, 
   TargetMemberAttributes=MulticastAttributes.NonAbstract)]
[PostSharp.Serialization.Serializer()]
[PostSharp.Aspects.Configuration.AspectConfigurationAttributeType(PostSharp.Aspects.Configuration.OnMethodBoundaryAspectConfigurationAttribute)]
[AttributeUsage(AttributeTargets.Assembly | 
    AttributeTargets.Class | 
    AttributeTargets.Constructor | 
    AttributeTargets.Event | 
    AttributeTargets.Interface | 
    AttributeTargets.Method | 
    AttributeTargets.Property | 
    AttributeTargets.Struct, 
   AllowMultiple=true, 
   Inherited=false)]
[XmlType("http://schemas.postsharp.net/2.0/aspects")]
[Serializable()]
public class GException : GAspectBase, Gibraltar.Agent.IMessageSourceProvider, PostSharp.Aspects.IAspect, PostSharp.Aspects.IAspectBuildSemantics, PostSharp.Aspects.IMethodLevelAspect, PostSharp.Aspects.IMethodLevelAspectBuildSemantics, PostSharp.Aspects.IOnMethodBoundaryAspect, PostSharp.Extensibility.IValidableAnnotation

Remarks

GException is a PostSharp aspect that watches for exceptions causing an associated method to exit early. Even if these exceptions would ultimately be handled by a method higher up the call stack they are recorded. Because they may be handled they are logged as warnings. If they ultimately become unhandled exceptions then Gibraltar's Error Manager will automatically record them as an error.

Recommended Usage

This aspect is very inexpensive at runtime and is highly recommended for use throughout your assemblies. In general the only cases where it isn't highly useful is when your code routinely uses exceptions to alter control flow or when you are also using GTrace, which will record the same information recorded by GException in a different form.

This can be easily accomplished by using Attribute Multicasting. See the general documentation on integrating with PostSharp for more information.

Log Message Categorization

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

Enabling and Disabling at Runtime

It is possible to enable and disable GException at runtime. To do this just set the Enabled property which will affect all methods instrumented with GException in the current process. Because GException records nothing in the nominal case where there is no exception causing the call stack to unwind it is very inexpensive to apply broadly and rarely should be disabled.

Example

You can associate the GException attribute with a single method, a property, or an entire class to monitor all methods in that class. You can also use attribute multicasting to apply it to all matching methods in your assembly.

Monitor one method within a class

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

Monitor all methods within a class

[GException]
public class SampleApplication
{
    private void InterestingMethod(int valueOne, String anotherValue)
    {
        //Do something interesting here
    }
 
    private void AnotherInterestingMethod(int valueTwo, String anotherValue)
    {
        //Do something even more interesting here
    }
}

Inheritance Hierarchy

System.Object
   System.Attribute
      PostSharp.Extensibility.MulticastAttribute
         PostSharp.Aspects.Aspect
            PostSharp.Aspects.MethodLevelAspect
               PostSharp.Aspects.OnMethodBoundaryAspect
                  Gibraltar.Agent.PostSharp.GAspectBase
                     Gibraltar.Agent.PostSharp.GException

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

GException Members
Gibraltar.Agent.PostSharp Namespace

Send Feedback