What's Include() method's job in Entity Framework

Question

I have two entities Permission and Access

Access.cs

public class Access
{
    public int Id { get; set; }

    public string Name { get; set; }

    public List<Permission> PermissionList { get; set; }
}

Permission.cs

public class Permission
{
    public int Id { get; set; }

    public string Name { get; set; }

    public int ParentId { get; set; }

    [NotMapped]
    public bool HasChildren { get; set; }

    [NotMapped]
    public List<Permission> ChildPermissions { get; set; }
}

I also have GenericRepository class to filter records in my database.

GenericRepository.cs

 public virtual IEnumerable<TEntity> Get(
            Expression<Func<TEntity, bool>> filter = null,
            Func<IQueryable<TEntity>, IOrderedQueryable<TEntity>> orderBy = null,
            string includeProperties = "", bool tracking = true)
        {
            IQueryable<TEntity> query = dbSet;


            if (filter != null)
            {
                query = query.Where(filter);
            }

            foreach (var includeProperty in includeProperties.Split
                (new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries))
            {
                query = query.Include(includeProperty);
            }
        /*...*/
        }

I call this method in my Access Service class

AccessService.cs

GenericRepository<Access> accessRepo = new GenericRepository<Access>();
List<Access> accessList = accessRepo.Get(d => d.Name == accessName, null, "PermissionList").OrderBy(d => d.Id).ToList();

This code filters records type of "Access" and then uses Include() method with "PermissionList" parameter in the Generic Repository. What's Include("PermissionList") method's job? What does it do? PermissionList is a property of Access and has elements type of Permission. But I couldn't totaly get what's its aim.

Answer 1

It is for eagerly loading related entities.

See Entity Framework Loading Related Entities.

When not using Include(), this query:

using (var context = new YourContext())
{
    var access = context.Access.Single(a => a.ID == 42);    
}

Would return an Access instance with an empty PermissionList property. Depending on how your context is configured, this collection would remain empty (no lazy loading) or would be lazy-loaded as soon as you access it (foreach (var permission in access.PermissionList) { ... }).

Now with Include():

using (var context = new YourContext())
{
    var access = context.Access.Include(a => a.PermissionList)
                               .Single(a => a.ID == 42);    
}

The query will be written as a join, loading all related permissions for you.

The Include() extension method also has a string overload, which your repository code is invoking:

query = query.Include(includeProperty);

This causes in your case "PermissionList" to be eagerly loaded, and it seems to support multiple Include()s using a comma-separated list (e.g. "PermissionList,PermissionList.ChildPermissions").