Loupe - Log - Monitor - Resolve
Gibraltar.Agent.PostSharp Namespace / GException Class
Members Example

In This Topic
    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
    'Declaration
     
    
    <DebuggerNonUserCodeAttribute()>
    <PostSharp.Extensibility.HasInheritedAttributeAttribute()>
    <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()]
    [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

    See Also