BannedApiAnalyzers.Unity 1.0.2

BannedApiAnalyzers for Unity

A Unity-focused fork of Microsoft.CodeAnalysis.BannedApiAnalyzers that uses Unity additional files instead of BannedSymbols.txt — no .csproj edits required.

[!NOTE]
This package is based on dotnet/roslyn-analyzers v3.11.0.

[!NOTE]
Unity additional files require Unity 2021.3 or later.

Analyzer Rules

RS0030 — Do not use banned APIs

The symbol has been marked as banned in this project, and an alternate should be used instead.

RS0031 — The list of banned symbols contains a duplicate

The list of banned symbols contains a duplicate.

RS0035 — External access to internal symbols outside the restricted namespace(s) is prohibited

RestrictedInternalsVisibleToAttribute enables a restricted version of InternalsVisibleToAttribute that limits access to internal symbols to those within specified namespaces. Each referencing assembly can only access internal symbols defined in the restricted namespaces that the referenced assembly allows.

Usage

1. Install the analyzer package

Install BannedApiAnalyzers.Unity from a package registry using either NuGetForUnity or UnityNuGet.

NuGetForUnity

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

UnityNuGet (hosted on OpenUPM)

1. Install the package:

   openupm add org.nuget.BannedApiAnalyzers.Unity
   

2. Open the .asmdef of each assembly you want the analyzer to apply to, and add BannedApiAnalyzers.Unity_Unity to its Assembly Definition References.

[!TIP]
Analyzers installed via NuGetForUnity apply to all assemblies in the project (including those in the PackageCache), while analyzers installed via UnityNuGet apply only to the referenced assembly and any assemblies that depend on it.

2. Create a banned symbols additional file

Create one or more files named according to the pattern <Filename>.BannedApiAnalyzers.Unity.additionalfile (the <Filename> part must not contain a period) and place them anywhere under Assets/:

• BannedSymbols.BannedApiAnalyzers.Unity.additionalfile
• Platform.BannedApiAnalyzers.Unity.additionalfile (one file per concern)

Unity automatically discovers .additionalfile files in Assets/ and passes them to the analyzer — no .csproj edits required.

For more details on Unity's additional files feature, see Additional files for Roslyn analyzers and source generators.

3. Add entries to the banned symbols file

To add a symbol to the banned list, just add an entry in the format below to one of the additional files (Description Text will be displayed as description in diagnostics, which is optional):

{Documentation Comment ID string for the symbol}[;Description Text]

Comments can be indicated with //, in the same way that they work in C#.

For details on ID string format, please refer to "ID string format".

Examples of banned symbols entries for symbols declared in the source below:

namespace N
{
    class BannedType
    {
        public BannedType() {}
        public int BannedMethod() {}
        public void BannedMethod(int i) {}
        public void BannedMethod<T>(T t) {}
        public void BannedMethod<T>(Func<T> f) {}
        public string BannedField;
        public string BannedProperty { get; }
        public event EventHandler BannedEvent;
    }

    class BannedType<T> {}
}

License

MIT — see License.txt.