Working with data¶
Every persisted class in a business object comes with operations for creating, finding, saving and deleting records. You do not write a data layer. The operations are listed in the Domain library.
Create and save¶
var product = Domain.Product.Create();
product.Name = "Notebook";
product.Price = 5;
product.Save();
Create() makes a new object in memory. Nothing is stored until you call Save(). IsNew() is true until the first save.
Find records¶
| Call | Returns |
|---|---|
Domain.Product.Find(p => p.Price > 100) |
The products that match. The query runs in the database. |
Domain.Product.Find(...).First() |
The first match, or null when nothing matches. It never throws. |
Domain.Product.Find(...).Length |
How many match. The count runs in the database. |
Domain.Product.GetAll() |
Every product. It loads the whole table, so prefer Find. |
Domain.Product.GetByKey(id) |
The product with that key. |
Domain.Product.Find(..., skip, take, ...) |
One page of matches, with optional ordering. |
var cheap = Domain.Product.Find(p => p.Price < 10 && p.Stock > 0);
var one = Domain.Product.Find(p => p.Name == name).First();
if one != null
{
// found it
}
Use Find when a record may not exist
GetByKey is meant for keys you know are valid. For a key that may be missing, such as one taken from a URL, use Find(p => p.Id == id).First() and check for null.
Write queries the database can run¶
The lambda you give to Find is translated into a database query. Keep it to simple comparisons of attributes and values:
- Compare attributes with
==,!=,<,>and combine them with&&and||. - Values from
thisor from parameters are fine. They are read before the query runs. - Do not call your own operations inside the lambda. Find the records first, then call operations on the result.
// In the query: only simple comparisons
var open = Domain.Order.Find(o => o.Status == Domain.OrderStatus.Open);
// In memory, afterwards: your own operations
var late = open.Where(o => o.IsLate());
Once the records are in a collection, you can use any lambda on them. See Types and variables.
Check a count before you compare it¶
Assign the result first, then compare:
Writing Domain.Product.Find(...).Length == 0 directly inside a condition can pass validation and then fail the build.
Change and delete¶
Delete() follows the rules of the model: an association marked as restricted blocks the delete while related records exist, and cascade delete removes the related records with it. See Associations.
Refresh() reloads an object from the database. The Domain library also has DeleteAll, Insert, Update, Merge and Copy.
Saving related objects¶
When a class owns its children, as in an order with its lines, adding a child to the parent and saving the parent saves the children too. For any other kind of association, save each object with its own Save().
Sorting, paging and grouping¶
Sort and slice the result with the collection methods:
On forms, a dataset does filtering, sorting and paging for you, and a list control uses it.
Direct database access¶
Sometimes you need more control. CommonLib has DataContext, which can flush pending changes, evict objects from the session, or run an SQL query. Reach for it only when the operations above are not enough.