BannedApiAnalyzers.Help.md

How to use Microsoft.CodeAnalysis.BannedApiAnalyzers

The following file or files have to be added to any project referencing this package to enable analysis:

• BannedSymbols.txt
• BannedSymbols.*.txt

This can be done by:

• In Visual Studio, right click project in Solution Explorer, and choose "Add -> New Items", then select "Text File" in "Add new item" dialog.

• Or, create the file at the location you desire, then add the following text to your project/target file (replace file path with its actual location):

  <ItemGroup>
    <AdditionalFiles Include="BannedSymbols.txt" />
  </ItemGroup>

Generated code is analyzed by default. To exclude generated code from banned API analysis, add the following to an analyzer config file such as .globalconfig:

is_global = true

dotnet_banned_api_analyzer.exclude_generated_code = true

To add a symbol to the banned list, just add an entry in the format below to one of the configuration 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 BannedSymbols.txt 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>
    {
    }
}

Symbol in Source	Sample Entry in BannedSymbols.txt
class BannedType	T:N.BannedType;Don't use BannedType
class BannedType<T>	T:N.BannedType`1;Don't use BannedType<T>
BannedType()	M:N.BannedType.#ctor
int BannedMethod()	M:N.BannedType.BannedMethod
void BannedMethod(int i)	M:N.BannedType.BannedMethod(System.Int32);Don't use BannedMethod
void BannedMethod<T>(T t)	M:N.BannedType.BannedMethod`1(``0)
void BannedMethod<T>(Func<T> f)	M:N.BannedType.BannedMethod`1(System.Func{``0})
string BannedField	F:N.BannedType.BannedField
string BannedProperty { get; }	P:N.BannedType.BannedProperty
event EventHandler BannedEvent;	E:N.BannedType.BannedEvent
namespace N	N:N