Logic Layer

DAL is the data access layer: connections, commands, queries and saves. Most day to day work happens a level above it, in classes that inherit from Logic or LogicRelation<T> and get Load, LoadSet, LoadByRelation, Save and Delete for free. What is left to write is the part that is actually specific to that class: its filters and its business rules.

Logic vs LogicRelation

Inherit from LogicRelation<T> when the class maps to a type with relations, child collections or related objects that should load and save alongside it. Inherit from Logic for a class with no relations to manage.

What you get by inheriting

A class that inherits from LogicRelation<T> gets its CRUD operations for free: Load, LoadSet, LoadByRelation, Save and Delete, built on top of DAL and FluentQuery<T> underneath. Only the parts that are specific to the class need writing.

public class Media : LogicRelation<DC.Media>
{
    public Media(string connectionString = null, string providerName = null)
        : base(connectionString, providerName) { }
}

This class already has working Load, LoadSet, Save and Delete methods, with no other code written.

What you write yourself

A real logic class usually adds custom load methods for its own filters and a small amount of setup. From an actual class in production:

public class Media : LogicRelation<DC.Media>
{
    public string AppConnectionString;

    public Media(string connectionString = null, string appConnectionString = null, string providerName = null)
        : base(connectionString, providerName)
    {
        AppConnectionString = appConnectionString;
    }

    protected override void Init()
    {
        IgnoreTypes = new HashSet<Type>();
        IgnoreTypes.Add(typeof(AccountRole)); // is a relation table, not a result

        AddDefaultSortOrder(new KeyValuePair<Expression<Func<object>>, bool>(() => new DC.Media().Id, false));
    }

    protected override DAL InitDAL(DAL dal = null)
    {
        dal = base.InitDAL(dal);
        return Util.AddCatalog<Account>(dal, AppConnectionString); // Account lives in a separate database
    }

    public async Task<(List<DC.Media> set, int totalItemCount)> LoadSetAsync(MediaFilter filter, int? pageSize = null)
    {
        using var dal = await InitDALAsync();
        PageSize = pageSize;

        var m = new DC.Media();
        var query = ApplyPaging(dal, ApplyDefaultSortOrder(dal.Query<DC.Media>(LoadOneToMany, LoadOneToOne)), filter.PageIndex);

        if (!string.IsNullOrEmpty(filter.FileName))
            query.Where(() => m.Filename).Contains(filter.FileName);

        var list = await query.ToListAsync();
        return (list, dal.TotalItemCount ?? 0);
    }
}

Init() configures relation and sort-order behavior for the whole class. InitDAL / InitDALAsync configure the underlying DAL instance, cross-database catalogs, for example, before it is used, see Mapping. Custom load methods use the same Query<T>() and Fluent Syntax covered on the Queries page, they just start from the class's own configured DAL rather than building one from scratch each time.

Working with DAL directly

The logic layer is built on DAL's own Save and Delete methods and nothing stops you from calling DAL directly for scripts, one-off tooling or anywhere a full logic class is not worth setting up.

dal.Save(customer);
await dal.SaveAsync(customer);

dal.Delete(customer);
await dal.DeleteAsync(customer);

Both accept deep (default true), which cascades to related child objects in the correct foreign key order and refreshModel (default true), which reads database-assigned values, a generated identity, for example, back onto the object after saving.

Batches

dal.SaveSet<Customer>(customers);
await dal.SaveSetAsync<Customer>(customers);

dal.DeleteSet<Customer>(customers);
await dal.DeleteSetAsync<Customer>(customers);

SaveSet and DeleteSet apply the same existence check, deep-save and refresh behavior as Save and Delete, once per item, inside a single transaction by default.

When every record is guaranteed to be new, after a table truncate or a bulk import, for example, SaveBatchAsync skips the existence check, child saves and model refresh that SaveSetAsync performs per item and is significantly faster for that specific case. It does not support child objects or model refresh.

await dal.SaveBatchAsync<Customer>(newCustomers);

Transactions

Every save and delete method accepts globalTransaction, true by default. With it on, the object, its child objects and any model refresh all run inside one transaction, so a failure partway through rolls back everything, not just the last statement. Set it to false when you are managing transaction scope yourself around multiple separate calls.