NDepend

Improve your .NET code quality with NDepend

SOLID Design: The Single Responsibility Principle (SRP)

After having covered The Open-Close Principle (OCP) and The Liskov Substitution Principle (LSP) let’s talk about the Single Responsibility Principle (SRP) which is the S in the SOLID acronym. The SRP definition is:

A class should have a single responsibility and this responsibility should be entirely encapsulated by the class.

This leads to what is a responsibility in software design? There is no trivial answer, this is why Robert C. Martin (Uncle Bob) rewrote the SRP principle this way:

A class should have one reason to change.

This leads to what is a reason to change?

SRP is a principle that cannot be easily inferred from its definition. Moreover the SRP lets a lot of room for own opinions and interpretations. So what is SRP about? SRP is about logic partitioning into code: which logic should be declared in which class. Something to keep in mind is that SRP is the only SOLID principle not related to the usage of abstraction and polymorphism.

The goal of this post is to propose objective and concrete guidelines to increase your classes compliance with SRP, and in-fine, increase the maintainability of your code.

SRP and Concerns

Typically the ActiveRecord pattern is used to exhibit a typical SRP violation. An ActiveRecord class has two responsibilities:

First an ActiveRecord object stores in-memory data retrieved from a relational database.
Second the record is active in the sense that data in-memory and data in the relational database are kept mirrored. For that, the CRUD (Create Read Update Delete) operations are implemented by the ActiveRecord.

To make things concrete an ActiveRecord class can look like that:

public class Employee {
   public string Name { get; set; }
   public string Address { get; set; }
   ...

   public static Employee LoadFromName(string name) {
      //below query will get only a value from DB
      string sqlQuery = "SELECT * FROM Employee WHERE Name = '" + name + "' LIMIT 1;";

      // get value from DB and fill this employee with obtained value
      Employee record = new Employee() { Name =  name, Address = ...};
      return record;
   }

   public bool Create() { 
      // create the record in DB
   }
   public bool Update() {
      // update the record in DB ...
   }
   public bool Delete() { 
      // delete the record in DB ...
   }
}

public class Employee {

public string Name { get; set; }

public string Address { get; set; }

...

public static Employee LoadFromName(string name) {

//below query will get only a value from DB

string sqlQuery = "SELECT * FROM Employee WHERE Name = '" + name + "' LIMIT 1;";

// get value from DB and fill this employee with obtained value

Employee record = new Employee() { Name = name, Address = ...};

return record;

}

public bool Create() {

// create the record in DB

}

public bool Update() {

// update the record in DB ...

}

public bool Delete() {

// delete the record in DB ...

}

If Employee was a POCO class that doesn’t know about persistence and if the persistence was handled in a dedicated persistence layer the API would be improved because:

Not all Employee consumer wants to deal with persistence.
More importantly an Employee consumer really needs to know when an expensive DB roundtrip is triggered: if the Employee class is responsible for the persistence who knows if the data is persisted as soon as a setter is invoked?

Hence better isolate the persistence layer accesses and make them more explicit. This is why at NDepend we promote rules like UI layer shouldn’t use directly DB types that can be easily adapted to enforce any sort of code isolation.

Persistence is what we call a cross-cutting concerns, an aspect of the implementation that tends to spawn all over the code. We can expect that most domain objects are concerned with persistence. Other cross-cutting-concerns we want to separate domain objects from include: validation, log, authentication, error handling, threading, caching. The need to separate domain entities from those cross-cutting concerns can be handled by some OOP pattern like the pattern decorator for example. Alternatively some Object-Relational Mapping (ORM) frameworks and some Aspect-Oriented-Programming (AOP) frameworks can be used.

SRP and Reason to Change

Let’s consider this version of Employee:

public class Employee { 
  public string Name { get; set; }
  public string Address { get; set; } 
  ...
  public void ComputePay() { ... }
  public void ReportHours() { ...}
}

public class Employee {

public string Name { get; set; }

public string Address { get; set; }

...

public void ComputePay() { ... }

public void ReportHours() { ...}

}

The ComputePay() behavior is under the responsibility of the finance people and the ReportHours() behavior is under the responsibility of the operational people. Hence if a financial person needs a change to be implemented in ComputePay() we can assume this change won’t affect the ReportHours() method. Thus according to the version of SRP that states “a class should have one reason to change”, it is wise to declare these methods in different dedicated modules. As a consequence a change in ComputePay() has no risk to affect the behavior of ReportHours() and vice-versa. In other words we want these two parts of the code to be independent because they will evolve independently.

This is why Robert C. Martin wrote that SRP is about people : make sure that logics controlled by different people are implemented in different modules.

SRP and High-Cohesion

The SRP is about encapsulating logic and data in a class because they fit well together. Fit well means that the class is cohesive in the sense that most methods use most fields. Actually cohesion of a class can be measured with the Lack of Cohesion Of Methods (LCOM) metric. See below an explanations of LCOM (extracted from this great Stuart Celarier placemat) What matters is to understand that if all methods of a class are using all instances fields, the class is considered utterly cohesive and has the best LCOM score, which is 0 or close to 0.

Typically the effect of a SRP violation is to partition a class methods and fields into groups with few connections. The fields needed to compute the pay of an employee are not the same than the fields needed to report pending work. This is why the LCOM metric can be used to measure adherence to SRP and take actions. You can use the rule Avoid types with poor cohesion to track classes with poor cohesion between methods and fields.

SRP and Fat Code Smells

While we can hardly find an easy definition for what is a responsibility we noticed that adhering to SRP usually results in classes with a good LCOM score. On the other hand, not adhering to SRP usually leads to the God class phenomenon: a class that knows too much and does too much. Such god class is usually too large: violations of rules like Avoid types too big, Avoid types with too many methods, Avoid types with too many fields are good candidate to spot god classes and refactor into a finer-grained design.

Guidelines to adhere to SRP

Here are a set of objective and concrete guidelines to adhere to SRP:

Domain classes must be isolated from Cross-Cutting Concerns: code responsible for persistence, validation, log, authentication, error handling, threading, caching…
When implementing your domain, favor POCO classes that do not have any dependency on an external framework. Note that a POCO class is not necessarily a fields and properties only class, but can implement logic/behavior related to its data.
Use your understanding of the Domain to partition code: logics related to different business functions should be kept separated to avoid interference.
Regularly check the Lack of Cohesion Of Methods (LCOM) score of your classes.
Regularly check for too large and too complex classes.

SOLID Design: The Open-Close Principle (OCP)

The Open-Close principle (OCP) is the O in the well known SOLID acronym.

Bertrand Meyer is generally credited for having originated the term open/closed principle, which appeared in his 1988 book Object Oriented Software Construction. Its original definition is

A module will be said to be open if it is still available for extension. For example, it should be possible to add fields to the data structures it contains, or new elements to the set of functions it performs.
A module will be said to be closed if it is available for use by other modules. This assumes that the module has been given a well-defined, stable description (the interface in the sense of information hiding)

Upon these definitions the principle is usually expressed and summarized this way:

Modules should be open for extension and closed for modification.

There have been (and still are) a lot of debates about the meaning of this simple definition and its implication on the usage of Object-Oriented Programming (OOP) in the real-world.

In this post I’ll try to be as concrete and concise as possible.

The classical code example to explain OCP

The classical code example to explain OCP can be translated in C# this way:

public class Circle { }

public class Square { }

public static class Drawer {
   public static void DrawShapes(IEnumerable<object> shapes) {
      foreach (object shape in shapes) {
         if (shape is Circle) {
            DrawCircle(shape as Circle);
         } else if (shape is Square) {
            DrawSquare(shape as Square);
         }
      }
   }
   private static void DrawCircle(Circle circle) { /*Draw circle*/ }

   private static void DrawSquare(Square square) { /*Draw Square*/ }
}

public class Circle { }

public class Square { }

public static class Drawer {

public static void DrawShapes(IEnumerable<object> shapes) {

foreach (object shape in shapes) {

if (shape is Circle) {

DrawCircle(shape as Circle);

} else if (shape is Square) {

DrawSquare(shape as Square);

}

private static void DrawCircle(Circle circle) { /*Draw circle*/ }

private static void DrawSquare(Square square) { /*Draw Square*/ }

}

I find this example a bit gross. I believe one must have no idea of what OOP is to write such code. It can obviously be refactored to something like this:

public interface IShape { void Draw(); }

public class Circle : IShape { public void Draw() { /*Draw circle*/ }}

public class Square : IShape { public void Draw() { /*Draw Square*/ } }

public static class Drawer {
   public static void DrawShapes(IEnumerable<IShape> shapes) {
      foreach (IShape shape in shapes) {
         shape.Draw();
      }
   }
}

public interface IShape { void Draw(); }

public class Circle : IShape { public void Draw() { /*Draw circle*/ }}

public class Square : IShape { public void Draw() { /*Draw Square*/ } }

public static class Drawer {

public static void DrawShapes(IEnumerable<IShape> shapes) {

foreach (IShape shape in shapes) {

shape.Draw();

}

Let’s look at the implication of this refactoring:

We introduced a new abstraction IShape to represent a concept that we already had in mind. Indeed, in the first code sample the method DrawShapes() already accepted a sequence of shapes. With the new IShape abstraction our design is now open to accept more shapes like Triangle or Pentagone.
The method DrawShapes() will draw any new shape without any need for modification. In other words the DrawShapes() method implementation is closed.

Here is how the OCP is usually presented. It is all about anticipating the future changes in the system in a way that:

When a change occurs existing code is left untouched. Existing code here is DrawShapes() concrete method body, IShape interface and Circle and Square classes.
When a change occurs new code to implement changes is written in new classes that implement existing abstraction. New classes here could be Triangle and Pentagone.

The Point of Variation principle

Another way to see the OCP is the Point of Variation (PV) principle that states:

Identify points of predicted variation and create a stable interface around them.

I find PV more understandable than OCP because it is actionable. First identify potential variations, second build the proper abstractions around these variations.

The real challenge: Anticipation

But the real challenge is anticipation, anticipating is hard. If anticipation was easy we’d be all billionaire in bitcoins. In real world, when you anticipate the risk is high that:

We do anticipate variations that won’t vary. This is what the YAGNI principle says (You aren’t gonna need it): Always implement things when you actually need them, never when you just foresee that you need them. Developing and maintaining an abstraction has a cost and if we won’t need it this cost is negative.
The risk is also high that we don’t anticipate the variation that will really be needed. But once the need for variation becomes real this is your developer responsibility to refactor and create the right abstractions and the right stable code that will act upon these abstractions. This is the fool me once, don’t fool me twice idea: I am not supposed to foresee what I’ll need but I am supposed to identify and then write the right abstraction when I need it.

OCP in the real world

Here is a pragmatic approach to OCP:

In any case the KISS principle applies (Keep It Simple Stupid): don’t underestimate the difficulty of anticipating and don’t waste your resources creating abstractions you won’t need.
Write automatic tests: one of the greatest benefit of writing tests is that for a while, you must look at your code from the client perspective. If your code contains some area difficult to cover by tests, it certainly means that your code should be refactored to be easily 100% testable. Experience shows that when refactoring from poorly testable code to fully testable code, the need for right abstractions naturally pops up.
Some static analyzers can help you pinpoint typical OCP violations:
- when downcasting reference (i.e casting from a base class or interface to a subclass or leaf class.),
- when using the is or as operators (as in the first example above).
- NDepend has the rule Base class should not use derivatives: matches of this rules are obvious violation of the OCP.

Keep in mind the fool me once, don’t fool me twice idea. You must refactor code as soon as the need to abstract some concepts is identified. Of course sometime it is not possible if tons of client code depend upon your API: in this situation you cannot easily refactor and often you’ll have to live with wrong design. This is why public API design is such a sensitive topic: you have no other choice than doing your best to anticipate and to accept to live with your past design mistake.

Be open to more than one variation with the Visitor pattern

Finally let’s underline that in the real world, data objects (like the shapes here) don’t implement themselves algorithm such as drawing. Experience tells that this is a clear violation of OCP because when a new algorithm is needed on data objects, like persistence in addition of drawing for example, all shape classes must be modified again. This is also a violation of the Single Responsibility Principle (SRP, the S in SOLID) because a shape class has now two responsibilities: 1) holding the shape data 2) drawing the shape.

Hence we now have two variations: we need a way to abstract both the shapes and the algorithms applied on the shapes, in order to to write something like algorithm.ApplyOn(shape). This sort of call on two abstractions is named a double dispatching call: the implementation really invoked depends both on the IShape object’s type and the IAlgorithm object’s type. If you have N shapes and M algorithms you need [N x M] implementations.

Fortunately the visitor pattern helps implementing double dispatching. The code with the new persistence algorithm would then look like:

//
// Shapes elements
//
public interface IShape { void Accept(IVisitor visitor); }
public class Circle : IShape {
   public void Accept(IVisitor visitor) { visitor.Visit(this); }
}
public class Square : IShape {
   public void Accept(IVisitor visitor) { visitor.Visit(this); }
}

//
// Visitors algorithms on shapes elements
// don't use the IAlgorithm terminology to keep up with the classical visitor pattern terminology
//
public interface IVisitor {
   void Visit(Circle circle);
   void Visit(Square square);
}
public class DrawAlgorithm : IVisitor {
   public void Visit(Circle circle) { /*Draw circle*/}
   public void Visit(Square square) { /*Draw square*/}
}
public class PersistAlgorithm : IVisitor {
   public void Visit(Circle circle) { /*Persist circle*/}
   public void Visit(Square square) { /*Persist square*/}
}

public static class Program {
   public static void ApplyVisitorAlgorithmOnShapesElements(IEnumerable<IShape> shapes, IVisitor visitor) {
      foreach (IShape shape in shapes) {
         // Double dispatching:
         //   shape can be both: Circle or Square
         //   visitor can be both Draw or Persist
         shape.Accept(visitor);  
      }
   }
}

// Shapes elements

public interface IShape { void Accept(IVisitor visitor); }

public class Circle : IShape {

public void Accept(IVisitor visitor) { visitor.Visit(this); }

}

public class Square : IShape {

public void Accept(IVisitor visitor) { visitor.Visit(this); }

}

// Visitors algorithms on shapes elements

// don't use the IAlgorithm terminology to keep up with the classical visitor pattern terminology

public interface IVisitor {

void Visit(Circle circle);

void Visit(Square square);

}

public class DrawAlgorithm : IVisitor {

public void Visit(Circle circle) { /*Draw circle*/}

public void Visit(Square square) { /*Draw square*/}

}

public class PersistAlgorithm : IVisitor {

public void Visit(Circle circle) { /*Persist circle*/}

public void Visit(Square square) { /*Persist square*/}

}

public static class Program {

public static void ApplyVisitorAlgorithmOnShapesElements(IEnumerable<IShape> shapes, IVisitor visitor) {

foreach (IShape shape in shapes) {

// Double dispatching:

// shape can be both: Circle or Square

// visitor can be both Draw or Persist

shape.Accept(visitor);

}

SOLID design: The Liskov Substitution Principle (LSP)

The Liskov substitution principle is the L in the well known SOLID acronym. The original principle definition is:

Methods that use references to base classes must be able to use objects of derived classes without knowing it.

At first glance this principle is pretty easy to understand. At second glance it seems redundant with the OOP concept of polymorphism. After all, the whole point of polymorphism is to consume an abstraction without knowing the implementation behind isn’t it?

However it is a good thing that the community emphases the Liskov substitution principle. This principle is in fact a caveat for developers that polymorphism is both powerful and tricky : in the real world, the usage of polymorphism often leads to a dead-end situation, it must be wisely used.

LSP is often summarized with a counter-example of Duck Test: “If it looks like a duck, quacks like a duck, but needs batteries – you probably have the wrong abstraction”

Let’s details some common polymorphism pitfalls that the Liskov substitution principle attempts to prevent by reminding the developer to adopt the client perspective.

Prevent situations where a method cannot be implemented

When a class implements an interface or derives from a base class, refactor tooling like Visual Studio refactor tools, Resharper or CodeRush propose to insert abstract methods stubs to implement. Typically the default body of such inserted method is throw NotImplementedException().

Obviously this behavior must remain temporary and must not be released in production. Client code that hold a reference on the interface or the base class doesn’t expect to get a NotImplementedException raised upon a method call. This is why NDepend has a default rule named Do implement methods that throw NotImplementedException, to prevent such situation.

On the other hand, if it doesn’t make sense to implement an abstract method, it clearly means that the design is wrong. Here is such wrong design, assuming that all birds can fly:

   public abstract class Bird {
      public abstract void Fly();
   }
   public class Parrot : Bird {
      public override void Fly() { throw new NotImplementedException(); } // To implement
   }
   public class Ostrich : Bird {
      public override void Fly() { throw new NotImplementedException(); } // How to implement this, Ostrih can't fly??
   }

public abstract class Bird {

public abstract void Fly();

}

public class Parrot : Bird {

public override void Fly() { throw new NotImplementedException(); } // To implement

}

public class Ostrich : Bird {

public override void Fly() { throw new NotImplementedException(); } // How to implement this, Ostrih can't fly??

}

This code could then be refactored to:

   public abstract class Bird {
   }
   public abstract class FlyingBird : Bird {
      public abstract void Fly();
   }
   public class Parrot : FlyingBird {
      public override void Fly() { throw new NotImplementedException(); }
   }
   public class Ostrich : Bird {
   }

public abstract class Bird {

}

public abstract class FlyingBird : Bird {

public abstract void Fly();

}

public class Parrot : FlyingBird {

public override void Fly() { throw new NotImplementedException(); }

}

public class Ostrich : Bird {

}

The problem was that Bird with its Fly() method was too coarse, we needed some refinement because not all bird can fly. From my experience such wrong assumptions on interfaces and base classes happen quite often in the real world. When you stumble on such situation, see it as a good starting point for refactoring … if possible. Indeed, sometime refactoring is not an option if many clients depend already on the wrong design.

Example of a LSP violation in the .NET framework design

One dreaded LSP violation is .NET System.Array implementing the ICollection<T> interface. Hence Array has to implement the ICollection<T>.Add() method but calling this method on an array throws at runtime a NotSupportedException:

The C# compiler doesn’t even warn on such simple erroneous program.

Of course we’d need to ensure that ICollection<T>.IsReadOnly is false before modifying a collection through a reference of IList<T> or a ICollection<T> but frankly this is an error-prone design. I can remember having stumbled on this situation quite a few times during the last 15 years I am programming with C#/.NET.

Moreover refactoring this original design mistake is not an option anymore, even when .NET Core was introduced, since millions of programs are relying on this API. IReadOnlyCollection<T> has been introduced with .NET v4.5 in 2012 but the original design cannot be changed.

Think twice before applying the ISA trick

Another common example to explain the Liskov substitution principle is the Rectangle/Square paradigm. A square is-a rectangle isn’t it? So we should be able to write such code:

   public class Rectangle {
      public virtual int Width { get; set; }
      public virtual int Height { get; set; }
   }
   public class Square : Rectangle {
      // Need to make sure that a Square width and height remain equal!
      public override int Width { set { this.Width = value; this.Height = value; } }
      public override int Height { set { this.Height = value; this.Width = value; } }
   }
   public void Method(Rectangle rect) {
     rect.Width = 2;
     rect.Height = 3;
     Debug.Assert(rect.Width == 2); // If rect references a Square object this legitimate client assertion is violated!!!
   }

public class Rectangle {

public virtual int Width { get; set; }

public virtual int Height { get; set; }

}

public class Square : Rectangle {

// Need to make sure that a Square width and height remain equal!

public override int Width { set { this.Width = value; this.Height = value; } }

public override int Height { set { this.Height = value; this.Width = value; } }

}

public void Method(Rectangle rect) {

rect.Width = 2;

rect.Height = 3;

Debug.Assert(rect.Width == 2); // If rect references a Square object this legitimate client assertion is violated!!!

}

Clearly this is a wrong usage of the ISA principle: yes a square is a rectangle but the client doesn’t expect that when modifying the height of the rectangle, the width gets modified also.

Here also such wrong design emerges quite often in the real world. For example when dealing with a complex control hierarchy with dozens of fields to maintain at various level, it can become quite tricky to maintain coherence in your objects’ states at runtime.

Code Contract to help?

In theory code contract could help here. A contract is one or several assertions that prevent corrupted state. When a corrupted state is reached at runtime (whether in production or at test run time), such assertion must deadly fail because continuing running with corrupted state can potentially lead to more corrupted states.

Often contracts are used at interface level to improve the semantic by adding constraints to classes that implement the interface. We might want to force all implementations of IRectangle.set_Width to let the Height value untouched. By using Microsoft Code Contracts we could try to write something like that:

using System.Diagnostics.Contracts;

[ContractClass(typeof(IRectangleContract))]
public interface IRectangle {
   int Width { get; set; } 
   int Height { get; set; }
}

[ContractClassFor(typeof(IRectangle))]
public class IRectangleContract : IRectangle {
   public int Width { get;
      set { Contract.PreserveValue(this.Height), "Height must not be changed when assigning Width"); }
   }
   public int Height { get;
      set { Contract.PreserveValue(this.Width), "Width must not be changed when assigning Height"); }
   }
}

using System.Diagnostics.Contracts;

[ContractClass(typeof(IRectangleContract))]

public interface IRectangle {

int Width { get; set; }

int Height { get; set; }

}

[ContractClassFor(typeof(IRectangle))]

public class IRectangleContract : IRectangle {

public int Width { get;

set { Contract.PreserveValue(this.Height), "Height must not be changed when assigning Width"); }

}

public int Height { get;

set { Contract.PreserveValue(this.Width), "Width must not be changed when assigning Height"); }

}

Unfortunately, as far as I know, Microsoft Code Contracts has no support for such PreserveValue() possibility. More generally it seems that Microsoft Code Contracts doesn’t receive much love nowadays despite how useful code contract can be. Ok C#8 non-nullable reference addresses many of the situations usually verified through contracts or assertions, but not all contracts are about nullable reference, as this example suggests.

Use polymorphism with great caution

These classical Bird and Rectangle examples show well how polymorphism and inheritance can quickly lead to rotten design, even in apparently simple situations. The Array class implementing ICollection<T> situation shows that in practice LSP violations just happen.

In my point of view, what the Liskov substitution principle really says is that when writing an API relying on polymorphism, you should first take the point of view of the client of your API before writing any interface and any class hierarchy.

Do really all birds can fly? What happen if I try to call Fly() on a bird that cannot fly?
Is a square really a rectangle? What happen if I change the width on a square?

In the real world this looks like:

Can all collections really be modified? What happen if I add or remove an element to an array?
Do all controls are scrollable? What happen if a scrollbar is displayed on a control that should not scroll?
Do withdrawal applies to all bank account? What happen if we try to withdraw money from a locked long term deposit account? Should we fail withdrawal badly in this situation or should we prevent such situation with an IAccountThatAuthorizeWithdraw abstraction?

A pattern emerges here: for each members of your interface you should question yourself: Do this member applies seamlessly to all objects that will implement this interface?

Notice that API writing principle is more general, it doesn’t only apply to polymorphism: when writing an API first take the point of view of the client of your API. This is the only way to achieve elegant API that clients will love to consume. This is another way to explain Test-Driven Development (TDD), where client code must be written for test and design purposes before writing the code itself.

In a previous post I explained why your classes should be declared as sealed when possible and why NDepend proposes the default rule Class with no descendant should be sealed if possible. In the real world, a class is never well designed for inheritance by chance and thus should be sealed by default. Designing well a class for inheritance requires quite an extensive understanding of your domain. As for everything in life, it requires a lot of effort to build something that others will find easy to use.

Identify .NET Code Structure Patterns with no Effort

The two pillars of code maintainability are automatic testing and clean code structure.

Testing is used to regularly challenge code correctness and detect regression early. Testing can be easily assessed with numbers like code coverage ratio and the amount of assertions tested.
A clean code structure prevents the phenomenon of spaghetti code, entangled code that is hard to understand and hard to maintain. However assessing the code structure cannot be achieved through numbers like for testing. Moreover the structure emerges from a myriad of details buried in many source files and thus appropriate tooling is needed.

For most engineers, code dependency graph is the tool of choice to explore code structure. Boxes and arrows graph is intuitive and well adapted to visualize a small amount of dependencies. However to visualize complex portion of code the Dependency Structure Matrix (DSM) is more adapted. See below the same set of 34 namespaces visualized with the NDepend Dependency Graph and the NDepend Dependency Matrix.

If the concept of dependency matrix is something new to you, it is important to note that:

The Matrix headers’ elements represent graph boxes
The Matrix non-empty cells correspond to graph arrows. Numbers on the cells represents a measure of the coupling in terms of numbers of methods and fields involved. In a symmetric matrix a pair of blue and green cell is symmetric because both cells represents the same thing: the blue cell represents A uses B and the green cells represents B is used by A.

Here is a 5 minutes introduction video if you are not familiar with the dependency matrix:

Clearly the graph is more intuitive, but apart the two red arrows that represent two pairs of namespaces mutually dependent this graph tells few things about the overall structure.

On the other hand the matrix algorithm naturally attempts to layer code elements, exhibit dependency cycles, shows which element is used a lot or not… Let’s enumerate some structural patterns that can be visualized at a glance with the dependency matrix:

Layers

One pattern that is made obvious by a DSM is layered structure (i.e acyclic structure). When the matrix is triangular, with all blue cells in the lower-left triangle and all green cells in the upper-right triangle, then it shows that the structure is perfectly layered. In other words, the structure doesn’t contain any dependency cycle.

On the right part of the snapshot, the same layered structure is represented with a graph. All arrows have the same left to right direction. The problem with graph, is that the graph layout doesn’t scale. Here, we can barely see the big picture of the structure. If the number of boxes would be multiplied by 2, the graph would be completely unreadable. On the other side, the DSM representation wouldn’t be affected; we say that the DSM scales better than graph.

Notice that NDepend proposes 2 rules out of the box to control layering by preventing dependency cycles to appear: ND1400 Avoid namespaces mutually dependent and ND1401 Avoid namespaces dependency cycles.

Interestingly enough, most of graph layout algorithms rely on the fact that a graph is acyclic. To compute layout of a graph with cycles, these algorithms temporarily discard some dependencies to deal with a layered graph, and then append the discarded dependencies at the last step of the computation.

Cycles

If a structure contains a cycle, the cycle is displayed by a red square on the DSM. We can see that inside the red square, green and blue cells are mixed across the diagonal. There are also some black cells that represent mutual direct usage (i.e A is using B and B is using A).

The NDepend’s DSM comes with the option Indirect Dependency. An indirect dependency between A and B means that A is using something, that is using something, that is using something … that is using B. Below is shown the same DSM with a cycle but in indirect mode. We can see that the red square is filled up with only black cells. It just means that given any element A and B in the cycle, A and B are indirectly and mutually dependent.

Here is the same structure represented with a graph. The red arrow shows that several elements are mutually dependent. But the graph is not of any help to highlight all elements involved in the parent cycle.

Notice that in NDepend, we provided a button to highlight cycles in the DSM (if any). If the structure is layered, then this button has for effect to triangularize the matrix and to keep non-empty cells as closed as possible to the diagonal.

High Cohesion / Low-Coupling

The idea of high-cohesion (inside a component) / low-coupling (between components) is popular nowadays. But if one cannot measure and visualize dependencies, it is hard to get a concrete evaluation of cohesion and coupling. DSM is good at showing high cohesion. In the DSM below, an obvious squared aggregate around the diagonal is displayed. It means that elements involved in the square have a high cohesion: they are strongly dependent on each other although. Moreover, we can see that they are layered since there is no cycle. They are certainly candidate to be grouped into a parent artifact (such as a namespace or an assembly).

On the other hand, the fact that most cells around the square are empty advocate for low-coupling between elements of the square and other elements.

In the DSM below, we can see 2 components with high cohesion (upper and lower square) and a pretty low coupling between them.

While refactoring, having such an indicator can be pretty useful to know if there are opportunities to split coarse components into several more fine-grained components.

Too many responsibilities

The popular Single Responsibility Principle (SRP) states that: a class shouldn’t have more than one reason to change. Another way to interpret the SRP is that a class shouldn’t use too many different other types. If we extend the idea at other level (assemblies, namespaces and method), certainly, if a code element is using dozens of other different code elements (at same level), it has too many responsibilities. Often the term God class or God component is used to qualify such piece of code.

DSM can help pinpoint code elements with too many responsibilities. Such code element is represented by columns with many blue cells and by rows with many green cells. The DSM below exposes this phenomenon.

Popular Code Elements

A popular code element is used by many other code elements. Popular code elements are unavoidable (think of the String class for example).

A popular code element is not a flaw. However it is advised that popular elements are interfaces and enumerations. This way consumers rely on abstractions and not on implementations details. The benefit is that consumers are less often broken because abstraction are less subject to change than implementations.

A popular code element is represented by columns with many green cells and by rows with many blue cells. The DSM below highlights a popular code element.

Something to notice is that when one is keeping its code structure perfectly layered, popular components are naturally kept at low-level. Indeed, a popular component cannot de-facto use many things, because popular component are low-level, they cannot use something at a higher level. This would create a dependency from low-level to high-level and this would break the acyclic property of the structure.

Mutual dependencies

You can see the coupling between 2 components by right clicking a non-empty cell, and select the menu Open this dependency.

If the opened cell was black as in the snapshot above (i.e if A and B are mutually dependent) then the resulting rectangular matrix will contains both green and blue cells (and eventually black cells as well) as in the snapshot below.

In this situation, you’ll often notice a deficit of green or blue cells (3 blue cells for 1 green cell here). It is because even if 2 code elements are mutually dependent, there often exists a natural level order between them. For example, consider the System.Threading namespaces and the System.String class. They are mutually dependent; they both rely on each other. But the matrix shows that Threading is much more dependent on String than the opposite (there are much more blue cells than green cells). This confirms the intuition that Threading is upper level than String.

Ensure that your classes are declared as sealed when possible

Inheritance is one of the pillar of OOP. However, in the real world, most classes are not designed to be properly inheritable.

Properly designing a class to be inheritable is a tricky task. One must anticipate state initialization, state correctness, state mutability and also non-public methods calls from descendants. Anticipating well code re-use is hard and this requires experience. As a consequence there is no chance that a class gets well designed for inheritance by chance.

However, in both C# and VB.NET, a class is by default inheritable. The C# keyword sealed and the VB.NET keyword NotInheritable must be specified explicitly. Since there is no compiler warning most developers don’t bother to seal their classes. Hence most classes are not properly designed for inheritance but are implicitly declared as inheritable.

As if writing high quality code was not complicated enough here we have a language pitfall.

This is why NDepend proposes the default rule Class with no descendant should be sealed if possible. The CQLinq source code of this rule is pretty obvious:

// <Name>Class with no descendant should be sealed if possible</Name>
// <Id>ND1203:ClassWithNoDescendantShouldBeSealedIfPossible</Id>
warnif count > 0 from t in JustMyCode.Types where 
  t.IsClass && 
  t.NbChildren ==0 && 
 !t.IsSealed && 
 !t.IsStatic && 
 !t.IsPubliclyVisible // You might want to comment this condition 
                      // if you are developing an application,
                      // instead of developing a library
                      // with public classes that are intended to be 
                      // sub-classed by your clients.
  orderby t.NbLinesOfCode descending
select new {
   t,
   t.NbLinesOfCode,
   Debt = 30.ToSeconds().ToDebt(),
   Severity = Severity.Medium
}

// <Name>Class with no descendant should be sealed if possible</Name>

// <Id>ND1203:ClassWithNoDescendantShouldBeSealedIfPossible</Id>

warnif count > 0 from t in JustMyCode.Types where

t.IsClass &&

t.NbChildren ==0 &&

!t.IsSealed &&

!t.IsStatic &&

!t.IsPubliclyVisible // You might want to comment this condition

// if you are developing an application,

// instead of developing a library

// with public classes that are intended to be

// sub-classed by your clients.

orderby t.NbLinesOfCode descending

select new {

t.NbLinesOfCode,

Debt = 30.ToSeconds().ToDebt(),

Severity = Severity.Medium

}

As explained in the rule’s comments, you won’t get warnings per default for public non-sealed classes with no descendants. Indeed, it might be well that the analyzed code base is a framework and that descendants of such classes are not available at the time of analysis. But if the code base analyzed is an application with no public API it is important to comment this clause and get most public classes declared as sealed.

If you are not convinced that most classes should be sealed, there are also non-obvious reasons. Here is a quote from Jeffrey Richter from his essential book CLR via C#:

When defining a new type, compilers should make the class sealed by default so that the class cannot be used as a base class. Instead, many compilers, including C#, default to unsealed classes and allow the programmer to explicitly mark a class as sealed by using the sealed keyword. Obviously, it is too late now, but I think that today’s compilers have chosen the wrong default and it would be nice if it could change with future compilers. There are three reasons why a sealed class is better than an unsealed class:

Versioning: When a class is originally sealed, it can change to unsealed in the future without breaking compatibility. (…)

Performance: (…) if the JIT compiler sees a call to a virtual method using a sealed types, the JIT compiler can produce more efficient code by calling the method non-virtually.(…)

Security and Predictability: A class must protect its own state and not allow itself to ever become corrupted. When a class is unsealed, a derived class can access and manipulate the base class’s state if any data fields or methods that internally manipulate fields are accessible and not private.(…)

In the same vein you can also refer to this Eric Lippert 2004 post where he explains why most .NET Framework classes are sealed per default.

The continuous adaptation of Visual Studio extensions

One could think that developing an extension for a two-decades+ product as mature as Visual Studio is headache-less.

Not really. Visual Studio is a big big beast used by millions of professional developers daily. Versions after versions Microsoft is spending an astounding amount of effort to improve it and make sure it respects the latest standard in terms of dev platforms, IDE features, usability and performance.

This implies a lot of deep changes and all VS extensions must adapt to these changes … or die. Most of this adaptation efforts come from the support of new platforms (.NET Core, Xamarin, upcoming .NET 5…) but here I’d like to focus on VS integration recent changes.

Deferred extensions loading

On Monday 11th December 2017 all VS partners received an mail announcing VS package deferred loading, also referred to extension asynchronous initialization. In this mode VS extensions are loaded after VS startup and initialization. As a consequence VS startup is not slowed down by extensions.

Implementing this scenario required serious changes described here but this deferred loading scenario became mandatory only with VS 2019.1 (16.1) released this spring 2019, around 18 months later after the initial announcement. VS extension ISVs got plenty of time (and plenty of high quality support from Microsoft engineers) to implement and test this async loading scheme.

VS2019 Extensions Menu

In February 2019, we were developing the support of NDepend for VS 2019 and were downloading the latest VS2019 preview, installed our NDepend extension and immediately noticed there were no more NDepend global menu? After investigation we saw our NDepend main menu, and other extensions menus, under a new Extensions menu –with no possibility to get back extensions menu in the main bar–.

This change impacts millions of extensions users and hundreds of partners ISVs but has never been announced publicly ahead nor debated. As an immediate consequence someone asked to get rid of this new Extensions menu and this generated a long list of complains.

I guess this major (and blunt) change was provoked initially by the VS2019 compact menu look, but I am not sure: even on a 1920 pixel wide monitor (DPI 100%) there is still plenty of width space to show extension menus.

Visual Studio 2019 Compact Menu

Sometime in April 2019 someone anonymously published on the discussion the link to a new extension to put back extensions main menus in the main bar.

I guess the VS APIs used to achieve this magic are not well documented, hence we can wonder if this initiative comes from MS or not? At least now users can get back their extensions menus in the main bar. But the Extensions in Main Menus extension has been downloaded only 800 times in around 3 months. It means only a tiny subset of VS extension users are aware of it and are actually using it.

Personally I still have hope Microsoft will reconsider this move and will embed a similar option in a future VS version to let the users chose which features (out-of-the-box VS feature or extension feature) deserves a no-brainer/main bar access or not.

VS2019 Optimize rendering for screens with different pixel densities

We published NDepend v2019.2.0 on 14th March 2019 with proud support for VS2019 and .NET Core 3. Two weeks later a user reported severe UI bugs we’ve never observed. The repro scheme was easy:

install .NET Fx 4.8,
enable the new VS2019 option Optimize rendering for screens with different pixel densities
run VS2019 with the NDepend extension in a multi-monitors environment with various DPI scale for each monitor

Optimize rendering for screens with different pixel densities

We then discussed with VS engineers. They pointed us to this documentation and kindly offered quite a few custom advices: Per-Monitor Awareness support for Visual Studio extenders

Actually this change is pretty deep for (the tons of) WPF and Winforms controls rendered in the Visual studio UI. This took us time but we just released on July 3rd 2019 NDepend v2019.2.5 with full support for this Optimize rendering for screens with different pixel densities option. This required quite tricky fixes and we’d wish we have had a few months to adapt to this major breaking changes as we had for deferred loading explained above. As far as I know extensions ISVs were not informed in advance. On the other hand I’d like to underline the awesome support we got from Visual Studio engineers (as always actually) thanks again to all of them.

I noticed that Resharper pops up a dialog at VS2019 starting time (not sure if they got all fixed at the time of writing).

Resharper Message related to Optimize rendering for screens with different pixel densities

I also noticed that up to VS2019 16.1.3 there were still some bugs in the VS UI, see the Project Properties and Diagnostics Tool windows below. I just tried with 16.1.5 and it seems fixed.

My point is that this great improvement (Optimize rendering for screens with different pixel densities) should have been highlighted ahead during VS2019 preview time to avoid a wide range of UI bugs experienced by users during the early months of VS2019 RTM.

What can we expect next?

With .NET 5 public announcement on May 6th 2019 the .NET community now knows that sooner or later most of .NET Core or .NET Fx applications will have to be migrated to benefit from latest innovations and improvements.

Hopefully .NET Core apps migration will be quite straightforward since .NET 5 is .NET Core vNext. But .NET Fx apps migration will be (more or less) painful. Although WPF and Winforms desktop APIs are already supported by .NET Core 3, some others major APIs are not – and won’t be – supported (ASP.NET Web Forms, WCF, Windows Workflow, .NET Remoting, AppDomain…).

For too complex migration plans here is the Microsoft recommendation: What do you do with your older applications that you are not spending much engineering time on? We recommend leaving these on .NET Framework. (…) .NET Framework will continue to be supported and will receive minor updates. Even here at Microsoft, many large products will remain on .NET Framework. There are absolutely no changes to support and that will not change in the future. .NET Framework 4.8 is the latest version of .NET Framework and will continue to be distributed with future releases of Windows. If it is installed on a supported version of Windows, .NET Framework 4.8 will continue to be supported too.

Visual Studio 2019 is still running in a 32 bits process upon the .NET Fx 4 CLR with a massive WPF based UI and some COM usage.

Can we expect VS2019 to run on .NET 5 sometime in 2021? or in a later version? or never?

Only the future will tell but I hope extension VS ISVs will be advised ahead to anticipate the migration and continue to offer a seamless integration experience to users.

Simplifying a Visual Studio extension menu: A Case Study

NDepend version 2019.2.1 has just been released. This new version proposes a simplified menu for the NDepend Visual Studio extension.

Before going further I underline that we didn’t get rid of the standard menu, the user can switch back and forth simplified and standard menu within a single click. There is something in UI that all users worldwide dislike: don’t force a new UI just for the sake of it.

The simplified menu is shown per default on machines that never ran NDepend, else the standard menu is shown. Here is a view of the simplified/beginner menu vs. the standard/advanced menu.

NDepend simplified/beginner menu vs. standard/advanced menu

We introduced a simplified menu because we think that trial users and beginner users will benefit from it. Having most features available through a single level menu certainly makes the product features more discoverable.

More and Tools popup menus

A More… popup menu is here to show features and actions that are typically used less often. It is a UI trade off to force an extra-click to access these actions:

The Tools popup menu is an opportunity to switch to the advanced menu, and see the NDepend Start Page. It is also good to discover NDepend tooling outside Visual Studio, the standalone VisualNDepend.exe, NDepend API and OSS Power Tools, Azure DevOps extension and others Continuous Integration possibilities:

Opportunities to lean up the user experience

Having a simplified menu is also an opportunity to encourage the user to do some configuration steps. For example in the first screenshot we have the Explore Code Coverage button. With NDepend the code coverage by tests of a code base can be harnessed in multiple ways as explained here. But to harness code coverage data the user has to import it first. Hence, per default an Import Code Coverage button is shown to the user and the Explore Code Coverage button is shown only upon data imported.

Another important NDepend feature is comparing against a baseline. As far as I know NDepend is the only Visual Studio tool that lets the user diff the actual code base against a baseline. The user can then focus on new issues since baseline, or diff-related issues like API Breaking Changes or Code Smells Regression. The baseline can also be used to review code changes since the baseline. When NDepend analyzes a large legacy code base, letting the user focuses on new issues since the baseline is a very important facility to avoid letting the users lost in the prioritization of thousands of issues.

Per default the baseline is set to the first analysis result obtained. It means that the first time the user runs an analysis on a code base, this first analysis result is used both for the actual snapshot and the baseline snapshot. In this situation, when the user clicks the buttons New Issues since Baseline or Diff since Baseline, there is nothing to show. Thus we take a chance to show an informational message box that explains this no-diff situation. Doing so avoids the user being stuck with a no-result action or even worse, a button disabled with no obvious reason. We also hope these explanations will motivate the user to work on changes and then re-analyze to see what NDepend has to say about the new changes.

Having a single level menu just became mandatory

Another point to underline is that having a single level VS extension menu just became mandatory. Visual Studio 2019 just introduced the Extensions top level menu and extensions cannot have their top level menus anymore.

This move adds an extra click for accessing each extension feature. This extra click represents a UI regression for the millions of VS extensions users and de-facto discards features accessible only through a nested sub-menu. This move was unexpected because it solves a UI problem we (as a VS extension provider) have never heard of: having so many extensions menus that it becomes a cluttering problem. The only right way to solve such problem would be to let the user choose which extension have their top-level menu and which extension lies under the Extensions menu. An extension menu should be top-leveled by default upon installation: when a user installs an extension the goal is to spend the next minutes or hours trying it and using it. In this context it doesn’t make sense to put the extension menus in a second-zone, doing so degrades the so precious and fragile FTUE First-Time User Experience. A VS extension doesn’t get a second chance to offer a first impression to a trial user.

Several big names in the VS extension industry have already complained about this move here. You can vote and comment now because apparently Microsoft will monitor this thread only till mid May 2019.

We hope this simplified menu will help trial and beginner users getting started with all the NDepend goodies. Certainly some seasoned users will also prefer this less cluttered menu style. If you have comment or ideas to improve more let us know.

On forced UI change you can read further this 2012’s Scott Hanselman post Who moved my cheese?

People don’t like it when you move their cheese. They are just trying to get through the maze, they have it all under control and then, poof, someone moved their cheese. Now it’s a huge hassle to find it again. Change a hotkey or the case of the menus and all heck breaks loose.

An in-depth analysis of .NET Core 3.0 support for WPF and Winforms APIs

.NET Core 3.0 will be RTM soon and it supports WPF and Winforms APIs.

In my last post I’ve been exploring .NET Core 3.0 new APIs by comparing compiled bits with NDepend, of .NET Core 3.0 against .NET Core 2.2.

In this post I will compare .NET Core 3.0 Windows Forms (Winforms) and WPF APIs with .NET Framework 4.x.

I won’t make the suspense last: .NET Core 3.0 support for Winforms and WPF APIs is almost complete, I found very few breaking changes.

I will now explain what I’ve done with NDepend to explore this API diff, and then dig into the results. If you are wondering How to port desktop applications to .NET Core 3.0 see Microsoft explanations here.

Comparing .NET Core 3.0 Winforms and WPF APIs vs. NET Framework 4.x with NDepend

From the NDepend Start Page select Compare 2 versions of a code base menu. Then use Add assemblies in Folder buttons to add .NET Framework assemblies from folder C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319 and Microsoft.WindowsDesktop.app nuget package assemblies (from folder C:\Users\psmac\.nuget\packages\microsoft.windowsdesktop.app\3.0.0-preview-27325-3\ref\netcoreapp3.0 on my machine).

Comparing .NET Core 3.0 Winforms WPF APIs with .NET Framework

A minor difficulty was to isolate the exact set of assemblies to focus on. Here is the list of concerned assemblies I came up with:

Accessibility
PresentationCore
PresentationCore-CommonResources
PresentationFramework
PresentationFramework.Aero
PresentationFramework.Aero2
PresentationFramework.AeroLite
PresentationFramework.Classic
PresentationFramework.Luna
PresentationFramework.Royale
PresentationUI
ReachFramework
System.Drawing
System.Drawing.Design
System.Drawing.Primitives
System.Printing
System.Security.AccessControl
System.Security.Cryptography.Cng
System.Security.Cryptography.Pkcs
System.Security.Cryptography.Xml
System.Security.Permissions
System.Security.Principal.Windows
System.Windows.Controls.Ribbon
System.Windows.Forms
System.Windows.Input.Manipulations
System.Windows.Presentation
System.Xaml
UIAutomationClient
UIAutomationClientSideProviders
UIAutomationProvider
UIAutomationTypes
WindowsBase
WindowsFormsIntegration

Accessibility

PresentationCore

PresentationCore-CommonResources

PresentationFramework

PresentationFramework.Aero

PresentationFramework.Aero2

PresentationFramework.AeroLite

PresentationFramework.Classic

PresentationFramework.Luna

PresentationFramework.Royale

PresentationUI

ReachFramework

System.Drawing

System.Drawing.Design

System.Drawing.Primitives

System.Printing

System.Security.AccessControl

System.Security.Cryptography.Cng

System.Security.Cryptography.Pkcs

System.Security.Cryptography.Xml

System.Security.Permissions

System.Security.Principal.Windows

System.Windows.Controls.Ribbon

System.Windows.Forms

System.Windows.Input.Manipulations

System.Windows.Presentation

System.Xaml

UIAutomationClient

UIAutomationClientSideProviders

UIAutomationProvider

UIAutomationTypes

WindowsBase

WindowsFormsIntegration

Notice that to preserve the correspondance between APIs and assemblies packaging, the attribute TypeForwardedToAttribute is massively used to delegate implementations.

The few breaking changes

With the default NDepend rules about API breaking changes, I’ve only found 16 public types and 52 public methods missing. Here are the types:

16 types missing in WPF Winforms .NET Core 3.0 API

16 types missing on a total of 4.095 public types, well done!

The 52 public methods missing are: (on a total of 42.645 public methods)

Parent Assembly Name	Parent Type Name	Method name
System.Security.Principal.Windows	System.Security.Principal.WindowsIdentity	.ctor(String,String)
System.Security.Principal.Windows	System.Security.Principal.WindowsIdentity	Impersonate()
System.Security.Principal.Windows	System.Security.Principal.WindowsIdentity	Impersonate(IntPtr)
System.Security.Principal.Windows	System.Security.Principal.IdentityReferenceCollection	get_IsReadOnly()
System.Security.Permissions	System.Net.EndpointPermission	ToString()
System.Security.Permissions	System.Security.HostProtectionException	GetObjectData(SerializationInfo,StreamingContext)
System.Security.Permissions	System.Security.Policy.ApplicationDirectory	Clone()
System.Security.Permissions	System.Security.Policy.ApplicationTrust	Clone()
System.Security.Permissions	System.Security.Policy.PermissionRequestEvidence	Clone()
System.Security.Permissions	System.Security.Policy.Site	Clone()
System.Security.Permissions	System.Security.Policy.StrongName	Clone()
System.Security.Permissions	System.Security.Policy.Url	Clone()
System.Security.Permissions	System.Security.Policy.Zone	Clone()
System.Security.Permissions	System.Security.Policy.GacInstalled	Clone()
System.Security.Permissions	System.Security.Policy.Hash	Clone()
System.Security.Permissions	System.Security.Policy.Publisher	Clone()
System.Security.Cryptography.Pkcs	System.Security.Cryptography.Pkcs.EnvelopedCms	.ctor(SubjectIdentifierType,ContentInfo)
System.Security.Cryptography.Pkcs	System.Security.Cryptography.Pkcs.EnvelopedCms	.ctor(SubjectIdentifierType,ContentInfo,AlgorithmIdentifier)
System.Security.Cryptography.Pkcs	System.Security.Cryptography.Pkcs.EnvelopedCms	Encrypt()
System.Security.Cryptography.Pkcs	System.Security.Cryptography.Pkcs.ContentInfo	Finalize()
System.Security.Cryptography.Cng	System.Security.Cryptography.ECDiffieHellmanCng	FromXmlString(String)
System.Security.Cryptography.Cng	System.Security.Cryptography.ECDiffieHellmanCng	ToXmlString(Boolean)
System.Security.Cryptography.Cng	System.Security.Cryptography.ECDsaCng	FromXmlString(String)
System.Security.Cryptography.Cng	System.Security.Cryptography.ECDsaCng	ToXmlString(Boolean)
System.Security.Cryptography.Cng	System.Security.Cryptography.RSACng	DecryptValue(Byte[])
System.Security.Cryptography.Cng	System.Security.Cryptography.RSACng	EncryptValue(Byte[])
System.Security.Cryptography.Cng	System.Security.Cryptography.RSACng	get_KeyExchangeAlgorithm()
System.Security.Cryptography.Cng	System.Security.Cryptography.RSACng	get_SignatureAlgorithm()
System.Printing	System.Printing.PrintQueue	set_Name(String)
System.Printing	System.Printing.IndexedProperties.PrintInt32Property	op_Implicit(PrintInt32Property)
System.Printing	System.Printing.IndexedProperties.PrintStringProperty	op_Implicit(PrintStringProperty)
System.Printing	System.Printing.IndexedProperties.PrintStreamProperty	op_Implicit(PrintStreamProperty)
System.Printing	System.Printing.IndexedProperties.PrintQueueAttributeProperty	op_Implicit(PrintQueueAttributeProperty)
System.Printing	System.Printing.IndexedProperties.PrintQueueStatusProperty	op_Implicit(PrintQueueStatusProperty)
System.Printing	System.Printing.IndexedProperties.PrintBooleanProperty	op_Implicit(PrintBooleanProperty)
System.Printing	System.Printing.IndexedProperties.PrintThreadPriorityProperty	op_Implicit(PrintThreadPriorityProperty)
System.Printing	System.Printing.IndexedProperties.PrintServerLoggingProperty	op_Implicit(PrintServerLoggingProperty)
System.Printing	System.Printing.IndexedProperties.PrintDriverProperty	op_Implicit(PrintDriverProperty)
System.Printing	System.Printing.IndexedProperties.PrintPortProperty	op_Implicit(PrintPortProperty)
System.Printing	System.Printing.IndexedProperties.PrintServerProperty	op_Implicit(PrintServerProperty)
System.Printing	System.Printing.IndexedProperties.PrintTicketProperty	op_Implicit(PrintTicketProperty)
System.Printing	System.Printing.IndexedProperties.PrintByteArrayProperty	op_Implicit(PrintByteArrayProperty)
System.Printing	System.Printing.IndexedProperties.PrintProcessorProperty	op_Implicit(PrintProcessorProperty)
System.Printing	System.Printing.IndexedProperties.PrintQueueProperty	op_Implicit(PrintQueueProperty)
System.Printing	System.Printing.IndexedProperties.PrintJobPriorityProperty	op_Implicit(PrintJobPriorityProperty)
System.Printing	System.Printing.IndexedProperties.PrintJobStatusProperty	op_Implicit(PrintJobStatusProperty)
System.Printing	System.Printing.IndexedProperties.PrintDateTimeProperty	op_Implicit(PrintDateTimeProperty)
System.Printing	System.Printing.IndexedProperties.PrintSystemTypeProperty	op_Implicit(PrintSystemTypeProperty)
System.Printing	System.Windows.Xps.XpsDocumentWriter	raise__WritingProgressChanged(Object,WritingProgressChangedEventArgs)
System.Printing	System.Windows.Xps.XpsDocumentWriter	raise__WritingCompleted(Object,WritingCompletedEventArgs)
System.Printing	System.Windows.Xps.XpsDocumentWriter	raise__WritingCancelled(Object,WritingCancelledEventArgs)
System.Drawing	System.Drawing.FontConverter	Finalize()

Portability to .NET Core 3.0 analysis

Microsoft offers a Portability Analyzer tool to analyze changes in desktop API that will break your desktop app. I’ve tested it on NDepend but I just got very coarse results. Did I miss something? At least it is mostly green 🙂

Portability Analyzer analysis on NDepend

I wrote last year a post named Quickly assess your .NET code compliance with .NET Standard let me know in comment if it is worth revisiting this post for desktop APIs. Btw, my guess is that desktop APIs won’t be part of .NET Standard vNext (since there is no plan to support it on all platforms) but I haven’t found any related info on the web.

Why migrate your desktop app to .NET Core 3.0?

This is a great news that Microsoft embeds good-old desktop APIs in .NET Core 3.0 with such an outstanding compatibility. It is worth noting that so far (February 2019) there is no plan to port Windows Forms and WPF on other platforms than Windows. So, what are the benefits of porting an existing application to .NET Core 3.0?

I found answers in this recent How to Port Desktop Applications to .NET Core 3.0 Channel9 30 minutes video at 5:12. Basically you’ll get more deployment flexibility, Core Runtime and API improvements and also more performances.

Microsoft promises to not urge anyone to port existing Winforms and WPF application to .NET Core 3.0. However for a Visual Studio extension shop like us if it is decided that VS will run on .NET Core 3.0 in the future, we hope to be notified many months ahead. We discussed that on twitter with Amanda Silver in January 2019. It looks like this spring 2019 they will take a decision. As a consequence to support both Visual Studio past versions running on .NET fx and new versions running on .NET Core 3, an extension will need to support both .NET Fx and .NET Core 3 desktop APIs.

Exploring .NET Core 3.0 new API

.NET Core 3.0 is representing a major step for the .NET community. It is interesting to analyze what’s new in the API directly from the compiled bits. In this post I will first explain how to diff .NET Core 3.0 against .NET Core 2.2 with NDepend, and then how to browse diff results.

Arguably the biggest progress of .NET Core 3.0 will be the support for Winforms and WPF on the Windows platform. Since everything is new here, compare to .NET Core 2.2, we won’t analyze this part. However it will be interesting to analyze .NET Fx Winforms/WPF APIs vs .NET Core 3.0 Winforms/WPF APIs in another post (that I finally wrote here).

Analyzing two versions of .NET Core with NDepend

It takes a few minutes to download NDepend trial, install it and start VisualNDepend.exe, and it takes a few minutes to compare .NET Core 3.0 against .NET Core 2.2. If you want to browse the diff on your machine, expect 5 to 10 minutes to get hands-on.

First Start VisualNDepend.exe and click Compare 2 versions of a code base:

How to compare 2 versions of a code base

For both builds, choose Add Assemblies in Folder:

Choose C:\Program Files\dotnet\shared\Microsoft.NETCore.App\2.2.2 for Older Build
Choose C:\Program Files\dotnet\shared\Microsoft.NETCore.App\3.0.0-preview-27324-5 for Newer Build

Respectively 156 and 161 assemblies are gathered. Click Ok to run two analysis, on older and newer build. Both analysis results will be then diffed automatically.

Ready to compare 2 versions of .NET Core

Querying new API

Let’s start with a few CQLinq code queries to explore the new .NET Core 3.0 APIs:

This query match all new public code elements, including new assemblies, namespace, types, methods and fields:

from x in Application.CodeElements
where x.WasAdded()  
 && (!x.IsTypeOrMember || x.AsTypeOrMember.IsPubliclyVisible)
select x

from x in Application.CodeElements

where x.WasAdded()

&& (!x.IsTypeOrMember || x.AsTypeOrMember.IsPubliclyVisible)

select x

Use the NDepend query result to browse this large new API set : 5 new assemblies, 83 new namespaces, 297 new types, 4 924 new methods and 307 new fields. Note that code elements with pink background are not matched by the query, they are just here for preserving the code hierarchy in the result:

Download here this long list obtained by exporting the query result to excel. For a better result formatting I actually used this refined query to show properly parent assemblies/namespaces/types in excel columns:

from x in Application.CodeElements
where x.WasAdded()  
 && (!x.IsTypeOrMember || x.AsTypeOrMember.IsPubliclyVisible)
select new { x, 
Assembly = x.IsAssembly ?  x.Name : 
           x.IsNamespace ? x.Parent.Name : 
                           x.AsTypeOrMember.ParentAssembly.Name,

Namespace = x.IsAssembly ?  " " : 
            x.IsNamespace ? x.Name: 
                            x.AsTypeOrMember.ParentNamespace.Name,

Type = x.IsAssembly ? " " :
       x.IsNamespace ? " " :
       x.IsType ? x.Name:
       x.AsMember.ParentType.Name,

Member = x.IsMember ? x.Name : " "
}

from x in Application.CodeElements

where x.WasAdded()

&& (!x.IsTypeOrMember || x.AsTypeOrMember.IsPubliclyVisible)

select new { x,

Assembly = x.IsAssembly ? x.Name :

x.IsNamespace ? x.Parent.Name :

x.AsTypeOrMember.ParentAssembly.Name,

Namespace = x.IsAssembly ? " " :

x.IsNamespace ? x.Name:

x.AsTypeOrMember.ParentNamespace.Name,

Type = x.IsAssembly ? " " :

x.IsNamespace ? " " :

x.IsType ? x.Name:

x.AsMember.ParentType.Name,

Member = x.IsMember ? x.Name : " "

}

It is interesting to just focus on the 297 new public types with the code query below. Download the list here or browse the same list at the end of this post.

from t in Application.Types
where t.IsPubliclyVisible && t.WasAdded() 
select t

from t in Application.Types

where t.IsPubliclyVisible && t.WasAdded()

select t

It is also interesting to browse the new 1.101 public methods and 38 public fields added on public types that existed already in .NET Core 2.2. Download this list here.

from m in Application.Members
where m.IsPubliclyVisible 
   && m.WasAdded()
   && !m.ParentType.WasAdded()
select new { m }

from m in Application.Members

where m.IsPubliclyVisible

&& m.WasAdded()

&& !m.ParentType.WasAdded()

select new { m }

API Breaking Changes

NDepend proposes 6 default rules to browse API breaking changes.

These rules matche 19 public types removed from .NET Core 2.2 (see list below) 176 public methods removed and 36 public fields removed

Listing Methods Changed

Exploring the API evolution is useful for API consumers. For those working on the framework .NET Core itself, it is interesting to also browse implementation changes. The NDepend search by change panel proposes various options for that. Note that this search panel is actually a code query generator. The Edit query button proposes to edit and refine the currently generated query.

Another interesting point is that it is a semantic implementation change. All matched methods do behave differently at runtime. This makes this tool ideal to plan code change review without bothering with formatting and comments change.

Matched code elements can be highlighted in the metric view. From the screenshot above we can see at a glance that System.Xml and System.Data are much more stable than System.RunTime for example. By zooming in the view, we can get more information about which code was churned.

In the query result panel, a code element is underlined when its implementation changed. If you have compiled both source versions on your machine and analyzed those compiled versions, you can right click an underlined method and directly compare the diff in source code.

I hope you see value both in the results offered and in the how-to-diff procedure that can be applied to any .NET code base, assuming you have 2 versions to compare.

New .NET Core 3.0 types

Here is the list of the 297 new types added to .NET Core 3.0.

ParentAssembly	Full Name
WindowsBase	System.Windows.Markup .ValueSerializerAttribute
System.Xml.Linq	System.Xml.XPath.XDocumentExtensions
System.Threading.ThreadPool	System.Threading.IThreadPoolWorkItem
System.Threading.Tasks	System.Runtime.CompilerServices .AsyncIteratorMethodBuilder
System.Threading.Tasks	System.Runtime.CompilerServices .ConfiguredCancelableAsyncEnumerable<T>
System.Text.Json	System.Text.Json.JsonCommentHandling
System.Text.Json	System.Text.Json.JsonTokenType
System.Text.Json	System.Text.Json.JsonDocument
System.Text.Json	System.Text.Json.JsonElement
System.Text.Json	System.Text.Json .JsonElement+ArrayEnumerator
System.Text.Json	System.Text.Json .JsonElement+ObjectEnumerator
System.Text.Json	System.Text.Json.JsonProperty
System.Text.Json	System.Text.Json.JsonValueType
System.Text.Json	System.Text.Json.JsonReaderException
System.Text.Json	System.Text.Json.JsonReaderOptions
System.Text.Json	System.Text.Json.JsonReaderState
System.Text.Json	System.Text.Json.Utf8JsonReader
System.Text.Json	System.Text.Json.JsonWriterOptions
System.Text.Json	System.Text.Json.JsonWriterState
System.Text.Json	System.Text.Json.Utf8JsonWriter
System.Security.Principal.Windows	System.Security.Principal .WindowsAccountType
System.Security.Cryptography.Primitives	System.Security.Cryptography .PbeEncryptionAlgorithm
System.Security.Cryptography.Primitives	System.Security.Cryptography .PbeParameters
System.Security.Cryptography.Algorithms	System.Security.Cryptography.AesCcm
System.Security.Cryptography.Algorithms	System.Security.Cryptography.AesGcm
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.CornerRadius
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.DurationType
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Duration
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.GridUnitType
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.GridLength
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Thickness
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.LayoutCycleException
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Markup .XamlParseException
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Automation .ElementNotAvailableException
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Automation .ElementNotEnabledException
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Media.Matrix
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Media.Media3D.Matrix3D
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Media.Animation.KeyTime
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Media.Animation .RepeatBehaviorType
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Media.Animation .RepeatBehavior
System.Runtime.WindowsRuntime.UI.Xaml	Windows.UI.Xaml.Controls.Primitives .GeneratorPosition
System.Runtime.WindowsRuntime	Windows.UI.Color
System.Runtime.WindowsRuntime	Windows.Foundation.Point
System.Runtime.WindowsRuntime	Windows.Foundation.Rect
System.Runtime.WindowsRuntime	Windows.Foundation.Size
System.Runtime.WindowsRuntime	System.WindowsRuntimeSystemExtensions
System.Runtime.WindowsRuntime	System.IO .WindowsRuntimeStorageExtensions
System.Runtime.WindowsRuntime	System.IO.WindowsRuntimeStreamExtensions
System.Runtime.WindowsRuntime	System.Threading.DispatcherQueueHandler
System.Runtime.WindowsRuntime	System.Threading.DispatcherQueuePriority
System.Runtime.WindowsRuntime	System.Runtime.InteropServices .WindowsRuntime.AsyncInfo
System.Runtime.WindowsRuntime	System.Runtime.InteropServices .WindowsRuntime.WindowsRuntimeBuffer
System.Runtime.WindowsRuntime	System.Runtime.InteropServices .WindowsRuntime .WindowsRuntimeBufferExtensions
System.Runtime.Serialization	System.Runtime.Serialization .ISerializationSurrogateProvider
System.Runtime.Loader	System.Runtime.Loader .AssemblyDependencyResolver
System.Runtime.Intrinsics	System.MidpointRounding
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Vector64
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Vector64<T>
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Vector128
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Vector128<T>
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Vector256
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Vector256<T>
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86 .FloatComparisonMode
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Aes
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Avx
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Avx2
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Bmi1
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Bmi2
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Fma
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Lzcnt
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Pclmulqdq
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Popcnt
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Sse
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Sse2
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Sse3
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Sse41
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Sse42
System.Runtime.Intrinsics	System.Runtime.Intrinsics.X86.Ssse3
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Arm.Arm64.Aes
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Arm.Arm64.Base
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Arm.Arm64.Sha1
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Arm.Arm64 .Sha256
System.Runtime.Intrinsics	System.Runtime.Intrinsics.Arm.Arm64.Simd
System.Runtime.InteropServices	System.Runtime.CompilerServices .IDispatchConstantAttribute
System.Runtime.InteropServices	System.Runtime.InteropServices .StandardOleMarshalObject
System.Runtime.InteropServices	System.Runtime.InteropServices .NativeLibrary
System.Runtime.Extensions	System.AppDomainSetup
System.Runtime.Extensions	System.Security.IStackWalk
System.Runtime.Extensions	System.Security.PermissionSet
System.Runtime.Extensions	System.Security.Permissions .PermissionState
System.Runtime.Extensions	System.Runtime.ProfileOptimization
System.Runtime	System.ArgIterator
System.Runtime	System.IAsyncDisposable
System.Runtime	System.Index
System.Runtime	System.Range
System.Runtime	System.Text.Rune
System.Runtime	System.Text.StringRuneEnumerator
System.Runtime	System.Globalization.ISOWeek
System.Runtime	System.Threading.Tasks.Sources .ManualResetValueTaskSourceCore<TResult>
System.Runtime	System.Runtime.Remoting.ObjectHandle
System.Runtime	System.Runtime.CompilerServices .AsyncIteratorStateMachineAttribute
System.Runtime	System.Runtime.CompilerServices .CallerArgumentExpressionAttribute
System.Runtime	System.Collections.Generic .IAsyncEnumerable<T>
System.Runtime	System.Collections.Generic .IAsyncEnumerator<T>
System.Private.CoreLib	System.IAsyncDisposable
System.Private.CoreLib	System.Index
System.Private.CoreLib	System.Range
System.Private.CoreLib	System.Text .StringBuilder+ChunkEnumerator
System.Private.CoreLib	System.Text.Rune
System.Private.CoreLib	System.Text.SpanRuneEnumerator
System.Private.CoreLib	System.Text.StringRuneEnumerator
System.Private.CoreLib	System.Globalization.ISOWeek
System.Private.CoreLib	System.Buffers.OperationStatus
System.Private.CoreLib	System.Buffers.StandardFormat
System.Private.CoreLib	System.Buffers.Text.Utf8Formatter
System.Private.CoreLib	System.Buffers.Text.Utf8Parser
System.Private.CoreLib	System.Buffers.Binary.BinaryPrimitives
System.Private.CoreLib	System.Threading.Tasks.Sources .ManualResetValueTaskSourceCore<TResult>
System.Private.CoreLib	System.Runtime.Remoting.ObjectHandle
System.Private.CoreLib	System.Runtime.Loader .AssemblyDependencyResolver
System.Private.CoreLib	System.Runtime.CompilerServices .AsyncIteratorMethodBuilder
System.Private.CoreLib	System.Runtime.CompilerServices .AsyncIteratorStateMachineAttribute
System.Private.CoreLib	System.Runtime.CompilerServices .CallerArgumentExpressionAttribute
System.Private.CoreLib	System.Runtime.CompilerServices .ConfiguredCancelableAsyncEnumerable<T>
System.Private.CoreLib	System.Runtime.CompilerServices .ConfiguredCancelableAsyncEnumerable<T >+Enumerator
System.Private.CoreLib	System.Runtime.Intrinsics.Vector64
System.Private.CoreLib	System.Runtime.Intrinsics.Vector128
System.Private.CoreLib	System.Runtime.Intrinsics.Vector256
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Bmi1+X64
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Bmi2+X64
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Lzcnt+X64
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Popcnt+X64
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Sse+X64
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Sse2+X64
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Sse41+X64
System.Private.CoreLib	System.Runtime.Intrinsics.X86.Sse42+X64
System.Private.CoreLib	System.Runtime.InteropServices .DllImportResolver
System.Private.CoreLib	System.Runtime.InteropServices .NativeLibrary
System.Private.CoreLib	System.Runtime.InteropServices .ComActivationContext
System.Private.CoreLib	System.Runtime.InteropServices .ComActivationContextInternal
System.Private.CoreLib	System.Runtime.InteropServices .ComActivator
System.Private.CoreLib	System.Runtime.InteropServices .ComEventInterfaceAttribute
System.Private.CoreLib	System.Runtime.InteropServices .DefaultParameterValueAttribute
System.Private.CoreLib	System.Diagnostics.DebugProvider
System.Private.CoreLib	System.Collections.Generic .IAsyncEnumerable<T>
System.Private.CoreLib	System.Collections.Generic .IAsyncEnumerator<T>
System.Private.CoreLib	Internal.Resources.PRIExceptionInfo
System.Private.CoreLib	Internal.Resources .WindowsRuntimeResourceManagerBase
System.Private.CoreLib	Internal.Threading.Tasks .AsyncCausalitySupport
System.Private.CoreLib	Internal.Runtime.InteropServices .WindowsRuntime.ExceptionSupport
System.ObjectModel	System.Reflection.ICustomTypeProvider
System.ObjectModel	System.ComponentModel .TypeConverterAttribute
System.ObjectModel	System.ComponentModel .TypeDescriptionProviderAttribute
System.ObjectModel	System.Windows.Markup .ValueSerializerAttribute
System.Net.Sockets	System.Net.Sockets.SafeSocketHandle
System.Memory	System.Text.SpanRuneEnumerator
System.Memory	System.Buffers.SequenceReader<T>
System.Memory	System.Buffers.SequenceReaderExtensions
System	System.StringNormalizationExtensions
System	System.Reflection.ICustomTypeProvider
System	System.Windows.Markup .ValueSerializerAttribute
System	System.Runtime.InteropServices .StandardOleMarshalObject
System	System.Diagnostics.ConsoleTraceListener
System	System.Diagnostics .XmlWriterTraceListener
System	System.Diagnostics.StackFrameExtensions
System	System.Security.SecureStringMarshal
System	System.Net.Sockets .SocketReceiveFromResult
System	System.Net.Sockets .SocketReceiveMessageFromResult
System	System.Net.Sockets.SocketTaskExtensions
System.Diagnostics.TextWriterTraceListener	System.Diagnostics.ConsoleTraceListener
System.Diagnostics.TextWriterTraceListener	System.Diagnostics .XmlWriterTraceListener
System.Data	System.Xml.XmlDataDocument
System.Data	System.Data.Common.DbColumn
System.Data	System.Data.Common .DbDataReaderExtensions
System.Data	System.Data.Common .IDbColumnSchemaGenerator
System.Core	System.Security.Cryptography.AesCng
System.Core	System.Security.Cryptography.DSACng
System.Core	System.Security.Cryptography .TripleDESCng
System.Core	System.Security.Cryptography.ECCurve
System.Core	System.Security.Cryptography .ECParameters
System.Core	System.Security.Cryptography.ECPoint
System.Core	System.Security.Cryptography .IncrementalHash
System.Core	System.Security.Cryptography .X509Certificates.CertificateRequest
System.Core	System.Security.Cryptography .X509Certificates .DSACertificateExtensions
System.Core	System.Security.Cryptography .X509Certificates .SubjectAlternativeNameBuilder
System.Core	System.Security.Cryptography .X509Certificates.X509SignatureGenerator
System.ComponentModel.TypeConverter	System.ComponentModel.VersionConverter
System.ComponentModel.Primitives	System.ComponentModel .InvalidAsynchronousStateException
System.ComponentModel.DataAnnotations	System.ComponentModel.DataAnnotations .AssociatedMetadataTypeTypeDescriptionPr ovider
System.ComponentModel.DataAnnotations	System.ComponentModel.DataAnnotations .MetadataTypeAttribute
System.ComponentModel.Annotations	System.ComponentModel.DataAnnotations .AssociatedMetadataTypeTypeDescriptionPr ovider
System.ComponentModel.Annotations	System.ComponentModel.DataAnnotations .MetadataTypeAttribute
mscorlib	System.TupleExtensions
mscorlib	System.AppDomainSetup
mscorlib	System.Globalization .GlobalizationExtensions
mscorlib	System.Threading.ThreadPoolBoundHandle
mscorlib	System.Threading.PreAllocatedOverlapped
mscorlib	System.Runtime.ProfileOptimization
mscorlib	System.Runtime.Remoting.ObjectHandle
mscorlib	System.Runtime.CompilerServices .RuntimeFeature
mscorlib	System.Runtime.CompilerServices .IsByRefLikeAttribute
mscorlib	System.Runtime.CompilerServices.ITuple
mscorlib	System.Runtime.CompilerServices .IsReadOnlyAttribute
mscorlib	System.Runtime.CompilerServices .TupleElementNamesAttribute
mscorlib	System.Runtime.CompilerServices .IDispatchConstantAttribute
mscorlib	System.Runtime.InteropServices .RuntimeInformation
mscorlib	System.Runtime.InteropServices .Architecture
mscorlib	System.Runtime.InteropServices .OSPlatform
mscorlib	System.Reflection.Emit.DynamicILInfo
mscorlib	System.Security.IStackWalk
mscorlib	System.Security.PermissionSet
mscorlib	System.Security.Permissions .PermissionState
mscorlib	System.Security.Principal .WindowsAccountType
mscorlib	System.Diagnostics.Tracing .EventSourceCreatedEventArgs
Microsoft.VisualBasic	Microsoft.VisualBasic.Collection
Microsoft.VisualBasic	Microsoft.VisualBasic.CompareMethod
Microsoft.VisualBasic	Microsoft.VisualBasic.ComClassAttribute
Microsoft.VisualBasic	Microsoft.VisualBasic.ControlChars
Microsoft.VisualBasic	Microsoft.VisualBasic.DateAndTime
Microsoft.VisualBasic	Microsoft.VisualBasic.Information
Microsoft.VisualBasic	Microsoft.VisualBasic .MyGroupCollectionAttribute
Microsoft.VisualBasic	Microsoft.VisualBasic.VariantType
Microsoft.VisualBasic	Microsoft.VisualBasic .VBFixedArrayAttribute
Microsoft.VisualBasic	Microsoft.VisualBasic .VBFixedStringAttribute
Microsoft.VisualBasic	Microsoft.VisualBasic.VBMath
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO.FileSystem
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO .DeleteDirectoryOption
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO .RecycleOption
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO .SearchOption
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO .UICancelOption
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO.UIOption
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO .MalformedLineException
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO .SpecialDirectories
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO .TextFieldParser
Microsoft.VisualBasic	Microsoft.VisualBasic.FileIO.FieldType
Microsoft.VisualBasic	Microsoft.VisualBasic.CompilerServices .BooleanType
Microsoft.VisualBasic	Microsoft.VisualBasic.CompilerServices .DecimalType
Microsoft.VisualBasic	Microsoft.VisualBasic.CompilerServices .Versioned
Microsoft.VisualBasic	Microsoft.VisualBasic.CompilerServices .DoubleType
Microsoft.VisualBasic	Microsoft.VisualBasic .ApplicationServices.StartupEventArgs
Microsoft.VisualBasic	Microsoft.VisualBasic .ApplicationServices .StartupNextInstanceEventArgs
Microsoft.VisualBasic	Microsoft.VisualBasic .ApplicationServices .UnhandledExceptionEventArgs
Microsoft.VisualBasic	Microsoft.VisualBasic.Devices .NetworkAvailableEventArgs
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CallType
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.Collection
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompareMethod
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.ComClassAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.Constants
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.ControlChars
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.DateAndTime
Microsoft.VisualBasic.Core	Microsoft.VisualBasic .HideModuleNameAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.Information
Microsoft.VisualBasic.Core	Microsoft.VisualBasic .MyGroupCollectionAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.Strings
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.VariantType
Microsoft.VisualBasic.Core	Microsoft.VisualBasic .VBFixedArrayAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic .VBFixedStringAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.VBMath
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO.FileSystem
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO .DeleteDirectoryOption
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO .RecycleOption
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO .SearchOption
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO .UICancelOption
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO.UIOption
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO .MalformedLineException
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO .SpecialDirectories
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO .TextFieldParser
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.FileIO.FieldType
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .BooleanType
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .Conversions
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .DecimalType
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .DesignerGeneratedAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate0
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate1
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate2
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate3
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate4
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate5
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate6
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .SiteDelegate7
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .IncompleteInitialization
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .NewLateBinding
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .ObjectFlowControl
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .ObjectFlowControl+ForLoopControl
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .Operators
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .OptionCompareAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .OptionTextAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .ProjectData
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .StandardModuleAttribute
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .StaticLocalInitFlag
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .Utils
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .Versioned
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.CompilerServices .DoubleType
Microsoft.VisualBasic.Core	Microsoft.VisualBasic .ApplicationServices.StartupEventArgs
Microsoft.VisualBasic.Core	Microsoft.VisualBasic .ApplicationServices .StartupNextInstanceEventArgs
Microsoft.VisualBasic.Core	Microsoft.VisualBasic .ApplicationServices .UnhandledExceptionEventArgs
Microsoft.VisualBasic.Core	Microsoft.VisualBasic.Devices .NetworkAvailableEventArgs

Advanced Code Search : A Case Study

This morning I stumbled on a complex test to write. The need was to create and show a custom Form (written with Windows Form) that relies on the System.ComponentModel.BackgroundWorker to do initialization stuff without freezing the UI. The test is complex because after creating and showing the form, it must wait somehow to release the UI thread for a while to let the BackgroundWorker achieve the RunWorkerCompleted on the UI thread.

I know that this is something we’ve done in the past and I know this is tricky enough to not reinvent the wheel. But with a test suite of over 13.000 tests this is quite challenging to find where we did that. So I decided to use NDepend querying facility to search.

First I analyze all NDepend assemblies, test assemblies included. Then I generate a code query to match all classes that derive from Form. This can be done from the NDepend Search panel : search Form by name in third-party types and then use a right-click menu to generate the code query:

The CQLinq code query generated is:

from t in Types 
let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")
where depth0  >= 0 orderby depth0
select new { t, depth0 }

from t in Types

let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")

where depth0 >= 0 orderby depth0

select new { t, depth0 }

60 classes are matched:

Let’s refine this query to match all methods that create any of those form classes.This could be achieved by iterating over (all methods) x (all form classes), but the NDepend.API extension method ThatCreateAny() acts like a join and operates in a linear time. For our search scenario, waiting a few seconds to get a search result is not a problem. But for a code rule written with CQLinq, this is important to run it as fast as possible in a few milliseconds, to run all queries and rules often in Visual Studio within a few seconds, hence the query performance entry on the documentation.

let formTypes = 
  (from t in Types 
   let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")
   where depth0  >= 0
   select t)

from m in Application.Methods.ThatCreateAny(formTypes)
select m

let formTypes =

(from t in Types

let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")

where depth0 >= 0

select t)

from m in Application.Methods.ThatCreateAny(formTypes)

select m

280 methods are instantiating some form classes. Let’s refine the query to match only tests method. The cleanest way would be to check for the usage of TestAttribute, but here just checking for parent assemblies names that contain “Test” is enough:

let formTypes = 
  (from t in Types 
   let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")
   where depth0  >= 0
   select t)
from m in Application.Methods.ThatCreateAny(formTypes)
where m.ParentAssembly.Name.Contains("Test")
select m

let formTypes =

(from t in Types

let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")

where depth0 >= 0

select t)

from m in Application.Methods.ThatCreateAny(formTypes)

where m.ParentAssembly.Name.Contains("Test")

select m

Still 122 test methods matched.

Before filtering the result even more, let’s refine the query to display for each test the form class(es) it instantiates. This can be achieved with a LINQ range variable formsCreated that we use in the result:

let formTypes = 
  (from t in Types 
   let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")
   where depth0  >= 0
   select t)

from m in Application.Methods.ThatCreateAny(formTypes)
where m.ParentAssembly.Name.Contains("Test")
let formsCreated = formTypes.Where(t =>m.CreateA(t))
select new { m, formsCreated }

let formTypes =

(from t in Types

let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")

where depth0 >= 0

select t)

from m in Application.Methods.ThatCreateAny(formTypes)

where m.ParentAssembly.Name.Contains("Test")

let formsCreated = formTypes.Where(t =>m.CreateA(t))

select new { m, formsCreated }

We can now browse which form(s) are instantiated by each test:

Finally let’s browse only tests that use some asynchronous related code. Many ways can be used to check for asynchronous usages. The easiest way is certainly to look at methods called by a test method, and check which ones have named related to async stuff. I tried a few words like “Async” “Sync” “Thread” “TimeOut” “Wait”… and “Wait” worked:

let formTypes = 
  (from t in Types 
   let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")
   where depth0  >= 0
   select t)
from m in Application.Methods.ThatCreateAny(formTypes)
where m.ParentAssembly.Name.Contains("Test")
let formsCreated = formTypes.Where(t =>m.CreateA(t))
where m.MethodsCalled.Any(m1 => m1.SimpleName.Contains("Wait"))
select new { m, formsCreated }

let formTypes =

(from t in Types

let depth0 = t.DepthOfDeriveFrom("System.Windows.Forms.Form")

where depth0 >= 0

select t)

from m in Application.Methods.ThatCreateAny(formTypes)

where m.ParentAssembly.Name.Contains("Test")

let formsCreated = formTypes.Where(t =>m.CreateA(t))

where m.MethodsCalled.Any(m1 => m1.SimpleName.Contains("Wait"))

select new { m, formsCreated }

In the source code of the highlighted test I had everything I needed for my scenario, including a link to a tricky stackoverflow answer that we found years ago. I found what I needed within a few minutes and had a bit of fun. I hope the methodology and the resulting query can be adapted to your advanced search scenarios.