Skip to content

Latest commit

 

History

History
62 lines (42 loc) · 3.16 KB

PublicApiAnalyzers.Help.md

File metadata and controls

62 lines (42 loc) · 3.16 KB
Raw

How to use Microsoft.CodeAnalysis.PublicApiAnalyzers

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

  • PublicAPI.Shipped.txt
  • PublicAPI.Unshipped.txt

This can be done by:

  • In Visual Studio, right-click the project in Solution Explorer, choose "Add -> New Item...", and then select "Text File" in the "Add New Item" dialog. Then right-click each file, select "Properties", and choose "C# analyzer additional file" for "Build Action" in the "Properties" window.
  • Or, create these two files 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="PublicAPI.Shipped.txt" />
    <AdditionalFiles Include="PublicAPI.Unshipped.txt" />
  </ItemGroup>

Nullable reference type support

To enable support for nullable reference types, make sure that you are using a Roslyn compiler version 3.5 (or newer) in your build process and then add the following at the top of each PublicAPI.*.txt file:

#nullable enable

One way of checking the version of your compiler is to add #error version in a source file, then looking at the error message output in your build logs.

At that point, reference types in annotated code will need to be annotated with either a ? (nullable) or a ! (non-nullable). For instance, C.AnnotatedMethod(string! nonNullableParameter, string? nullableParameter, int valueTypeParameter) -> void.

Any public API that haven't been annotated (i.e. uses an oblivious reference type) will be tracked with a ~ marker. The marker lets you track how many public APIs still lack annotations. For instance, ~C.ObliviousMethod() -> string.

We recommend to enable RS0041 warning if you start with a fresh project or your project has reached 100% annotation on your public API to ensure that all public APIs remain annotated. If you are in the process of annotating an existing project, we recommended to disable this warning until you complete the annotation. The rule can be disabled via .editorconfig with dotnet_diagnostic.RS0041.severity = none.

Conditional API Differences

Sometimes APIs vary by compilation symbol such as target framework.

For example when using the #if preprocessor directive:

        public void Foo(string s)
        {}

#if NETCOREAPP3_0
        public void Foo(ReadOnlySpan<char> s)
        {}
#else

To correctly model the API differences between target frameworks (or any other property), use multiple instances of the PublicAPI.*.txt files.

If you have multiple target frameworks and APIs differ between them, use the following in your project file:

  <ItemGroup>
    <AdditionalFiles Include="PublicAPI/$(TargetFramework)/PublicAPI.Shipped.txt" />
    <AdditionalFiles Include="PublicAPI/$(TargetFramework)/PublicAPI.Unshipped.txt" />
  </ItemGroup>