Open sandboxFocusImprove this doc

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

Classes

DiagnosticDefinition

Defines a diagnostic that does not accept any parameters. For a diagnostic that accepts parameters, use DiagnosticDefinition<T>.

DiagnosticDefinition<T>

Defines a diagnostic with a strongly-typed set of parameters that are typically specified by using a named tuple for generic parameter T. For diagnostics that accept a single parameter, T must be set to the type of this parameter. To accept several parameters, use a tuple. For a diagnostic that does not accept parameters, use DiagnosticDefinition.

SuppressionDefinition

Defines the suppression of a kind of diagnostics. Suppression definitions must be static fields or properties of an aspect classes. Suppressions are instantiated with Suppress(ISuppression, IDeclaration, IDiagnosticSource).

Structs

None

A type to be used as generic argument of DiagnosticDefinition<T> when there is no parameter in the message.

ScopedDiagnosticSink

Encapsulates an IDiagnosticSink and the default target of diagnostics, suppressions, and code fixes.

Interfaces

IDiagnostic

Represents an instance of a diagnostic, including its parameters and its optional code fixes.

IDiagnosticDefinition

A non-generic base interface for DiagnosticDefinition<T>.

IDiagnosticLocation

A base interface for objects to which a diagnostic can be reported.

ISuppressibleDiagnostic

Represents a diagnostic that can be suppressed using Filter.

ISuppression

Represents an instance of a diagnostic suppression, including an optional filter delegate.

Enums

Severity

Severity of diagnostics.