Namespace Metalama.Framework.Diagnostics

This namespace allows you to report or suppress diagnostics from your aspect code.

Conceptual Documentation

Refer to Reporting and suppressing diagnostics.

Class diagram

classDiagram

  class SuppressionDefinition {
      SuppressedDiagnosticId
  }

    class ScopedDiagnosticSink {
        Report(IDiagnosticLocation, IDiagnostic)
        Suppress(IDiagnosticLocation, SuppressionDefinition)
        Suggest(IDiagnosticLocation, CodeFix)

    }

    class ScopedDiagnosticSink {
        Declaration
        Location
        Report(IDiagnostic)
        Suppress(SuppressionDefinition)
        Suggest(CodeFix)
    }




    class DiagnosticSeverity {
        None
        Hidden
        Information
        Warning
        Error
    }
    class IDiagnostic {
        Id
        Message
        Title
        Category
        Severity
        CodeFixes
        WithCodeFixes(CodeFix[])
    }

    class CodeFix {

    }


    IDiagnostic *-- CodeFix : can contain

     DiagnosticDefinition~T~ <|-- `DiagnosticDefinition ` : derives from

class `DiagnosticDefinition ` {

}

    class DiagnosticDefinition~T~ {
        Id
        Category
        Severity
        MessageFormat
        Title
        WithArguments(T) IDiagnostic
        }

    class IAspectBuilder {
        Diagnostics
    }

    class ValidationContext {
        Diagnostics
    }


    IDiagnostic <|.. `DiagnosticDefinition ` : implements
    IDiagnostic <.. DiagnosticDefinition~T~ : WithArguments instantiates
    DiagnosticSeverity <-- IDiagnostic : Severity
    IDiagnostic <.. ScopedDiagnosticSink : accepts
    SuppressionDefinition <.. ScopedDiagnosticSink : accepts
    CodeFix <.. ScopedDiagnosticSink : accepts

    ScopedDiagnosticSink <-- IAspectBuilder : exposes
    ScopedDiagnosticSink <-- ValidationContext : exposes

CodeFix <-- CodeFixFactory : creates

Reporting diagnostics

To report a diagnostic, first define a static field of type DiagnosticDefinition or DiagnosticDefinition<T> in your aspect class. Use DiagnosticDefinition for parameterless diagnostics, and DiagnosticDefinition<T> for parametric diagnostics.

To report parametric diagnostics, first call the WithArguments method. This step is not necessary for parameterless diagnostics.

To report a diagnostic, call the Report method. This object is exposed on the Diagnostics property of the argument of the IAspectBuilder.BuildAspect method of your aspect. You can also report a diagnostic from a validator.

When reporting a diagnostic, you can specify the location of the diagnostic, i.e., the code element to which it will be reported (which determines the file and line of the error message). If you don't specify the location, the default location for the current context will be used.

You can add code fixes to diagnostics. For details, refer to the Metalama.Framework.CodeFixes namespace.

Suppressing diagnostics

To suppress a diagnostic, first define it as a static field of type SuppressionDefinition in your aspect class. You can then suppress a diagnostic from any declaration from an aspect using the Suppress method.

For more information, refer to Reporting and suppressing diagnostics.

Suggesting code actions

Refer to Metalama.Framework.CodeFixes.

Namespace members