Read Methods Understanding - lobodava/artisan-orm GitHub Wiki

In order to fetch data from a database the Artisan.Orm has a bunch of Read methods:

Method Description
ReadTo<T> to read a single value or object using an existing mapper
ReadToAsync<T> to read a single value or object asynchronously using an existing mapper
ReadAs<T> to read a single object using automapping
ReadAsAsync<T> to read a single object asynchronously using automapping
ReadToList<T> to read a list of values or objects using an existing mapper
ReadToListAsync<T> to read a list of values or objects asynchronously using an existing mapper
ReadAsList<T> to read a list of objects using automapping
ReadAsListAsync<T> to read a list of objects asynchronously using automapping
ReadToArray<T> to read an array of values or objects using an existing mapper
ReadToArrayAsync<T> to read an array list of values or objects asynchronously using an existing mapper
ReadAsArray<T> to read an array list of objects using an automapping
ReadAsArrayAsync<T> to read an array list of objects asynchronously using an automapping
ReadToObjectRow<T> to read a single ObjectRow using an existing mapper
ReadToObjectRowAsync<T> to read a single ObjectRow asynchronously using an existing mapper
ReadAsObjectRows to read ObjectRows using an automapping
ReadAsObjectRowsAsync to read ObjectRows asynchronously using an automapping
ReadToDictionary<TKey, TValue> to read a dictionary of objects with first column as a key using an existing mapper
ReadToDictionaryAsync<TKey, TValue> to read a dictionary of objects with first column as a key asynchronously using an existing mapper
ReadAsDictionary<TKey, TValue> to read a dictionary of objects with first column as a key using an automapping
ReadAsDictionaryAsync<TKey, TValue> to read a dictionary of objects with first column as a key asynchronously using an automapping
ReadToEnumerable<T> to read an IEnumerable of objects using an existing mapper (sync method only)
ReadAsEnumerable<T> to read an IEnumerable of objects using an automapping (sync method only)
ReadToTree<T> to read a list of objects using an existing mapper and build a single root tree
ReadToTreeList<T> to read a list of objects using an existing mapper and build a multiple roots tree

Note:

All the above methods can be used on three levels:

  • Base level,
  • Command level,
  • Reader level.

Base Level Methods

If a repository is derived from the Artisan RepositoryBase then a repository method can use Read methods of the base:

public class Repository: RepositoryBase
{
    public User GetUserById(int id)
    {
        return base.ReadTo<User>("dbo.GetUserById", new SqlParameter("Id", id));
    }
}

or even omit the base keyword:

public class Repository: RepositoryBase
{
    public IList<User> GetAllUsers()
    {
        return ReadAs<User>("dbo.GetAllUsers");
    }
}

New overloads from version 1.1.1:

public class Repository: RepositoryBase
{
    public User GetUserById(int id)
    {
        return ReadTo<User>("dbo.GetUserById", cmd => cmd.AddIntParam("Id", id));
    }

    public async Task<User> SaveUserAsync(User user)
    {
        return await ReadToAsync<User>("dbo.SaveUser", cmd =>
        {
            cmd.AddTableRowParam("@User", user);
            cmd.AddTableParam("@RoleIds", user.RoleIds);
        });
    }

    public void DeleteUser(Int32 userId)
    {
        Execute("dbo.DeleteUser", cmd => cmd.AddIntParam("@UserId", userId) );
    }
}

Command Level Methods

For more convenient command configuration the RepositoryBase has GetByCommand and RunCommand methods, where the above Read methods can be called as extension methods from the command argument:

public class Repository: RepositoryBase
{
    public User GetUserById(int id)
    {
        return base.GetByCommand(cmd => 
        {
            cmd.UseProcedure("dbo.GetUserById");
            cmd.AddIntParam("Id", id);

            return cmd.ReadTo<User>();
        });
    }
}

with omitting the base keyword:

public class Repository: RepositoryBase
{
    public IList<User> GetAllUsers()
    {
        return GetByCommand(cmd => 
        {
            cmd.UseProcedure("dbo.GetAllUsers");
            return cmd.ReadAsList<User>();
        });
    }
}

Reader Level Methods

When it's necessary to read multiple recordsets the Read methods can be called as extension methods to SqlDataReader:

public class Repository: RepositoryBase
{
    public User GetUserById(int id)
    {
        return GetByCommand(cmd => 
        {
            cmd.UseProcedure("dbo.GetUserById");
            cmd.AddIntParam("Id", id);

            return cmd.GetByReader(dr => 
            {
                var user = dr.ReadTo<User>();
                user.RoldeIds = dr.ReadTo<int>();
        
                return user;
            } 
        });
    }
}

See also:

⚠️ **GitHub.com Fallback** ⚠️