ApiChange

New Post: DiffPrinter.Print internal?

alois — Tue, 05 Apr 2011 21:07:45 GMT

Yes it is an error that the class is public. I did not want to make the diff format static for all times from now on. You can of course copy the code of DiffPrinter which is rather simple. I am sure there are better ways to represent a diff but it does the job.

  public class DiffPrinter
    {
        TextWriter Out;

        /// <summary>
        /// Print diffs to console
        /// </summary>
        public DiffPrinter()
        {
            Out = Console.Out;
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="DiffPrinter"/> class.
        /// </summary>
        /// <param name="outputStream">The output stream to print the change diff.</param>
        public DiffPrinter(TextWriter outputStream)
        {
            if (outputStream == null)
            {
                throw new ArgumentNullException("outputStream");
            }

            Out = outputStream;
        }

        internal void Print(AssemblyDiffCollection diff)
        {
            PrintAddedRemovedTypes(diff.AddedRemovedTypes);

            if (diff.ChangedTypes.Count > 0)
            {
                foreach (var typeChange in diff.ChangedTypes)
                {
                    PrintTypeChanges(typeChange);
                }
            }
        }

        private void PrintTypeChanges(TypeDiff typeChange)
        {
            Out.WriteLine("\t" + typeChange.TypeV1.Print());
            if (typeChange.HasChangedBaseType)
            {
                Out.WriteLine("\t\tBase type changed: {0} -> {1}", 
                    typeChange.TypeV1.IsNotNull( () => 
                        typeChange.TypeV1.BaseType.IsNotNull( () => typeChange.TypeV1.BaseType.FullName)),
                    typeChange.TypeV2.IsNotNull(()=> 
                        typeChange.TypeV2.BaseType.IsNotNull( () => typeChange.TypeV2.BaseType.FullName))
                );
            }

            if (typeChange.Interfaces.Count > 0)
            {
                foreach (var addedItf in typeChange.Interfaces.Added)
                {
                    Out.WriteLine("\t\t+ interface: {0}", addedItf.ObjectV1.FullName);
                }
                foreach (var removedItd in typeChange.Interfaces.Removed)
                {
                    Out.WriteLine("\t\t- interface: {0}", removedItd.ObjectV1.FullName);
                }
            }

            foreach(var addedEvent in typeChange.Events.Added)
            {
                Out.WriteLine("\t\t+ {0}", addedEvent.ObjectV1.Print());
            }

            foreach(var remEvent in typeChange.Events.Removed)
            {
                Out.WriteLine("\t\t- {0}", remEvent.ObjectV1.Print());
            }

            foreach(var addedField in typeChange.Fields.Added)
            {
                Out.WriteLine("\t\t+ {0}", addedField.ObjectV1.Print(FieldPrintOptions.All));
            }

            foreach(var remField in typeChange.Fields.Removed)
            {
                Out.WriteLine("\t\t- {0}", remField.ObjectV1.Print(FieldPrintOptions.All));
            }

            foreach(var addedMethod in typeChange.Methods.Added)
            {
                Out.WriteLine("\t\t+ {0}", addedMethod.ObjectV1.Print(MethodPrintOption.Full));
            }

            foreach(var remMethod in typeChange.Methods.Removed)
            {
                Out.WriteLine("\t\t- {0}", remMethod.ObjectV1.Print(MethodPrintOption.Full));
            }
        }

        private void PrintAddedRemovedTypes(DiffCollection<Mono.Cecil.TypeDefinition> diffCollection)
        {
            if (diffCollection.RemovedCount > 0)
            {
                Out.WriteLine("\tRemoved {0} public type/s", diffCollection.RemovedCount);
                foreach (var remType in diffCollection.Removed)
                {
                    Out.WriteLine("\t\t- {0}", remType.ObjectV1.Print());
                }
            }

            if (diffCollection.AddedCount > 0)
            {
                Out.WriteLine("\tAdded {0} public type/s", diffCollection.AddedCount);
                foreach (var addedType in diffCollection.Added)
                {
                    Out.WriteLine("\t\t+ {0}", addedType.ObjectV1.Print());
                }
            }
        }
    }

Updated Wiki: WhoUsesMethod

Alois — Tue, 05 Apr 2011 20:52:01 GMT

Purpose

This is one of the most popular commands to find all callers of one or many methods. To make it easy you do not have to enter the full method declaration and type name at the command line. Instead a query approach is used to select from a set of assemblies a set of types and from there a set of methods which are matched against the respective file, type and method query. Once the exact type reference is resolved you can search with the -in clause a set of assemblies for callers of the previously found methods.

Parameters

-WhousesMethod <typemethodquery> <declaring file/s> -in <using file/s>
or
-wm <typemethodquery> <declaring file/s> -in <using file/s>

Example

Who is using the Stopwatch Seek Method within the .Net Framework?

ApiChange -whousesmethod "Stopwatch(* Start())" $net2dir\System.dll -in $net2 -excel

The expression "Stopwatch(* Start())" is a combined type and method query. The first is a type query. It can be a fully qualified type name or only the type name. The match is done case insensitive. It is generally of the form

<Visibility> <ClrType> <TypeName>

Visibility can be public | internal
ClrType can be class | interface | struct | enum
TypeName is the full qualified type name or a partial name or only a namespace query. The string after the last . is treated as the actual type name.

Valid Type Queries are

System.Diagnostics.Stopwatch
Stopwatch
stopwatch
stopw*
System.*.Stopwatch
public class *

...

New Post: DiffPrinter.Print internal?

dradovic — Tue, 22 Feb 2011 18:19:40 GMT

I've tried to use the DiffPrinter from my project directly. However, its Print method is internal. Why? The DiffPrinter itself is public but has no public methods - rather useless. Or am I missing something?

Cheers

Reviewed: ApiChange v1.0.0.1 with improved tracing (Feb 22, 2011)

dradovic — Tue, 22 Feb 2011 17:08:25 GMT

Rated 5 Stars (out of 5) - Does exactly the job that I was looking for! We will include in our automatic testing to check that we did not break an API accidentally. Thank you very much for sharing this!!!

Updated Wiki: Documentation

Alois — Thu, 09 Sep 2010 14:04:10 GMT

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:

Load mscorlib.dll from the Global Assembly Cache. This is a file query which you will see very often.
Load from mscorlib all types which match as type name String. It is actually a type query which can be fuzzy.
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.

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

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

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:

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

Updated Wiki: Documentation

Alois — Thu, 09 Sep 2010 14:02:10 GMT

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

First steps

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

you can read it like this:

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

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:

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

Updated Release: ApiChange v1.0.0.1 with improved tracing (Jul 19, 2010)

Alois — Sat, 24 Jul 2010 16:00:20 GMT

Contains improved tracing functionality and API to automatically trace exceptions on method leave as well as the ability to inject faults into your product code without the need to change any product code.

Released: ApiChange v1.0.0.1 with improved tracing (Jul 19, 2010)

Sat, 24 Jul 2010 16:00:20 GMT

Updated Release: ApiChange v1.0.0.1 with improved tracing (Jul 19, 2010)

Alois — Mon, 19 Jul 2010 21:12:58 GMT

Released: ApiChange v1.0.0.1 with improved tracing (Jul 19, 2010)

Mon, 19 Jul 2010 21:12:58 GMT

Source code checked in, #76c98b8c7311

Alois Kraus — Mon, 19 Jul 2010 21:12:16 GMT

Incremented version number

Source code checked in, #b2b2f0f8ced2

Alois Kraus — Mon, 19 Jul 2010 21:04:14 GMT

Added possiblity to inject faults as aspect of tracing to remove the need to alter product code for fault injection.

Source code checked in, #bab74b26ceb8

Alois Kraus — Mon, 05 Jul 2010 20:36:18 GMT

Introduced Exception Severity to enable application wide first chance exception tracing without the need to enable full tracing for all methods.

Source code checked in, #d2442550cbd2

Alois Kraus — Mon, 05 Jul 2010 19:42:50 GMT

Added pointer offsets for 64 bit platforms to get the last thrown exception in all .NET Framework versions from the current thread.

Source code checked in, #c394c5fc3e74

Alois Kraus — Sun, 04 Jul 2010 17:59:17 GMT

Added Exception tracing on method leave.

Updated Wiki: Home

Alois — Sat, 12 Jun 2010 19:24:40 GMT

Mission

This tool is the swiss army knife for developers who want to know whats inside their binaries and who is using it.

You can query your code with a simple command line interface and print the matches to console or pipe it directly to excel to generate nice reports or Pivot tables. If you have the pdbs for your binaries at hand you can directly jump from excel to the matching lines into your code!

The following example shows how you can track the usage of all String.Index method calls inside the .NET Framework. From the excel output you can create pivot tables to get valuable insights how the code base is really structured (e.g. who is using what method how often).

See Documentation for more information how you can query your code base.

Updated Wiki: ShowRebuildTargets

Alois — Tue, 08 Jun 2010 21:06:14 GMT

Purpose

This command does help incremental builds to build only the necessary targets. If you have your own build system (not MSBuild) this could be interesting.

Parameters

-ShowrebuildTargets -new <file/s> -old <file/s> [-old2 <file/s>] -searchin <file/s>
Diff the new files old versus old files. If breaking changes are found search in all -searchin files for affected targets which should be rebuilt.
The file to compare is first searched in the -old file list and then in the -old2 file list.

Example

ApiChange -showrebuildtargets -new NewBuild\*.dll -old v1.0\*.dll -searchin v1.0\*.dll -cwd \ProjectDir

Updated Wiki: ShowRebuildTargets

Alois — Tue, 08 Jun 2010 21:05:51 GMT

Purpose

This command does help incremental builds to build only the necessary targets. If you have your own build system (not MSBuild) this could be interesting.

Parameters

-ShowrebuildTargets -new <file/s> -old <file/s> [-old2 <file/s>] -searchin <file/s>
Diff the new files old versus old files. If breaking changes are found serach in all -searchin files for affected targets which should be rebuilt.
The file to compare is first searched in the -old file list and then in the -old2 file list.

Example

ApiChange -showrebuildtargets -new NewBuild\*.dll -old v1.0\*.dll -searchin v1.0\*.dll -cwd \ProjectDir

Updated Wiki: ShowStrongName

Alois — Tue, 08 Jun 2010 21:02:53 GMT

Purpose

Display the strong name of an assembly.

Parameters

-ShowstrongName <file/s>
Display the strong name of the assembly files

Example

Display the strong name of all .NET Framework assemblies.

ApicCange -sn $net2

Accessibility, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
AspNetMMCExt, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
cscompmgd, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
IEExecRemote, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
IEHost, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
IIEHost, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
Microsoft.Build.Framework, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
Microsoft.Build.Engine, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
Microsoft.Build.Utilities, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
Microsoft.Build.VisualJSharp, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
Microsoft.Build.Tasks, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
Microsoft.VisualBasic.Compatibility.Data, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
Microsoft.VisualBasic.Compatibility, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
...

Updated Wiki: GetPdbs

Alois — Tue, 08 Jun 2010 21:00:15 GMT

Purpose

Download with the symchk command for all binaries the correct symbols beside the binaries. You need to have symchk.exe in your path to make this command work. *Note: You need the 32/64 bit version of symchk depending on your binaries.

Parameters

-GetPdbs <file/s> [PdbStoreDirectory]
If the pdb store directory is omitted the pdbs are downloaded beside the binary. Default is Microsoft (http://msdl.microsoft.com/download/symbols).
You need to set the environment variable %SYMSERVER% to use a different one.

Example

Download the pdbs for the given binaries from Microsoftsymbol server.

ApiChange -getpdbs $net2 c:\net2pdbs

Start downloading symbols.
Estimated download time 1:03 minutes for 159 files from symbol server
...