I'm back at Microsoft.  I had a great time outside the company including working for several years with my brother on a startup, but now I'm excited to be back.  I've now joined the Azure Information Management and Machine Learning organization, and I'm working on a cool technology called program synthesis.  More details soon.

- Danny

If you are interested in following my adventures as I step out of the reality distortion bubble surrounding 1 Microsoft Way and enter some new form of reality distortion bubble, I'm now going to blog at blogs.the-simmons.net/danny

One of the best parts about working at Microsoft is the opportunity it gives you to explore a variety of things and work on multiple different projects without the impact on the rest of your life associated with changing companies.  So I’ve decided the time has come for me to take advantage of this unique employment situation and explore some new challenges elsewhere in the company.  Thankfully, I know that I’m leaving the EF in very good hands and that it has a wonderfully bright future ahead of it.

In case you are wondering where I’m going, I’m joining an incubation team which is in charge of, among other things, the phoenix project.  Specifically I’ll be working on ahead-of-time compilation for c# in order to solve some really challenging problems in system programming.  One of the things that has come out of the last several years for me is a real love of programming in c#, and this project has the potential to help extend the use of c# into domains where it can’t be used today.  The team I’m joining faces some challenges which will benefit from my past experience, and at the same time there is a vast new domain to learn about where I have no experience (compilers).

So today I lay down my claim to the title “system.data.objects dev guy”, and take up the mantle of “compiler padawan.”  (My wife asks if I’m going to grow a small padawan braid at the back of my head, but I really don’t think anyone wants to see that, so I suppose I’ll pass.)

- Danny

For my first attempt I did the easiest thing (and the one most frequently shown in simple WPF graphics demos) which is to use a Canvas and create on it a series of Line objects.   The result looked like this:

[STAThread]
public static void Main()
{
    var app = new Application();
    var window = new Window();
    var canvas = new Canvas();

    window.Content = canvas;
    canvas.Children.Add(new Line
        {
            X1 = 0,
            Y1 = 0,
            X2 = 400,
            Y2 = 400,
            Stroke = Brushes.Black
        });
    canvas.Children.Add(new Line
        {
            X1 = 0,
            Y1 = 400,
            X2 = 400,
            Y2 = 0,
            Stroke = Brushes.Black
        });

    app.Run(window);
}

While this approach worked for my initial drawings and was quite easy, I became concerned when I wanted to introduce some animation because I had cases where I wanted to animate a figure made up of a large number of lines as though it was one thing, and it began to get a bit ugly to setup.  In addition I started to worry a bit about perf, and even though I didn’t have the full program running yet so I wasn’t able to actually measure the perf, my reading on the net led me to think those worries were justified.

One fairly commonly recommended alternative approach is to use a DrawingVisual which as I understand it is basically a lower level construct which allows you to compose a number of drawing commands as though they were a single control in the visual hierarchy.  Rather than each part of the drawing being full-fledged controls with their own events and everything, you create a series of drawing commands and put them inside a single object that is the only thing which has events and such.  This is supposed to be faster, and it’s also supposed to allow you to use things like DrawingGroup which can cause all its contents to animate together as one thing—just what I wanted!

When I started to try this, though, everything I did seemed to just display a blank screen.  My app would start, and the window would come up, but the graphics weren’t drawn into it.  I looked at several samples—many of which were all in xaml—and you’d think that they would convert easily to code since xaml is just a straightforward mapping onto object creation after all, but I just couldn’t make it work.  After much banging my head on the wall and searching on the net I eventually discovered that one of the main places I was looking, MSDN, had a sample with code shown on the help page that was incomplete.  There was a small link to another page where you could go download the full sample, which worked fine.  So a fair amount of scratching my head and trial and error later led me to the discovery of what was in that sample which was missing from my code.  Hopefully this post will help some other poor wpf graphics programmer figure out their problem sooner.

It turns out that the key to my whole mess was creating the “visual host” control which would contain my drawing.  This control inherits from FrameworkElement and provides the infrastructure for event handling and other things.  It plays a role much like the canvas in the sample above except that with the canvas, each child is also something that inherits from FrameworkElement whereas when using a VisualDrawing this is the only thing that does that and all of its children are just simple drawing components.  In addition to inheriting from FrameworkElement, the visual host needs to contain a VisualCollection object which is a container for its children.  That much I had working.  The part that had escaped me was that you are also required to override a property and a method from FrameworkElement.  The property is VisualChildrenCount.  It needs a getter and it should just return the count value from the VisualCollection.  The method is GetVisualChild and it just returns the child with the specified index from the VisualCollection.

Unfortunately these aren’t abstract so the compiler won’t catch the issue and tell you that you must override them, but if you don’t, then the framework never becomes aware of your child objects and the result is that nothing is displayed.

Once over that hurdle, everything works great.  The final program (equivalent to the one above) looks like this:

[STAThread]
public static void Main()
{
    var app = new Application();
    var window = new Window();
    var host = new MyVisualHost();

    window.Content = host;
    app.Run(window);
}

public class MyVisualHost : FrameworkElement
{
    private VisualCollection children;
        
    public MyVisualHost()
    {
        children = new VisualCollection(this);

        var visual = new DrawingVisual();
        children.Add(visual);

        using (var dc = visual.RenderOpen())
        {
            dc.DrawLine(new Pen(Brushes.Black, 1), new Point(0, 0), new Point(400, 400));
            dc.DrawLine(new Pen(Brushes.Black, 1), new Point(0, 400), new Point(400, 0));
        }
    }

    protected override int VisualChildrenCount
    {
        get { return children.Count; }
    }

    protected override Visual GetVisualChild(int index)
    {
        if (index < 0 || index >= children.Count)
        {
            throw new ArgumentOutOfRangeException();
        }

        return children[index];
    }
}

As you can see, the structure of the program is very similar to the first sample except that instead of creating a canvas and then adding child line objects to that canvas, I create a new “MyVisualHost” object which in its constructor creates a DrawingVisual, uses that object to get a DrawingContext and then calls methods on the DrawingContext to draw lines.  Everything but the last two methods is fairly easy to find in samples on the net, but if you omit them, your program will compile—it just won’t work.  Lovely.

- Danny

In an attempt to improve matters, I’ve spent some time over the last few weeks relocating the FAQ to www.ef-faq.org (a domain that I registered personally, not something officially owned or maintained by Microsoft) and changing its source format into a series of text files with simple wiki-like markup maintained under mercurial-based source control at the codeplex project effaq.codeplex.com/.  In addition, some folks on the EF team have put a lot of effort into adding additional questions and answers and updating things based on EF4 so hopefully the FAQ is in a better place than it has been for a while.

Now my hope is that some of you will take a few minutes to help me out in the following ways:

1. Look over the FAQ—maybe you will learn something.
2. Next time you have a question or answer a question, check the FAQ, and if the answer is already there publish a link so that others can more easily find and benefit from it.  Every question has a fragment name based on the section and question #.  So if you want a link, for instance to Code Generation Question 12.2 (“Is there any way to use public, easily modifiable templates for EF code generation?”), the link would be www.ef-faq.org/code-generation.html#12.2
3. If the question you have is NOT answered in the FAQ, and you think it is something others may also run into.  Please, PLEASE, take the time to enlist in the codeplex project, edit the source, make a fork and send a pull request so that we can incorporate your change and push it up to the site.  This is designed to be a pretty easy process, and it can really benefit your fellow programmers.

For the curious, here’s a little background about how the new EF FAQ site is put together: After casting about for a bit, I decided that I wanted to have a static site with pretty simple HTML so that it is simple, quick and search-engine friendly.  I wanted more formatting than I could get from strict plain text, but I wanted something simpler and more constrained/uniform than what I could get out of word or something like that.  In the end I decided to take the markdownsharp library (thanks Jeff and others), extend it a little bit to add the concept of “sections” and “questions” which get auto-numbered, have some specific HTML markup and help to produce an auto-generated index of sections for navigation.  I also wrote a simple program to wrap the generated content HTML in a high-level template so that every page gets a header, footer and navigation bar and to manage the workflow of turning the various source files into all the HTML for the site.  You can find the source for my “faqbldr” app as part of the codeproject as well, and soon I hope to push my extensibility hooks for markdownsharp back into its repository so that I can remove its source from the codeplex project and just check in a binary nuget-style.

By the way, if you are an HTML and CSS guru with a strong stomach, you might want to take a look at template.html in the codeplex project where I have created a horrendous mess that no doubt violates every rule of good HTML design but somehow seems to have landed in a place where the site works and looks OK as long as I don’t touch it any more (If I do I’m pretty sure the whole house of cards will come tumbling down).  Someone who wasn’t such an awful html hacker like me could no doubt make it cleaaner, nicer looking and faster.

One last comment, while the FAQ has originally been produced by members of the EF team (and likely some EF team members will continue to contribute to it), it is definitely my intention that this not just be a Microsoft effort.  This isn’t official documentation.  Ideally it should be a helpful resource that contains whatever info you need to help get your tasks programming with the EF done (or more frequently pointers to where to find the more complete details on what you need).  This means that if you have negative comments about the EF in some area or positive comments about some other product that you would use in conjunction with the EF or instead of it in some scenario, those belong here as well—as long as they are constructive and help achieve the goal of making people successful at building great software.  Happily Craig Stuntz has agreed to start contributing to the project, and it’s my hope that we’ll have others join in soon.

- Danny

P.S. If you visit the site in the next day or two, you will find that the bing search box in the upper left isn’t fully working yet because the site is so new and bing hasn’t indexed it, but that should fix itself in the next few days.

Question #1: Where is the hot path?

The first thing to think about in broad terms is where is the time really going.  Often it’s relatively easy to introduce a few counters or make some other small hack to find the worst offender in your application.  My first bit of advice to you on this front is: Don’t be afraid to make temporary changes to your code.  You can sometimes get great results by making a fresh enlistment in your source control system, checking out a bunch of files and hacking on the code in ways that you would never ship but which help to isolate things so you can figure out what’s really going on.

My next suggestion is: Get a profiler and figure out how to use it.  Visual studio has a great profiler if you have a sufficiently advanced version, and that’s what I use, but there are other products on the market.  There are even some profilers specifically aimed at working with applications built on top of the EF.  In any case, if you care about perf, a profiler is hugely important.  I’m no expert on any of these, but you can find some great resources on the web.  Some of the the articles I’ve found useful for working with the VS profiler are: msdn.microsoft.com/en-us/magazine/cc337887.aspx and www.wintellect.com/CS/blogs/jrobbins/archive/2009/10/19/vs-2010-beta-2-sampling-and-instrumentation-profiling-in-depth-first-look.aspx.

However you decide to measure things, the first level of investigation which I’d recommend when you are looking at an EF-based application is to determine where your biggest bottleneck is:

• your application
• EF one-time startup
• EF query code
• network transmission
• or the database

If you can figure this out, then you can much more quickly home in on where to investigate further and what experiments you might want to try to improve performance.

What happens during the execution of an EF query?

In order to get to the next level of your investigation, it can help a lot to have a general idea of what all is happening and in what order when you execute an EF query.  To that end, here’s a rough list:

• Startup: When you first create an ObjectContext, it will load metadata describing your model.  The first time a context is created in an app domain, that metadata is loaded either from resources in your assemblies or from files on disk.  On subsequent context creations the data is loaded from an in-memory cache making it much faster.
   
• Startup: The first time you execute a query on the first ObjectContext instance for an app-domain, the EF will generate an in-memory structure (called the query views) which it uses for query translation.  For every query after that, it will simply retrieve the views from an in-memory cache.  This view generation step can be very time consuming—especially for large, complex models.
   
• Query: Next the query is translated from LINQ or ESQL into your backend database command (TSQL in the case of SQL Server) and the results assembly plan is created.
   
• Query: The connection is opened if it isn’t already.  By default the EF will open the connection before each operation and close it when the operation is complete.  If you open the connection manually, though, the EF will leave it alone so it can be kept open if you are performing multiple operations in a row, and this can sometimes be a significant perf win.
   
• Query: If a TransactionScope is active, then the connection is enlisted in the transaction.  The effect of this depends on the ado.net provider—for sql server 2008 this is usually cheap, but for earlier versions of sql server if the connection has been previously opened and closed and was just opened again all within the same transaction (or for any provider if more than one transaction participant is involved), then the transaction is promoted to a distributed transaction which can be very expensive.
   
• Network: Send query to the database.  Typically this part of the process is inexpensive because the amount of data required to send the query to the database is usually small.  Network time is more of a factor when results come back later.
   
• Database: Execute the query.  What this entails obviously depends on the complexity of the query, the indexes that are configured and the particular database server involved among other things.  Most modern databases have their own fairly sophisticated query optimization system as well as execution plan caches and other mechanisms to help here.  In the case of sql server, the complexity of the query being executed is only one of the tools available for tuning, indexes and statistics can be added to the database and even plan guides can be used to give the database hints about how to execute the query efficiently.
   
• Network: Return results from the database.  This can become a significant factor if your query returns extra data which isn’t actually needed by the app.  In addition, things like eager loading can help perf by reducing the number of network round trips, but they can also hurt performance by causing redundant data to be returned since the way entities from different tables are returned is through the use of a join which often causes some data to be repeated—this repeated data is accounted for during the result assembly process so you end up with accurate results, but there is still overhead in the data returned over the network.
   
• Query: Check the ObjectStateManager by key to see if the entity in question is already present (unless MergeOption is NoTracking).
   
• Startup: The first time a particular entity type / query result shape is returned, dynamic code is generated which extracts the relevant data from the DataReader, constructs the object and initializes it with data (called materialization).
   
• Query: Objects are actually materialized.
   
• Query: Objects are added to the ObjectStateManager (unless MergeOption is NoTracking).
   
• Query: Relationships between entities are fixed up.
   
• Application: Results are processed potentially causing additional queries (especially through lazy loading, etc.)

OK.  Now you know what goes on under the covers, and you’ve found something that seems to be taking more time than necessary.  That brings us to…

What can be done to improve EF query perf?

Here’s a general rule-of-thumb checklist for EF query perf tuning in the order I would tend to investigate (since this is usually the order of highest bang-for-the-buck).

DANGER!  DANGER!  DANGER!  If you read my post about perf tuning philosophy, all kinds of bells should be going off in your head about now.  You should be saying something like, “I thought perf was a science and I should measure what exactly is the issue, create my own prioritization and then do a series of carefully controlled experiments.”  Of course all those things are true.  You SHOULD measure the reality in your particular situation.  That said, I get asked these kinds of questions quite often, and some of these issues show up frequently enough that it if it’s not too expensive to try one of these fixes, you might just try them and measure the results—this could be cheaper to try than deep profiling or the like.

1. Pre-compiled views.  Usually a very easy to implement change is to turn on pre-compiled views.  This will move the time of generating views from the first query in your app-domain to design time.
    
2. Avoid distributed transactions.  If your app is triggering distributed transactions, getting rid of that can be a MAJOR perf win.  So even though this can be more involved, it’s worth looking for.  If you are using SQL Server 2000 or 2005, this can be caused just by opening and closing the connection more than once inside the same transaction, and if that’s the case the fix is as simple as explicitly opening the connection before the first operation inside the transaction and then either explicitly closing it when the transaction is done or letting it be closed when the context is disposed.
    
3. Avoid extra connection opens.  Even if you aren’t getting distributed transactions, if you have a number of operations all in a row, just opening the connection can be expensive.  As with the best case of distributed transactions, it can be easily addressed by explicitly opening the connection before the first operation.
    
4. Reduce database round trips.  Eager loading through the Include method can cause graphs of related entities to be retrieved in a single round trip rather than several.  This can be an especially big win if you are using lazy loading to retrieve a graph of related entities across a 1-many relationship like a set of customers and their orders.  With lazy loading this will take one round trip for the customers + one round trip for each order, while lazy loading could return the entire set in a single round trip.  Be careful, though, to balance the cost of round trips against the cost of extra network traffic and query complexity.  If you have a large graph of related entities (across several relationships), using eager loading to retrieve the whole thing may not be the most efficient.  Often the best answer is a combination with some eager loading and some lazy loading or some other combination.  The only way to tell is to try things and measure.
    
5. Retrieve less data.  Often this is the first thing your DBA will tell you: Quit retrieving data that you don’t actually use in your app.  If you only want to display a list of customers and their zip codes, then retrieving the entire customer object might be a bad idea.  On the other hand, it may be that querying for the customer object up front will allow you to avoid later queries for the rest of the data, so it’s a balance and you have to try things and measure.
    
6. Reduce post DB-query client processing costs.  Often the simplest way to do this is to set the MergeOption of the query to NoTracking.  When you do this the EF will no longer check the ObjectStateManager to see if the entity is already present there, and after the objects are constructed, it will not add the entity to the ObjectStateManager.  This can often produce a significant perf improvement, but you have to keep in mind the side effects this will cause since entity change tracking and identity resolution will no longer happen, etc.
    
7. Reduce pre DB-query client processing costs.  If you only execute this particular query once, then there’s really not much you can do, but if you execute the same query multiple times and you use ESQL, then the EF will automatically cache the translated query.  For LINQ, though, the EF doesn’t automatically cache the query which is where LINQ compiled queries come in.  They allow you to explicitly do the translation ahead of time, hold onto a token representing the query and then use that token to execute it each time.
    
8. Reduce complexity of the DB query.  You may find opportunities to do this by adjusting the shape of the LINQ or ESQL that you write in your application.  More often, though, you should look for ways to adjust the model shape.  Deep inheritance hierarchies with lots of relationships, and especially if they use TPC-style inheritance tend to create complex queries.  If you can reduce the depth of your inheritance hierarchy, write queries that return fewer different types in a single query, or switch from TPC to TPH or something like that, the result will tend to be less complex.  While the EF often does a great job in the database queries that it generates, occasionally it will produce a query which is less than ideal.  If you determine this is your bottleneck and you know how to hand-write a better query, then you can consider writing the query by hand as a stored procedure and calling that in order to take complete control over the query rather than letting the EF generate it.

- Danny

There Are Two Ways to Improve Performance

In my opinion, there are basically two different ways to actually improve the performance of an application (improving the performance of a framework or a server overlaps a lot but each has some unique challenges that I’m not going to consider today).  The first technique is all about your application design, and the second is a matter of tuning individual operations. 

Without a doubt the biggest wins come from making good design decisions up front.  What I’m talking about here are coarse-grained things that affect the entire way your app works.  Getting these right is generally either a measure of understanding your problem space well through a lot of experience, being lucky or writing your application, discovering what you got wrong and then completely re-writing large portions of it.  An example of this kind of issue would be the difference between a client-server application where the client is essentially just a dumb terminal that requires every single key-stroke to travel to the server to be handled and one where you have a smarter client that does a fair amount of display, validation and other logic on the client giving great responsiveness and then just sends larger batch operations to the server.  If you happen to choose the first approach, you might discover huge perf problems, and if that happens it will be a major issue to redesign your application to the second approach.

While the first approach is largely about forecasting where you are going and making sure you create an architecture that leads you down the right path for your largest decisions, the second approach looks at how to improve much finer-grained individual scenarios.  The techniques you use for this approach are much different than those used for the first one.  In fact, often if you try to think carefully and optimize your fine grained operations up front in the way you do for the overall architecture, you will introduce a ton of complexity which makes your application much harder to develop, test and maintain and even after all that experience shows that most often you will not have actually improved the performance in a way that has a meaningful positive effect on the end user experience—you may actually have made it worse.

So while design is very important, tuning is also critical to get a great experience from your app.

Tuning is Experimental Science

While lots of what we do as software developers is very different from experimental science (resembling something closer to craftsmanship involving a mix of art & science, engineering & design), performance tuning done right is ALL SCIENCE.  We need to have an understanding of the underlying concepts, to have some intuition about what will and will not work, but just like an experimental scientist we have to train ourselves to thoroughly harness that intuition and slave it to a process that will lead us to results we can prove and depend on.

I like to tell developers on my team, “If you think you know what will improve the perf, you are almost certainly wrong.”  As developers we often have that feeling that we just know what is wrong with the code, and we want desperately to dive in and implement our fix.  In practice, though, often we’re wrong.  Oh sure, we will improve the performance of some part of the code, but unless we’ve done a very careful investigation first we may have made an improvement in an area of the code that is already so fast it doesn’t matter while ignoring or maybe even making worse the hot path (the thing that is the current slowest part which has the most effect on the user experience).  Further, we often have a tendency to take a shotgun approach and make a lot of changes before measuring again with the result that if the perf gets better, worse or stays approximately the same we have no way to know what change we made is responsible.

The only real answer is to make a baseline measurement, look at the data, create a hypothesis and then make the smallest possible change to test that hypothesis.  Further, it’s super important that we carefully prioritize our experiments.  We want to go after the lowest hanging fruit.  That is to tackle those problems which will have the biggest impact on the end user experience for the lowest possible cost in terms of development cost and final code complexity.  Obviously this means we have a tendency to look for the hot path through the application as the first step, but we also have to apply a complexity filter since it may be that the hot path is something that would be very hard to change, while there may be 2 or 3 other things that are almost as significant as the hot path but much easier to change.  Just always remember: measure, measure, measure.  When we’re done we want to KNOW the app will be faster and that we’ve gotten there as quickly and easily as possible.

Tuning Improvements Tend to be the Enemy of Clean Code

To add further strength to the comment that we want to make the cheapest possible changes, I’ll point out that while top-level architecture design style perf improvements can often make your application even cleaner and easier to understand and work with at the same time that they improve performance, the kinds of changes you make when tuning tend to have the opposite effect.  So you want to start with the simplest, cleanest possible implementation for every part of your app.  Remember: You never know in advance where the tuning will really be needed so wait until you can measure and find out where you have to introduce the hacks rather than putting them in up front.

One example of this principle comes to mind from when I used to work on Excel a number of years ago.  Excel is a product that has been around for a LONG time in software years, and it’s been through a lot of changes.  When I worked on the product it had already been around a long time so there was a lot of legacy.  One aspect of this legacy was a perf optimization they had put into the product back when it was being used on MUCH slower systems than we have today.  There was this code which was used to interpret the core data structures representing cells in the spreadsheet.  The structure itself was highly optimized to make cells take as little memory as possible with the result that the bytes in memory could have one of several meanings so the code would look at a few bits up front to figure out how to interpret the rest.  Not only was this data structure very complicated, but to make matters worse the code for interpreting the structure was repeated all over the code base.  They went to great lengths to make sure it stayed the same everywhere, but nevertheless it was repeated.  They had done this for very good reasons.  At the time it was first done that way, the cost of calling to a single central routine to interpret the structure in all the many places that needed to interact with it was just too high.  If they had to make that jump every time and then return, recalcs would take forever.  The problem was that by the time I was working on the project, there really wasn’t anyone left on the team who knew every place that might have a copy of that code, and when we wanted to introduce a change to the data structure, the cost was astronomical to hunt down every case and fix it and then to test the product like maniacs to make sure we hadn’t missed anything.  At about the same time, a related small project rewrote the core spreadsheet engine from scratch in a small component designed for plugging into web pages.  Since this was written from scratch in an era where computers had sped up considerably, this little component was able to centralize its code for the same task with the result that it had more features in some areas than the big brother excel product for several years until excel could finally be updated.

The moral of the story? Start clean, measure carefully, tune in biggest-bang-for-the-buck order.  Stop tuning as soon as you can.  (Which implies that you need to know just how fast is fast enough.)

- Danny

Authentication

Somewhere along the way between the last D3 release and this one I had knee surgery.  My recovery was actually pretty quick, but I did end up spending most of a week sitting at home with my knee in the air and a computer on my lap.  I spent a frighteningly large amount of time trying to read up on ways to do authentication using WCF for the D3 project.  One of the best blog posts I found was this:

blogs.infosupport.com/blogs/alexb/archive/2009/10/02/silverlight-3-securing-your-wcf-service-with-a-custom-username-and-password-authentication-mechanism.aspx

The overall approach really seemed to match my general goals in the sense that I want the service to be essentially secure and WCF to handle that security in a relatively transparent way, but I also want to have my own username and password tracking in my EF model (I don’t want to create windows accounts on a domain controller for every user of D3 or something like that).  The issue that drove me nuts is the fact that this approach absolutely requires SSL and at the time I was working on it there really wasn’t a good way to get SSL running (even with just a test cert) inside of VS because Cassini (the mini-webserver built into VS) doesn’t support it. 

Since then the IISExpress project seems to have gotten off the ground, and it may well be the right long-term answer, but after much banging of my head against this particular wall, I decided that for the current interim release I would completely fake all of this in a hacky way that would leave us setup for the right thing but be clear to implement now.  What I did was to add a username and password parameter to every method on the service.  We’ll return to this in a later release and make things more secure and nicer to use.

Service Contract Design

As I have written in other places (such as this short series of MSDN Magazine Articles: Anti-Patterns To Avoid In N-Tier Applications, N-Tier Application Patterns & N-Tier Apps and the Entity Framework: Building N-Tier Apps with EF4), there are lots of patterns/approaches that can and should be considered when designing a service.  While especially typical intranet line-of-business applications will benefit from the developer productivity and simplicity of an approach like self-tracking entities or RIA services, in this case my goal is to create a game that will run over the internet which means that I’d like to take more control over the contract. 

That led me to the decision that D3’s service should be fairly strictly SOA—at least for the most commonly used methods (issuing commands from the client and retrieving events from the server).  For these two core commands, I decided that the service should neither accept entities as parameters nor return them as results.  We just want the simplest, most basic possible interface, and the result is the following two method signatures:

[OperationContract, FaultContract(typeof(CommandFault)), ApplyProxyResolver]
void ExecuteCommand(string userName, string password, int playerId, string command);

[OperationContract]
Tuple<IEnumerable<string>, int> GetEventMessages(string userName, string password, 
                                                 int playerId, int lastSeenEventId);

Ignoring the authentication parameters (which as discussed above should go away in a later release), the first method takes a player ID and a string representing the command that the player wants to execute—typically this will be something like “go north”, “get fancy sword” or “attack purple snorklewacker”.  You’ll notice that this method does not return any results—the only interesting result is if the command is invalid in which case the service will return a CommandFault with the error message.

The way the service returns the results of commands as well as the observable actions of others in the game is through the GetEventMessages method.  It also takes a player ID to determine the perspective of the player from which the events are observed, and it takes the ID of the last event which was returned by a previous call to GetEventMessages.  This method returns a tuple which contains an enumerable of strings which are messages to display on the client plus the ID of the last event which produced a member of that last event of messages.

The idea is that the client will have two asynchronous UI interaction streams going on.  First, at any time the player can type a command and send it to the server, and assuming the command was valid the server will process the command using its business logic and create events representing the result of that command.  The second thing going on is that the client will periodically poll the server for new event messages observed by the player.  The events which produce these messages are both those created as a part of processing this player’s commands as well as events caused by everyone else in the game.  Each time the client calls the GetEventMessages method, it will get back any messages that it hasn’t yet seen plus an ID used in the next call to the method to indicate the “high-water mark” of what it has already seen.

Obviously the GetEventMessages method will be the most frequently called top-level method in the entire application (every client will poll it frequently in order to maintain its UI).  So it will be very perf sensitive.  In subsequent blog posts, I’ll take a look at the topic of tracking and tuning the perf of this method.

Unit Testing vs. Integration Testing

If you’ve been reading my blog, you probably know by now that I’m a huge fan of unit testing, and I’ve been putting a lot of work into appropriately unit testing D3 as we go.  This has led to finding and fixing a lot of bugs early on, increasing my confidence in my ability to refactor the project frequently without much risk of introducing new subtle bugs and generally a better overall structure for the project.  Unit testing, though, isn’t everything.  When unit testing we try to isolate small parts of the application so we can focus what we test on a very small piece to make it fast and make sure we know what is responsible when a test fails (so it’s easy to fix).  Sometimes, though, you’ve got to move to a coarser granularity and make sure that you have some tests to verify that all the units go together properly. 

This lesson came home to me in a big way when I decided to write a small integration test that would simulate the most common client / service interactions.  I had been unit testing various parts including directly calling the service method implementations, etc., but I hadn’t yet put it all together and run it through WCF.  The code I wanted to get working wasn’t exactly huge or hugely complicated.  It looked like this:

[TestMethod]
public void KickoffScenario_Works()
{
    using (var svc = new PlayerServiceClient(
        new BasicHttpBinding(), 
        new EndpointAddress("localhost:9999/PlayerService")))
    {
        svc.CreateUser("simmdan", "password");

        var id = svc.CreatePlayer("simmdan", "password", "joe");
        svc.GetPlayers("simmdan", "password").Single(p => p.Id == id);
        var logOnEventId = svc.LogOn("simmdan", "password", id);

        svc.ExecuteCommand("simmdan", "password", id, "get item1");
        var eventMessages = svc.GetEventMessages("simmdan", "password", id, logOnEventId);

        var message = eventMessages.Item1.Single();
        Assert.AreEqual("You pick up the Item1.\n", message);
    }
}

As I discovered, though, there were a surprising number of issues that came up including some things that were quick and easy to find and some others that were pretty subtle and took a fair amount of hunting.  Along the way, one thing I found very helpful was this post about turning on WCF tracing: www.c-sharpcorner.com/UploadFile/shivprasadk/6876788978904302009095012AM/68767889789.aspx  Following the directions on that site I added the following XML to the app.config file in D3.Web.Tests:

<system.diagnostics>
  <sources>
    <source name="System.ServiceModel" switchValue="Information, ActivityTracing">
      <listeners>
        <add name="log" type="System.Diagnostics.XmlWriterTraceListener" initializeData="c:\Traces.svclog" />
      </listeners>
    </source>
  </sources>
</system.diagnostics>

Common Issues When Using the EF & WCF Together

So all of that leads me to the following short list of the most common issues I encounter in my own code or when talking with others specific to using the EF and WCF together.

1. Not understanding the basic design patterns involved.  This is by far and away the most common issue.  For this I recommend the magazine articles I referred to in the Service Contract Design section above. 
   
   (Side Note: It used to be that at least as common as this one was the issue of trying to figure out how EF’s disconnected APIs work—even if you did understand the basic patterns, it could be very hard to implement them correctly with the EF.  Happily, since EF4 shipped the APIs are much easier to use, so this is not so common any more.)
    
2. Disposing the context before enumerating a query which is returned from the service method.  This one will get you almost every time.  The general recommended pattern is that each service method should create a context instance in a using block so that it (and its underlying connection) will be disposed properly as soon as possible to free up precious server resources.  If you have a method that returns an enumerable of some type which comes from a query to the database, though, you have to make sure that you fully enumerate that query before the context is disposed.  If you just return the query itself, in a regular CLR method call where the context lifetime is managed some other way, that query would be cast to IEnumerable and the CLR would lazily evaluate it when the results were actually needed.  This is simple and efficient, but in a case where the context is being disposed before the method returns, though, the query results won’t be enumerated until the WCF service’s serializer attempts to process things after the method returns, and in that case the context will first be disposed and then later the query will be enumerated, and it will throw an exception because its connection to the database will be gone.  The fix?  Just call .ToList() on your query before returning.
    
3. Using POCO without thinking through WCF’s requirements for objects it serializes.  If you have a WCF service which accepts entities as parameters or returns them as results and you use POCO entities (maybe by using the POCO T4 template or maybe just writing them by hand), then you have to think about WCF’s requirements for its objects because your POCO objects can be almost anything and they may well not be setup properly to work with WCF.  The three ways this comes up most commonly for me are if you have dynamic proxies (either just for lazy loading or for full change tracking), if you have inheritance in your model which the DataContract serializer is unaware of, or if you want to return entire graphs of entities which have cycles.  You can read about the first two issues (and how to address them) here: blogs.msdn.com/b/adonet/archive/2010/01/05/poco-proxies-part-2-serializing-poco-proxies.aspx the key concepts are the DataContractResolver and KnownTypes.  For the last issue, the answer is in the IsReference=true parameter to the DataContract attribute.  This is a feature that was added in .Net 3.5sp1 which makes the DataContract serializer smarter about graphs of related objects.  You can read more about that here: zamd.net/2008/05/20/datacontract-serializer-and-isreference-property/ 
   
   One thing to watch out for is that if you have POCO entities with no DataContract attributes, the DataContract serializer will handle them fine up to a point, but if you start having more advanced scenarios like graphs of related entities or dynamic proxies, then the default conventions which the DataContract serializer uses will no longer work, and in that case the answer is to add the attributes.  If you are using the POCO template to generate your entities, for instance, it’s pretty easy to hack these into the T4 template which is what I did for D3.  If you are using the default codegen, then all of these things are taken care of for you automatically, but of course there are other advantages to POCO—it’s all a matter of tradeoffs.

OK.  I suppose that’s enough for now.  Happy WCF-service building.

- Danny

This is not all that different from some samples we have put together before.  Sanjay, for instance, wrote a post quite some time ago showing how to enable an extension which would cause code generation to add an arbitrary attribute to classes or properties.  The core capability of adding annotations to the conceptual model metadata as described in that post is still the same.  Since EF4 has shipped, however, we have some additional options which make the overall task a whole lot easier than it was before.  First off, this seemed like a great opportunity to play a bit with the EDM Designer Extension Starter Kit which I had not previously given the time that it deserves.  Of course this is a perfect application for T4 templates which make it much easier to customize code generation (I’ll not give a link for that since we have talked about it a lot in the past—you can easily find more info with a quick search), and the VS2010 VSIX extension format makes it easy to wrap all of this up in a neat package and manage installation and versioning of it.

The final result of this effort is a VSIX package I call EntityRoots which adds an extension to the designer making it possible to set in the properties for an entity type whether or not it is a root which will then show up as an annotation in the CSDL for that entity type as well as a new T4 code generation item template which looks at that annotation in order to decide whether or not to output an ObjectSet property for that type.  In addition to just downloading and using the VSIX package, if you want you can download the solution I use to build it.

For the designer extension, the exercise was mostly just a matter of removing parts of the starter sample that do other things than just adding a property to entity types and renaming things, so I won’t spend much time describing how to do it.  You can follow the example and easily adapt it to whatever other scenario you might have.  Happily the starter kit also automatically creates a VSIX project to install the extension without much effort.  The more interesting part (although also pretty easy) is creating the T4 template, turning it into a VS item template and adding it to the VSIX package.  To do that, my first step was to decide that I wanted to base my template on the POCO template.  You could, of course, do the same thing with the default code gen template, the self-tracking entities template or any other EF code gen template you might have. 

I created a small sample project, added the POCO template, and then just added a few lines to the portion of the template which outputs the ObjectSet properties:

        var entityRootsExist = container.BaseEntitySets.OfType<EntitySet>()
            .Where(s => s.ElementType.MetadataProperties
                .Contains("blogs.msdn.com/dsimmons/schemas/EntityRoot:EntityRoot"))
            .Any();

        foreach (EntitySet entitySet in container.BaseEntitySets.OfType<EntitySet>())
        {
            if (!entityRootsExist || (entitySet.ElementType.MetadataProperties
                .Contains("blogs.msdn.com/dsimmons/schemas/EntityRoot:EntityRoot") &&
                ((XElement) entitySet.ElementType
                .MetadataProperties["blogs.msdn.com/dsimmons/schemas/EntityRoot:EntityRoot"].Value).Value == "True"))
            {
#>

    <#=Accessibility.ForReadOnlyProperty(entitySet)#> ObjectSet<<#=code.Escape(entitySet.ElementType)#>> <#=code.Escape(entitySet)#>
    {
        get { return <#=code.FieldName(entitySet) #>  
                    ?? (<#=code.FieldName(entitySet)#> = CreateObjectSet<<#=code.Escape(entitySet.ElementType)#>>("<#=entitySet.Name#>")); }
    }
    private ObjectSet<<#=code.Escape(entitySet.ElementType)#>> <#=code.FieldName(entitySet)#>;
<#

            }
        }

Essentially we just check to see if any of the entity sets have the annotation.  If so, then we only output an ObjectSet if that set has the annotation and it is set to true.

I then put the modified templates into a project which creates a VS item template (which is just a zip file with the T4 template files plus a vstemplate file giving information about how the templates should be added to the project).  In order to make this item template show up in the EF designer’s add code generation item dialog, the vstemplate file’s name must begin with “ADONETArtifactGenerator_”.  You can read more about VS item templates here.

- Danny

Since I’m stuck sitting at home with my knee elevated as I recover from minor knee surgery, I thought I’d take a little time today to create something which should make this much easier.  You can find the result here.  It’s a visual studio extension file (VSIX) which installs a new T4 item template called EntityHooks.  If you right click on the EF designer background and choose “Add Code Generation Item…”, you should see a new EF EntityHooks Code Generator in the list of templates.  If you choose that option, it will add a new TT file to your project that implements the hooks.

It’s important to realize that this complements whatever other code generation you have going on—it doesn’t replace it.  So if you have already added a code generation item, this will just add another one which generates partial classes that add functionality to your existing partial classes.  Unfortunately, if this is the first code gen artifact you have added to your project, the designer doesn’t realize it doesn’t generate the full entities so it turns off the default codegen, and you will either need to add another codegen artifact or in the properties for your EDMX file set the codegen strategy property from None back to default.

Once this is done you can write your own partial class for any of your entities and implement any or all of the OnAdded, OnModified and OnDeleted partial methods.  These methods will be called whenever an instance of that entity type is in the appropriate state at the time SaveChanges is called, and the call will happen before the framework does any other part of SaveChanges.  So, if your method throws an exception, no save will happen.  This also means that you can modify other entities if you want, or cancel an operation on the particular entity by calling AcceptChanges on its ObjectStateEntry (which is passed as an argument to the partial method).

Here’s a simple example I used to test out the extension.  It’s a hook which takes Customer entities marked for deletion and instead of deleting them just prepends “D:” to the front of the company name as a signal that they are deleted but you still want to keep them around for historical info or something like that:

public partial class Customer
{
    partial void OnDeleted(System.Data.Objects.ObjectStateEntry entry)
    {
        entry.ChangeState(EntityState.Modified);
        CompanyName = "D:" + CompanyName;
    }
}

With this class in place, any attempt to delete a Customer will instead become just a modification.

The extension should work with whatever code generation strategy (default, self-tracking, poco, any custom strategy you create) as long as you generate partial classes both for your entities and your context.  You will notice, though, that it introduces a dependency on the EF since the partial methods receive an ObjectStateEntry argument.  if you want this kind of thing with a truly POCO experience, then you would need to create some other type to abstract away this dependency.  For this exercise I just took the shortcut of passing a state entry because it makes it easy to change the state of the entity or perform other actions in a general way.

The way I implemented this was to output an IEntityHooks interface which declares three methods OnAddedHook, OnModifiedHook and OnDeletedHook, plus a partial class for each entity which implements the interface by having those methods call the corresponding OnAdded, OnModified or OnDeleted partial method which the partial class also declares (can’t have a partial method implement an interface method because the compiler will completely optimize away the partial method if no one implements it), and finally a partial class for the context which overrides the SaveChanges virtual method.  The new SaveChanges method retrieves entries from the ObjectStateManager which represent entities in the various states, casts the entities to the interface and then executes the appropriate hook.

If you want more details, install the VSIX file linked above, add the hook template to one of your projects and have a look.  Pretty straight-forward really.  Let me know if you have any questions.

- Danny