Unity プロジェクトで Roslyn アナライザーとルールセットファイルを使用して、コードのスタイルや品質、その他の問題を検査します。
既存のアナライザーライブラリを使用してコードを検査したり、独自のアナライザーを作成して組織内のベストプラクティスや規約を推進したりすることができます。このページでは、空の Unity プロジェクトで Roslyn アナライザーを使用する方法を説明します。
既存の Roslyn アナライザーライブラリを使用するには、ErrorProne.NET.CoreAnalyzers library from NuGet をプロジェクト内部にインストールします。次に、 .csproj ファイルを開きます。このプロジェクトには、アナライザーとして 3 つの .dll ファイルが含まれています。
<ItemGroup>
<Analyzer Include="packages\ErrorProne.NET.CoreAnalyzers.0.1.2\analyzers\dotnet\cs\ErrorProne.NET.Core.dll" />
<Analyzer Include="packages\ErrorProne.NET.CoreAnalyzers.0.1.2\analyzers\dotnet\cs\ErrorProne.Net.CoreAnalyzers.dll" />
<Analyzer Include="packages\ErrorProne.NET.CoreAnalyzers.0.1.2\analyzers\dotnet\cs\RuntimeContracts.dll" />
</ItemGroup>
3 つの .dll ファイルを、Unity プロジェクトの Assets フォルダー (または Assets フォルダー内にネストになっている任意のフォルダー) に移動します。エディターで .dll ファイルを選択します。Plugin Inspector の Select platforms for plugin で、 Any Platform を無効にします。Include platforms のセクションで、 Editor と Standalone のプラットフォームを無効にします。次に、すべての DLL に新しい アセットラベル として RoslynAnalyzer を与えます。
すべてが動作することをテストするために、RethrowError.cs というファイルに以下のコードを記述して、プロジェクトの Assets フォルダーに保存します。このコードによって、ErrorProne.NET は、不正な例外の伝播や疑わしい例外処理に関する警告を発します。
using System;
using UnityEngine;
public class RethrowError : MonoBehaviour
{
void Update()
{
try
{
DoSomethingInteresting();
}
catch (Exception e)
{
Debug.Log(e.Message);
throw e;
}
}
private void DoSomethingInteresting()
{
throw new System.NotImplementedException();
}
}
これを実行すると、コンソールウィンドウに以下の 2 つの警告が表示されます。
Assets\RethrowError.cs(14,23): warning EPC12: Suspicious exception handling: only e.Message is observed in exception block.
Assets\RethrowError.cs(15,19): warning ERP021: Incorrect exception propagation. Use throw; instead.
アナライザーは、アセンブリが Assets フォルダー、またはその親フォルダーに アセンブリ定義ファイル が含まれていないサブフォルダーにある場合、プロジェクトのすべてのアセンブリにグローバルに適用されます。アナライザーがアセンブリ定義を含むフォルダー、またはそのサブフォルダーにある場合、アナライザーはそのアセンブリ定義から生成されたアセンブリと、それ以外のアセンブリ定義を参照するアセンブリにのみ適用されます。
つまり、パッケージ は、パッケージを使用するコードにのみ適用されるアナライザーを供給できます。例えば、パッケージのユーザーがパッケージの API を正しく使用するためのサポートとして使用されます。
プロジェクトのアナライザーが発するさまざまな警告やエラーを処理する方法を独自のルールで定義するには、ルールセットファイルを作成します。カスタムルールセットの作成方法の詳細については、Microsoft の Visual Studio のドキュメント ルール セットをカスタマイズする を参照してください。
Assets ルートフォルダーに、Default.ruleset という名前のルールセットファイルを置きます。Default.ruleset で定義するルールは、すべての定義済みアセンブリ (例えば、Assembly-CSharp.dll)、および .asmdef ファイルを使用して構築されたすべてのアセンブリに適用されます。
Default.ruleset のルールを定義済みのアセンブリにオーバーライドするには、ルートフォルダーに .ruleset ファイルを作成し [PredefinedAssemblyName].ruleset と名づけます。例えば、Assembly-CSharp.ruleset のルールは、Assembly-CSharp.dll のコードに適用されます。これらの .ruleset ファイルのみがルートフォルダー内で許可されます。
Default.RulesetAssembly-CSharp.rulesetAssembly-CSharp-firstpass.rulesetAssembly-CSharp-Editor.rulesetAssembly-CSharp-Editor-firstpass.rulesetUnity でルールセットファイルをテストするには、以下を行います。
Assets フォルダーの中に Subfolder という名前のサブフォルダーを作成します。Subfolder 内で以下を行います。
.asmdef ファイルを作成します。RethrowError.cs の複製を保存します。Assets の中に Default.ruleset ファイルを作成します。<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description=" " ToolsVersion="10.0">
<Rules AnalyzerId="ErrorProne.NET.CodeAnalyzers" RuleNamespace="ErrorProne.NET.CodeAnalyzers">
<Rule Id="ERP021" Action="Error" />
<Rule Id="EPC12" Action="None" />
</Rules>
</RuleSet>
Default.ruleset ファイルでは、以下のルールが定義されています。
EPC12 の抑制。疑わしい例外処理についての警告です。ERP021 の発生。不正な例外伝播に関する警告です。プロジェクトにルールセットファイルを追加した後、ルールを適用するアセンブリ内にあるスクリプトをすべて再インポートします。これを行うと、Unity は新しいルールセットファイルを使用してアセンブリを再コンパイルします。再コンパイルの後、コンソールウィンドウに以下の 2 つのメッセージが表示されます。
Assets\Subfolder\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation. Use throw; instead.
Assets\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation. Use throw; instead.
Unity は Default.ruleset で定義されたルールを Assets/RethrowError.cs と Assets/Subfolder/RethrowError.cs の両方に適用していることに注目してください。
Assets/Subfolder に .ruleset ファイルを作成し、任意の名前を付けます (この例では Hello.ruleset)。
<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description=" " ToolsVersion="10.0">
<Rules AnalyzerId="ErrorProne.NET.CodeAnalyzers" RuleNamespace="ErrorProne.NET.CodeAnalyzers">
<Rule Id="ERP021" Action="Info" />
<Rule Id="EPC12" Action="Info" />
</Rules>
</RuleSet>
この新しい Hello.ruleset ファイルは、Unity に EPC12 と ERP021 の両方を警告やエラーとして扱わずに、コンソールに出力するように指示します。
Unity がプロジェクトを再度コンパイルすると、コンソールウィンドウに以下のメッセージが表示されます。
Assets\Subfolder\RethrowError.cs(14,23): info EPC12: Suspicious exception handling: only e.Message is observed in exception block.
Assets\Subfolder\RethrowError.cs(15,19): info ERP021: Incorrect exception propagation. Use throw; instead.
Assets\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation. Use throw; instead.
Default.ruleset のルールは Assets\RethrowError.cs にはまだ適用されますが、Assets\Subfolder\RethrowError.cs には適用されません。Hello.ruleset のルールがそれをオーバーライドするためです。
許可されているすべてのルールセットのアクションファイルの詳細については、Visual Studio のドキュメント コード分析ルールセットエディターを使用する を参照してください。
以下は、よく使われる Roslyn アナライザーライブラリの Github リポジトリへのリンクです。
2020.2 に Roslyn アナライザーの互換性を追加ニューイン20202