BannedApiAnalyzers.Unity を公開しました

Microsoft.CodeAnalysis.BannedApiAnalyzers は、プロンプトで使用を禁止したいAPIを設定ファイルに書くことでコンパイル時に診断できるRoslynアナライザです。

もちろんUnityでも使用できますが、Unityでは自動生成される .csproj ファイルに設定ファイルのパスを追加する必要があります。これはエディタスクリプトで .csproj ファイル生成をフックして書き換えれば実現できますが、少し面倒です。

このエディタスクリプト実装が不要になるようフォークして変更した BannedApiAnalyzers.Unity を作ったので紹介します。

github.com

nugte.org にも公開済みです。

www.nuget.org

BannedApiAnalyzers.Unity の利点

.csproj ファイルの書き換えが不要

素の Microsoft.CodeAnalysis.BannedApiAnalyzers では、設定ファイルとして BannedSymbols.txt もしくは BannedSymbols.\*.txt を要求します。ファイル名は固定ですが、ファイルパスを .csproj ファイルに AdditionalFiles として追加しなければなりません。

一方、Unityでは2021.3から、特定のファイルパスを .csproj ファイルに AdditionalFiles として追加する機能が使えます*1。しかしファイル名に制約があり、Filename.[Analyzer Name].additionalfile フォーマットでないと処理されません。つまり、BannedSymbols.txt というファイルをアナライザに渡す手段はありません。

BannedApiAnalyzers.Unity は、UnityのAdditional files機能で渡されたファイルを設定ファイルとして読みます。つまり、プロジェクトの Assets/ 下に <Filename>.BannedApiAnalyzers.Unity.additionalfile という名前のファイルを置くだけで、禁止するAPIを指定できます。

なお、次の点に注意してください。

<Filename> 部分は必須で、かつ途中にピリオドを含んではいけません
Assets/ 直下だけでなくサブディレクトリのどこに置いたファイルでも、プロジェクト全体に適用されます。ディレクトリやアセンブリごとに設定を使い分けることはできません
Packages/ 下にある組み込みパッケージにも適用されます

v3.11 ベース

nuget.orgに公開されている Microsoft.CodeAnalysis.BannedApiAnalyzers は v3.3.4 です。次バージョンである v3.11 は安定版をリリースされないまま dotnet/roslyn に統合され、パッケージとしての公開はされていません。

BannedApiAnalyzers.Unity は、v3.11 のソースをベースにしています。v3.3.4 との差異は次のとおりです（Claude Code調べ）。

新機能（v3.11.0 で追加）

機能	概要
名前空間の ban 対応	`BannedSymbols.txt` に `N:SomeNamespace` と書くと、そのネームスペース内のすべての型参照に RS0030 が発火する。v3.3.4 では未対応（エントリが無視された）。
継承元の ban 検出	`class Derived : BannedBase {}` のような継承構文に対しても RS0030 が発火するようになった。Base-type syntax node への `RegisterSyntaxNodeAction` が追加。
`//` コメントのサポート	`BannedSymbols.txt` で行末に `// 説明` と書けるようになった。v3.3.4 では `//` 以降が DocumentationCommentId の一部として解釈され、シンボル解決が静かに失敗していた。

内部変更（挙動に影響する可能性あり）

変更	影響
シンボル解決の遅延化	解決を `Lazy<ImmutableArray<ISymbol>>` に変更。パフォーマンス改善で機能差異はほぼないが、曖昧な ID のエッジケースで挙動が変わる可能性あり。
重複検出ロジック変更	v3.3.4: 解決済み `ISymbol` オブジェクトの比較。v3.11.0: 生の `DeclarationId` 文字列（trim 後）で grouping。未解決シンボルでも重複が検出されるように。

使いかた

インストール

アナライザのインストールは、NuGetForUnity か UnityNuGet (OpenUPM)*2 からがおすすめです。

NuGetForUnity の場合、次の手順でインストールすると、全アセンブリに適用されます。

Open the NuGetForUnity window via NuGet > Manage NuGet Packages
Search "BannedApiAnalyzers.Unity" and click Install

UnityNuGet の場合、openupmコマンドかPackage Managerウィンドウでインストールしてから、適用させたいアセンブリの Assembly Definition References に BannedApiAnalyzers.Unity_Unity を追加します。

openupm add org.nuget.BannedApiAnalyzers.Unity

NuGetForUnity と UnityNuGet の違いについて詳しくは、次の記事を参照してください。

www.nowsprinting.com

設定ファイル

Assets/ 下の任意のディレクトリに設定ファイルを作ります。ファイル名はフォーマット <Filename>.BannedApiAnalyzers.Unity.additionalfile を守る必要があります。

設定ファイルにはDocumentation Comment ID形式で禁止したいAPIを列挙します。書式は ID string format を参照してください。

たとえば、Assets/BannedSymbols.BannedApiAnalyzers.Unity.additionalfile に次のように書きます。

M:UnityEngine.GameObject.Find(System.String)

すると、次のように GameObject.Find(string) メソッドの使用箇所で警告が出ます。

なお、Documentation Comment ID の後ろに ; を挟んでメッセージを書けるので、どう書き換えるべきかを書いておくとよいでしょう。特にAI Coding Agentを使用するなら必須といえます。

補足

重大度の変更

デフォルトでは、BannedApiAnalyzers.Unity による診断の重大度（severity）は Warning です。これは .ruleset、.globalconfig、もしくは .editorconfig ファイルで変更できます。詳しくは、それぞれ過去記事を参照してください。

www.nowsprinting.com