When the guy who’s writing your documentation is getting confused by your API, it’s time to do something about it.
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);
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.