Installation

The zip file can be deployed anywhere via XCopy deployment. No Installation steps are required.

System Requirements
  • .NET Framework 3.5
  • Windows XP or better.
  • (optional) MS Excel 2003 or better if you want to have Excel output.
  • (optional) symchk.exe in your path if you want to use the pdb download functionality. symchk.exe is part of the Windbg package.

Command Reference

Query And Search

Utility Commands

Supporters

ApiChange has been designed with top performance in mind. With the YourKit Memory and Performance profiler no glaring
performance inefficiencies can hide in its code base.

YourKit is kindly supporting open source projects with its full-featured Java Profiler.
YourKit, LLC is the creator of innovative and intelligent tools for profiling .NET and Java applications. Take a look at YourKit's leading software products:
YourKit .NET Profiler and YourKit Java Profiler.

First steps

Start ApiChange.exe from the directory where you did unzip it. It is recommended to set the Console window width to 300 characters to see the command line help nicely formatted..

The command line syntax is a bit awkward but powerful. It is basically a pipeline of queries to find the relevant things. The file selection is done by file queries the type and method selection is done by type and method queries. Most commands are of the form

ApiChange <Find Something> -in <Search for matches in these files>

The <Find Something> is a fuzzy query to select one or more types or methods from one or more assemblies. If you see a cryptic command line like

ApiChange -whousesmethod "String(* IndexOf(*))" gac:\mscorlib.dll -in $net35 -excel


you can read it like this:
  1. Load mscorlib.dll from the Global Assembly Cache. This is a file query which you will see very often.
  2. Load from mscorlib all types which match as type name String. It is actually a type query which can be fuzzy.
  3. For each type match select any overload of IndexOf. I have inserted * as placeholders for return type and method arguments to get all overloads.

The following example shows you can track the usage of all String.Index method calls inside the .NET Framework. From there it is easy to make pivot tables to get valuable insights how the code base is really structured and where the hot users are located.

Example Excel Output

Once you have this list you can generate a graph which assembly uses the String.IndexOf methods most of the time:
String.IndexOf Usage

Now you can get all sort of interesting things out. E.g. you can check how the overload usage distribution of the String.IndexOf methods is

String IndexOf Distribution

Source File/Line Number

When you have the pdbs for the assemblies at hand the tool will try to resolve the file and line information for all found matches so you can directly junp to your source file from the excel output:

Source Code Links

Examples:

  • Download the pdbs for the given binaries from Microsoftsymbol server.
    • ApiChange -getpdbs $net2 c:\net2pdbs
  • Who references System.dll
    • ApiChange -whoreferences $net2dir\System.dll -in $net2
  • Who references System.Configuration.dll located in the GAC.
    • ApiChange -whoreferences gac:\system.configuration.dll -in C:\Windows\Microsoft.NET\Framework\v2.0.50727\*.dll
  • Check after building a dll into the NewDll folder for breaking changes and list all affected targets which need potentially a rebuild.
    • ApiChange -showrebuildtargets -new NewBuild\*.dll -old v1.0\*.dll -searchin v1.0\*.dll -cwd \ProjectDir
  • Find all users of e.g an enum type. It can find practically all enum usage locatons (if,switch case, ...). Locations where the enum is casted to e.g. an int cannot be found (e.g. int v=(int) xxx) because the compiler assigns simply the value to it.
    • ApiChange -whousestype "public enum System.IO.FileShare" $net2dir\mscorlib.dll -in $net2 -excel
  • Check who is using all non constant public fields. Note: Const fields are never used directly. The compiler embeds the const value directly into the target location which makes it impossible to track the usage of const values inside IL code. Instead a source code search should be performed. In case of enums you can track their usage with a -whousestype query to find all enum instance declarations.
    • ApiChange -whousesfield "*(public !const * *)" $net2dir\mscorlib.dll -in $net2 -excel
  • Search for subscribers/unsubscribers from all public types with public events. To check for imbalances you can add the -imbalance switch.
    • ApiChange -whousesevent "public *(public event * *)" GAC:\System.Windows.Forms.dll -in $net2 -excel
  • Search for users of the null string constant. It does search simply for null as substring (case insensitive) in all string constants in all files.
    • ApiChange -ws null -in $net2 -excel

Last edited Sep 9, 2010 at 3:04 PM by Alois, version 14

Comments

No comments yet.