Api Check

Api check documentation

• Basics
• Adding exceptions

Basics

API Check detects breaking changes in public APIs by generating and storing an API listing of the base version of an assembly that later on gets compared with the API listing of the version of the assembly in development.

Usage:  .\Microsoft.AspNetCore.BuildTools.ApiCheck.exe [command]
Commands:
  compare
  generate

.\Microsoft.AspNetCore.BuildTools.ApiCheck.exe generate [options]

Options:
  -a|--assembly                   Path to the assembly to generate the ApiListing for
  -p|--project                    Path to the project.json file
  --packages                      Path to the nuget packages folder on the machine
  -c|--configuration              Debug or Release
  -epi|--exclude-public-internal  Exclude types on the .Internal namespace from the generated report
  -o|--out                        Output path for the generated ApiListing file
  -h|--help                       Show help information

Usage: .\Microsoft.AspNetCore.BuildTools.ApiCheck.exe compare [options]

Options:
  -b|--ApiListing                 Path to the API listing file to use as reference.
  -e|--exclusions                 Path to the exclusions file for the ApiListing
  -a|--assembly                   Path to the assembly to generate the ApiListing for
  -p|--project                    Path to the project.json file
  --packages                      Path to the nuget packages folder on the machine
  -c|--configuration              Debug or Release
  -epi|--exclude-public-internal  Exclude types on the .Internal namespace from the generated report
  -h|--help                       Show help information

Adding exceptions

When a breaking change is desired, an exclusion file can be used. This file contains a list of exclusions in JSON format where each exclusion is a JSON object with the following properties:

• OldTypeId
• OldMemberId
• NewTypeId
• NewMemberId
• Kind

Type ids correspond to the signature of the type with fully qualified type names and T0, T1, and so on for generic parameters. Member ids correspond to the signature of the member with fully qualified type names and T0, T1, and so on for generic parameters. Kind indicates the type of change, it can be one of two values Modification or Removal.

Below is an example of a breaking change entry.

[
  {
        "OldTypeId": "public static class Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions",
        "OldMemberId": "public static Microsoft.EntityFrameworkCore.Query.IIncludableQueryable<T0, T2> ThenInclude<T0, T1, T2>(this Microsoft.EntityFrameworkCore.Query.IIncludableQueryable<T0, System.Collections.Generic.ICollection<T1>> source, System.Linq.Expressions.Expression<System.Func<T1, T2>> navigationPropertyPath) where T0 : class",
        "NewTypeId": "public static class Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions",
        "NewMemberId": "public static Microsoft.EntityFrameworkCore.Query.IIncludableQueryable<T0, T2> ThenInclude<T0, T1, T2>(this Microsoft.EntityFrameworkCore.Query.IIncludableQueryable<T0, System.Collections.Generic.IEnumerable<T1>> source, System.Linq.Expressions.Expression<System.Func<T1, T2>> navigationPropertyPath) where T0 : class",
        "Kind": "Modification"
  }
]

The exclusions file must live side by side with the baseline file, and it should be named exceptions.net45.json and exceptions.netcore.json for full framework and core framework respectively.

For removing an existing property, both the getter and the setter need to be added to the exceptions file. For instance, to remove public IViewEngine ViewEngine { get; set; }:

[
    {
        "OldTypeId": "public class Microsoft.AspNetCore.Mvc.ViewComponentResult : Microsoft.AspNetCore.Mvc.ActionResult",
        "OldMemberId": "public Microsoft.AspNetCore.Mvc.ViewEngines.IViewEngine get_ViewEngine()",
        "Kind": "Removal"
    },
     {
        "OldTypeId": "public class Microsoft.AspNetCore.Mvc.ViewComponentResult : Microsoft.AspNetCore.Mvc.ActionResult",
        "OldMemberId": "public System.Void set_ViewEngine(Microsoft.AspNetCore.Mvc.ViewEngines.IViewEngine value)",
        "Kind": "Removal"
    }
]