Metalama 1.0 / / Metalama Documentation / Aspect API Documentation / Metalama.​Framework.​Diagnostics

Namespace Metalama.Framework.Diagnostics

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

Conceptual Documentation

See Reporting and Suppressing Diagnostics.

Class diagram

classDiagram class SuppressionDefinition { SuppressedDiagnosticId } class IDiagnosticSink { Report(IDiagnosticLocation, IDiagnostic) Suppress(IDiagnosticLocation, SuppressionDefinition) Suggest(IDiagnosticLocation, CodeFix) } class ScopedDiagnosticSink { Declaration Location Report(IDiagnostic) Suppress(SuppressionDefinition) Suggest(CodeFix) } ScopedDiagnosticSink --|> IDiagnosticSink : implements class DiagnosticSeverity { None Hidden Information Warning Error } class IDiagnostic { Id Message Title Category Severity CodeFixes WithCodeFixes(CodeFix[]) } class CodeFix { } IDiagnostic *-- CodeFix : can contain DiagnosticDefinition_ --|> DiagnosticDefinition~T~ : derives from class DiagnosticDefinition_ { <<without parameter>> } class DiagnosticDefinition~T~ { <<with parameters>> Id Category Severity MessageFormat Title WithArguments(T) IDiagnostic } class IAspectBuilder { Diagnostics } class ValidationContext { Diagnostics } DiagnosticDefinition_ ..|> IDiagnostic : implements DiagnosticDefinition~T~ ..> IDiagnostic : WithArguments instantiates IDiagnostic --> DiagnosticSeverity : Severity IDiagnosticSink ..> IDiagnostic : accepts IDiagnosticSink ..> SuppressionDefinition : accepts IDiagnosticSink ..> CodeFix : accepts IAspectBuilder --> ScopedDiagnosticSink : exposes ValidationContext --> ScopedDiagnosticSink : exposes CodeFixFactory --> CodeFix : creates

Reporting diagnostics

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

To report a parametric diagnostics, you must first call the WithArguments method. This step is not necessary with 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 you are reporting a diagnostic, you can specify the location of the diagnostic, i.e. the element of code to which it will be reported (which determines the file and line of the error message). If you do not specify the location, the default location for the current context will be used.

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

Suppressing diagnostics

To suppress of diagnostic, you must 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, see Reporting and Suppressing Diagnostics.

Suggesting code actions

See 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.

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.

Severity

Severity of diagnostics.

SuppressionDefinition

Defines the suppression of a kind of diagnostics. Suppressions must be defined as static fields or properties of an aspect classes. Suppressions are instantiated with Suppress(SuppressionDefinition, IDeclaration).

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.

IDiagnosticSink

A sink that reports diagnostics reported from user code.