Meziantou.Analyzer.Annotations 1.8.0

Meziantou.Analyzer.Annotations

Meziantou.Analyzer.Annotations enables you to configure certain analyzer rules by adding annotations directly to your code.

Meziantou.Analyzer.Annotations is a separate dependency from Meziantou.Analyzer. If you want to use these attributes in your code, add an explicit package reference:

dotnet add package Meziantou.Analyzer.Annotations

You can also copy the attribute source files into your project as long as the namespace and type names match. The copied types can be public or internal.

By default, all usages of attributes from Meziantou.Analyzer.Annotations are removed from the compiled assembly metadata. This means your binaries will not reference the Meziantou.Analyzer.Annotations.dll assembly.

If you want to keep these attributes in the metadata (for example, for reflection or tooling purposes), define the MEZIANTOU_ANALYZER_ANNOTATIONS conditional compilation symbol in your project settings.

Available attributes

ExcludeFromBlockingCallAnalysisAttribute

Use ExcludeFromBlockingCallAnalysisAttribute to exclude specific MA0042/MA0045 method/property diagnostics at the assembly level.

[assembly: Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute("M:System.Threading.Tasks.Task.Wait")]
[assembly: Meziantou.Analyzer.Annotations.ExcludeFromBlockingCallAnalysisAttribute(typeof(System.Threading.Thread), "Sleep", typeof(int))]

ExcludeFromCancellationTokenAnalysisAttribute

Use ExcludeFromCancellationTokenAnalysisAttribute to mark a method as valid to call without a CancellationToken. No MA0032/MA0040/MA0079/MA0080 diagnostic is reported for the calls to an excluded method, even when the method has an overload with a CancellationToken and a token is available in the scope.

Methods of the current project can be annotated directly:

class Sample
{
    [Meziantou.Analyzer.Annotations.ExcludeFromCancellationTokenAnalysis]
    public static System.Threading.Tasks.Task FlushAsync() => throw null;
    public static System.Threading.Tasks.Task FlushAsync(System.Threading.CancellationToken cancellationToken) => throw null;
}

await Sample.FlushAsync(); // No MA0040 diagnostic

Methods of another assembly can be annotated at the assembly level, using their XML documentation id or their containing type and name. The parameter types are optional and restrict the exclusion to a single overload.

[assembly: Meziantou.Analyzer.Annotations.ExcludeFromCancellationTokenAnalysis("M:System.Threading.Channels.ChannelWriter`1.WriteAsync(`0,System.Threading.CancellationToken)")]
[assembly: Meziantou.Analyzer.Annotations.ExcludeFromCancellationTokenAnalysis(typeof(Sample), "FlushAsync")]
[assembly: Meziantou.Analyzer.Annotations.ExcludeFromCancellationTokenAnalysis(typeof(Sample), "FlushAsync", typeof(System.Threading.CancellationToken))]

Note that the attribute is removed from the metadata of the compiled assembly unless the MEZIANTOU_ANALYZER_ANNOTATIONS symbol is defined. Use the assembly-level form to exclude the methods of an assembly that does not define this symbol.

NonAwaitableTypeAttribute

Use NonAwaitableTypeAttribute to exclude MA0042/MA0045 await recommendations for specific types at the assembly level. The match is exact-type only. Derived types are not excluded unless explicitly listed.

[assembly: Meziantou.Analyzer.Annotations.NonAwaitableTypeAttribute(typeof(System.Data.Common.DbCommand))]

NonAsyncDisposableTypeAttribute

Use NonAsyncDisposableTypeAttribute to exclude MA0042/MA0045 await using recommendations for specific types at the assembly level. The match is exact-type only. Derived types are not excluded unless explicitly listed.

[assembly: Meziantou.Analyzer.Annotations.NonAsyncDisposableTypeAttribute(typeof(System.Data.Common.DbCommand))]

CultureInsensitiveAttribute

Use CultureInsensitiveAttribute to mark the value of a property, a field, or a parameter as culture-insensitive, even when its type is culture-sensitive. Methods cannot be annotated: the attribute marks a value, not the way a method computes it.

class Sample
{
    [Meziantou.Analyzer.Annotations.CultureInsensitive]
    public static double InvariantValue => 0;
}

_ = $"{Sample.InvariantValue}"; // No MA0076 diagnostic

A parameter marked with the attribute is culture-insensitive in both directions: reading it in the method does not report a diagnostic, and MA0075/MA0076 are not reported for the arguments provided by the callers.

static void Log([Meziantou.Analyzer.Annotations.CultureInsensitive] string message) { }

Log($"Value: {1.5}"); // No MA0076 diagnostic

Properties and fields of another assembly can be annotated at the assembly level using their XML documentation id.

[assembly: Meziantou.Analyzer.Annotations.CultureInsensitiveAttribute("P:Sample.InvariantValue")]