VisualStudio 特定の型やメンバが使われたときに警告を表示する #Roslyn

このドキュメントの内容

VisualStudio の支援機能を使って、使用してほしくない型やメソッドに対して警告が表示されるようにする方法を二つ紹介します。

例

次のような Execute メソッドがあるとします。
コネクションを指定しない場合は既定のコネクションを使用するメソッドを提供していましたが、何らかの理由でこのメソッドを使用しないようにしたいと考えているとします。

public static class DbHelper
{
    /// <summary>
    /// 指定されたコマンドを実行します。<--このメソッドを使わせたくなくなった。
    /// </summary>
    /// <param name="commandText">コマンドテキスト</param>
    public static void Execute(string commandText)
    {
        Execute(commandText, CreateDbConnection());
    }

    /// <summary>
    /// 指定されたコマンドを実行します。
    /// </summary>
    /// <param name="commandText">コマンドテキスト</param>
    /// <param name="connection">コネクション</param>
    public static void Execute(string commandText, IDbConnection connection)
    {
        // 割愛
    }

    private static IDbConnection CreateDbConnection()
    {
        // 割愛
    }
}

方法

ObsoleteAttribute 属性を適用する

型やメンバが廃止予定であることをマークするための属性です。
抑制したい型やメンバが廃止予定である場合、この属性を適用します。
対象の型やメンバに属性を適用するわけですから、自分たちが開発している型とその型のメンバにしかこの方法は使えません。

ObsoleteAttribute属性を適用

    /// <summary>
    /// 指定されたコマンドを実行します。
    /// </summary>
    /// <param name="commandText">コマンドテキスト</param>
    [Obsolete("Execute(string, IDbConnection)を使用してください。")]
    public static void Execute(string commandText)
    {
        Execute(commandText, CreateDbConnection());
    }

対象のメソッドを使用するとコードエディタ上に次のような警告が表示されるようになります。

BannedApiAnalyzers アナライザを利用する

Roslyn アナライザによって抑制したい型やメンバに対して警告を表示します。
ObsoleteAttribute 属性とは異なりソースコードに対して記述するわけではないため、標準ライブラリや OSS などで提供されている型やメンバにも適用できます。

Nuget などで対象のプロジェクトに Microsoft.CodeAnalysis.BannedApiAnalyzers を追加します。
対象のプロジェクトに BannedSymbols.txt という名前のテキストファイルを追加します。
BannedSymbols.txt 内に抑制したい型やメンバを列挙します。記述書式は 種類:シグネチャ;メッセージ です。詳しくは参考リンクを参照してください。

BannedSymbols.txt

M:mxProject.DbHelper.Execute(System.String);Execute(string, IDbConnection)を使用してください。

対象のメソッドを使用するとコードエディタ上に次のような警告が表示されるようになります。和訳の結果がやや残念ですが、意図は十分伝わると思います。

参考リンク

【Cygames Engineers' Blog】ZLogger – .NET CoreとUnityのためのゼロアロケーション構造化ロガー
【Qiita】How to use Microsoft.CodeAnalysis.BannedApiAnalyzers