Simple.Data change: FindBy is deprecated for 1.0

When the guy who’s writing your documentation is getting confused by your API, it’s time to do something about it.

What’s changing?

The first method that Simple.Data ever had was FindByXyz, and all it did was blindly generate a SQL Server compatible “SELECT * FROM” statement and return the first record it found as a dynamic object. At the time, I really hadn’t put any proper thought into the design of the API, because, well, it wasn’t an API, it was just a proof-of-concept.

Since then, about half the questions I answer are along the lines of “why doesn’t this work”:

var customers = db.Customer.FindByRegion("NW").ToList();

The answer, of course, is that FindBy returns a single record; you want FindAllBy.

The problem is that even I get it wrong. If I had a magic wand, and could change one thing in Simple.Data without breaking anybody’s code, I’d make FindBy return a query and get rid of FindAllBy. Sadly, I can’t do that. The best I can do, for now, is to make this announcement that FindBy is deprecated, and make it write a Trace Warning if you use it in your code.

So how do I find a single record?

Much like you would using LINQ:

var justOneCustomer = db.Customer.FindAllByName("Phronesis").FirstOrDefault();

Simple.Data will use that FirstOrDefault to intelligently limit the number of returned results in the generated SQL (for example, using TOP 1 in SQL Server) so you won't get enormous result sets being generated.

Of course, if you have a primary key, you can still use Get which will continue to return a single record:

var justOneCustomer = db.Customer.Get(42);

Define "deprecated"

Deprecated means that the FindBy method will continue to work in Simple.Data 1.0 and all subsequent 1.x maintenance releases.

In Simple.Data 2.0, which is already in development, FindBy won't work at all, and if you try to use it you'll get a very specific Exception telling you not to.

At some point in the Simple.Data 2.x lifecycle, FindBy will become an alias for FindAllBy, and that will be an end to it.

Comments

  1. Thank you!
    I for one have run into that problem more than once. This is much clearer.

  2. Obligatory FindBy deprecation reactionary comment:
    You can’t do this my whole codebase will stop working! ;-)

  3. I write one little email… ;-)

  4. Kyle Fisher says:

    Using FirstOrDefault(), what is “Default” going to mean? Null or a new, empty object with actual defaults?

Trackbacks

  1. Inferred Hierarchies and Evaluation Strategies in Simple.Data…

    This is the second of a number of posts derived from the documentation for Simple.Data that I’m…

Leave a Reply

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

WordPress.com Logo

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

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 4,006 other followers

%d bloggers like this: