Become an N-Tier Ninja with Trackable Entities 2.0

Taking a cue from Julie Lerman and Scott Hanselman, I’ve decided to dub version 2.0 of my Trackable Entities framework, the “Ninja Edition.” After releasing v 1.0 six month ago, I received several constructive suggestions on the project discussion and issues forums, which highlighted features I needed to add in order to make Trackable Entities a viable alternative to the now defunct Entity Framework Self-Tracking Entities. Now that I’ve added these items, Trackable Entities lets you become an N-Tier Ninja.

tracking-logoLet me put it this way. With just a few clicks, Trackable Entities gives you a fully functioning, real-world N-Tier application, with client-side change tracking that is portable and platform agnostic (it can work on any client – from WPF and Windows Phone to iOS and Android), and server-side persistence of batch updates in a disconnected and stateless manner, within a single transaction and a single round trip. In other words, this thing is cool.

Can’t wait to get started? Check out the Online Tutorials, or have a look at the Getting Started Video to build a complete n-tier application with EF 6.1 and ASP.NET Web API 2.1 in less than 10 minutes.


Aside from the coolness factor, what makes Trackable Entities a killer framework, is that it comes as a Visual Studio Extension.  To get it from within Visual Studio, all you have to do is install it from the Tools, Extensions and Updates menu.  This will give you a number of Trackable Entities project templates.


Once you click on one of these babies, you get a mulit-project Visual Studio solution. This in itself is an incredible time-saver.  All of the NuGet packages are there. All of the project references are correctly set. Customized T4 templates are inserted and ready to go.


The next step is to reverse engineer an existing database into entities and mapping classes. For this aspect, we leverage the Entity Framework Power Tools. (I’m planning to replace this in the near future with the EF 6.1 Tools for Visual Studio, which also come with VS 2013 Update 2.)  The reason for this is that it’s easy to customize entity code-generation by modifying a set of T4 templates.  On the client side, the entities are data-binding friendly and they play nice with the change tracker. On the server side, the templates generate classes that are much simpler, without concern for change tracking or data binding. Because the classes are persistence ignorant POCO’s (Plain Old CLR Objects), they’re ideal for use with Domain Driven Design Patterns (such as Repository and Unit of Work).

What this separation between client and server entities means is that the service does not have to worry about how change tracking takes place on the client.  All it cares about are two little properties: TrackingState (Unchanged, Modified, Added or Deleted) and ModifiedProperties (which properties have been changed). This is essentially what sets Trackable Entities apart from its evil twin, Self-Tracking Entities.  In order to apply changes to an Entity Framework DbContext, we don’t need to know anything about original property values, and all the change-tracking logic is encapsulated on the client, by adding the Trackable Entities Client NuGet package.

As a consequence there’s nothing to stop a JavaScript client, such as a SPA, or Single Page Application, from setting tracking state on entities and sending them off to a RESTful web service that uses Trackable Entities to perform batch updates.  Nice.

Then there’s hassle-free serialization. Trackable Entities sets everything up so you don’t have to worry about tweaking configuration settings or attaching the correct attributes.  This is worth mentioning because by default Entity Framework favors the least common use-case, which a client communicating directly with a database via EF.  DbContext is configured to use dynamic proxies for lazy loading, and these are not serializable.  Trackable Entities, on the other hand, provides a DbContext class with proxy generation turned off, and entities are decorated with both JsonObject and DataContract attributes, so that cyclical references do not break the serializer.

The other thing that makes n-tier just plain hard is the Entity Framework API for persisting changes in a disconnected fashion.  Julie Lerman and Rowan Miller discuss this in their excellent DbContext book, but it remains a complex problem to solve, especially when it comes to dealing with many-to-many relationships.  But this is where Trackable Entities shines.  All you have to do is write one line of code:  DbContext.ApplyChanges.  Pass in one or more entities, and Trackable Entities will walk the entire object graph in all directions, correctly setting entity state.  It uses recursion to traverse the graph and can apply a change several layers deep.  And here’s the kicker: it knows how to deal with many-to-many relationships.  This is a feature I added to version 2.0, and it uses the metadata workspace to reflect over the conceptual model and add or remove entities from the M-M relationship without inserting or deleting the entities themselves.

Another cool feature I added to v 2.0 is an extension method to DbContext called LoadRelatedEntities.  This is one I’m especially proud of.  It obviates the need to call LoadProperty on ObjectContext, which can be quite inefficient and can only be executed synchronously.  The reason you may need to load properties is to set reference properties on added entities.  For example, you create a new order with details, and you want to return the inserted order with Customer set on each order and Product set on each order detail.  What makes LoadRelatedEntities so gnarly (to use surfer-speak) is (a) it traverses the object graph, so you only have to call it once, (b) it fetches batches of entities by dynamically constructing Entity SQL statements, and (c) it can be executed asynchronously, utilizing EF 6’s async capabilities.

After performing updates, it is important to return updated entities to the client, so that entity properties are populated with database generated values, for example, identity keys and concurrency tokens.  The trick is knowing how to merge changes back into the original objects, when those objects do not contain any metadata concerning primary keys.  The solution is to use a unique identifier that allows you to correlate each updated entity to the corresponding original entity.  In v 2.0 I added a new MergeChanges method that does precisely this.  Now you can update a collection of entities bound to a data grid without affecting the order or messing up the data bindings.

There are separate installers for Visual Studio 2012 and 2013, with limited support for .NET 4.0.  The VS extension includes multi-project templates for both WCF and ASP.NET Web API, with item templates that provide both WCF service types and Web API controllers. And wherever possible operations and actions are asynchronous.

Lastly, the icing on the cake is full support for domain driven design with repository and unit of work patterns.  A separate template gives you a multi-project solution, with interfaces separated cleanly from implementation, so that you have complete independence from the underlying persistence framework, enabling you to future-proof your app against potential obsolescence and, should it become necessary, swap out EF for something else.

The beauty of Trackable Entities is that you get all this goodness for free, and you can accomplish in minutes what it would otherwise take hours or days to pull off.  To get started you can go through one of the Online Tutorials (Web API, WCF, or Repo / Unit of Work), or take a look at the Getting Started Video, to build an end-to-end n-tier application in no time with Trackable Entities, Entity Framework, and ASP.NET Web API or WCF.  Enjoy!

About Tony Sneed

Sr. Software Solutions Architect, Hilti Global Application Software
This entry was posted in Technical and tagged , , . Bookmark the permalink.

7 Responses to Become an N-Tier Ninja with Trackable Entities 2.0

  1. Vlad says:

    Hi Tony,
    I find your work very inspired and I want to thank you for making such a great framework.

    Still, I have a question… I quote you here :

    What about that? You still have to set state manually on every entity on the graph as well as setting the modified properties manually. I would really be awesome if there was a JS version of your tracking client entities…. Or am I missing something here?

  2. Vlad says:

    This is the text I tried to quote:
    As a consequence there’s nothing to stop a JavaScript client, such as a SPA, or Single Page Application, from setting tracking state on entities and sending them off to a RESTful web service that uses Trackable Entities to perform batch updates. Nice.

  3. Ali Sharkasi says:

    Thanks for your greate work and efforts you help to move from dataset usage to entity framework with N tier trackable changes.

    Thanks alot

    Ali Sharkasi

  4. jeremywesley says:

    Hi Tony,
    I stumbled on your framework while looking for part of what it does. It appears to be almost what I’m looking for. I am building a sync system for thin clients, ios, spa,etc.

    I noticed you don’t call this sync but traceable and I believe that is accurate. But it’s not far from syncing. You made a statement that the server does not have to need to track changes just the client, but if the same data is being sent to multiple installs of the client code (iPhone, iPad) I can see how to sync adds and deletes but how would the second device know what changes had been made on the first device?

    I have some ideas on how to make it work but I wanted to make sure I wasn’t overlooking something before I headed down that road.

    Thanks for all the time you have put in on this framework, it appears to be well done


    • Tony Sneed says:

      Hello Jeremy,

      Glad you found my framework! You’re right in observing that Trackable Entities is mostly about tracking changes to entities across service boundaries. It also comes with a number of Visual Studio templates which speed development of n-tier applications while applying a set of best practices. The idea is that a client will make some changes to a graph of objects, which will each have a TrackingState property. The client-side change tracker will update TrackingState as those objects are added, modified or removed. When objects are sent to a web service (either WCF or Web API), then the TrackingState of each object is read and applied to an Entity Framework data context so they can be persisted within a single transaction, with a single round trip to the server.

      TE does not, however, have a facility for notifying various clients that changes have taken place in a data store. As such, it is based on a “pull” mechanism, rather than a “push” mechanism. There are other frameworks, such as SignalR, or WCF duplex channels, which can be used for broadcasting notifications. On the other hand, a polling mechanism could also be used. It seems to me that TE would complement the sync framework you are working on, because it simply encapsulates the communication of changes to a central repository. Clients could then be made to poll for changes, or register to receive notifications.

      Good luck with your framework!


  5. Ayala says:

    Hey Tony,
    I am using your nugget package for “TrackableEntities.EF.6″ in my web API for the server side (in .net framework)
    my client side is angular (8),I install the npm:”npm i –save trackable-entities”
    I looked in your sample and I saw that TE have POC of webapi+consoleapplicaton communication but angular only has POC when the object created on the client side and there is no post to server side,
    I tries to make POC with client-server communication between angular and web api and here is some problems I met:
    1. The TE on angular work with proxy that the ctor create, in case that I get my object from http request the result is a json and the conversion to the model that extend the TE is not working (I found a workaround that after the get send the result to the ctor and then it worked-but it is not sound ok to do this regularly)
    2. After I have changes on my object I want to send it to server side as body of post request but I get console log of circular reference (=it failed on the serialization) (I found a work around that my model have toJson function but still it doesn’t sound like the best practice)
    3. I want that every model that I get from my webapi to have the tracking=true, but as I see in my code I need to set it after I get the object from the webapi, my object have many inner models so I have to set the tracking=true by running though all my object (this scenario doesn’t sound as best way)
    I will be glad if u can make your opinion on the problems above if I can avoid these problem without using my workarounds
    thanks a lot

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.