Entity Framework Core Integration Best Practices
See Entity Framework Core Integration document for the basics of the EF Core integration.
- Do define a separated
DbContext
interface and class for each module. - Do not rely on lazy loading on the application development.
- Do not enable lazy loading for the
DbContext
.
DbContext Interface
- Do define an interface for the
DbContext
that inherits fromIEfCoreDbContext
. - Do add a
ConnectionStringName
attribute to theDbContext
interface. - Do add
DbSet<TEntity>
properties to theDbContext
interface for only aggregate roots. Example:
[ConnectionStringName("AbpIdentity")]
public interface IIdentityDbContext : IEfCoreDbContext
{
DbSet<IdentityUser> Users { get; }
DbSet<IdentityRole> Roles { get; }
}
- Do not define
set;
for the properties in this interface.
DbContext class
- Do inherit the
DbContext
from theAbpDbContext<TDbContext>
class. - Do add a
ConnectionStringName
attribute to theDbContext
class. - Do implement the corresponding
interface
for theDbContext
class. Example:
[ConnectionStringName("AbpIdentity")]
public class IdentityDbContext : AbpDbContext<IdentityDbContext>, IIdentityDbContext
{
public DbSet<IdentityUser> Users { get; set; }
public DbSet<IdentityRole> Roles { get; set; }
public IdentityDbContext(DbContextOptions<IdentityDbContext> options)
: base(options)
{
}
//code omitted for brevity
}
Table Prefix and Schema
- Do add static
TablePrefix
andSchema
properties to theDbContext
class. Set default value from a constant. Example:
public static string TablePrefix { get; set; } = AbpIdentityConsts.DefaultDbTablePrefix;
public static string Schema { get; set; } = AbpIdentityConsts.DefaultDbSchema;
- Do always use a short
TablePrefix
value for a module to create unique table names in a shared database.Abp
table prefix is reserved for ABP core modules. - Do set
Schema
tonull
as default.
Model Mapping
- Do explicitly configure all entities by overriding the
OnModelCreating
method of theDbContext
. Example:
protected override void OnModelCreating(ModelBuilder builder)
{
base.OnModelCreating(builder);
builder.ConfigureIdentity();
}
- Do not configure model directly in the
OnModelCreating
method. Instead, create an extension method forModelBuilder
. Use ConfigureModuleName as the method name. Example:
public static class IdentityDbContextModelBuilderExtensions
{
public static void ConfigureIdentity([NotNull] this ModelBuilder builder)
{
Check.NotNull(builder, nameof(builder));
builder.Entity<IdentityUser>(b =>
{
b.ToTable(AbpIdentityDbProperties.DbTablePrefix + "Users", AbpIdentityDbProperties.DbSchema);
b.ConfigureByConvention();
//code omitted for brevity
});
builder.Entity<IdentityUserClaim>(b =>
{
b.ToTable(AbpIdentityDbProperties.DbTablePrefix + "UserClaims", AbpIdentityDbProperties.DbSchema);
b.ConfigureByConvention();
//code omitted for brevity
});
//code omitted for brevity
}
}
- Do call
b.ConfigureByConvention();
for each entity mapping (as shown above).
Repository Implementation
- Do inherit the repository from the
EfCoreRepository<TDbContext, TEntity, TKey>
class and implement the corresponding repository interface. Example:
public class EfCoreIdentityUserRepository
: EfCoreRepository<IIdentityDbContext, IdentityUser, Guid>, IIdentityUserRepository
{
public EfCoreIdentityUserRepository(
IDbContextProvider<IIdentityDbContext> dbContextProvider)
: base(dbContextProvider)
{
}
}
- Do use the
DbContext
interface as the generic parameter, not the class. - Do pass the
cancellationToken
to EF Core using theGetCancellationToken
helper method. Example:
public virtual async Task<IdentityUser> FindByNormalizedUserNameAsync(
string normalizedUserName,
bool includeDetails = true,
CancellationToken cancellationToken = default)
{
return await (await GetDbSetAsync())
.IncludeDetails(includeDetails)
.FirstOrDefaultAsync(
u => u.NormalizedUserName == normalizedUserName,
GetCancellationToken(cancellationToken)
);
}
GetCancellationToken
fallbacks to the ICancellationTokenProvider.Token
to obtain the cancellation token if it is not provided by the caller code.
- Do create a
IncludeDetails
extension method for theIQueryable<TEntity>
for each aggregate root which has sub collections. Example:
public static IQueryable<IdentityUser> IncludeDetails(
this IQueryable<IdentityUser> queryable,
bool include = true)
{
if (!include)
{
return queryable;
}
return queryable
.Include(x => x.Roles)
.Include(x => x.Logins)
.Include(x => x.Claims)
.Include(x => x.Tokens);
}
- Do use the
IncludeDetails
extension method in the repository methods just like used in the example code above (seeFindByNormalizedUserNameAsync
).
- Do override
WithDetails
method of the repository for aggregates root which have sub collections. Example:
public override async Task<IQueryable<IdentityUser>> WithDetailsAsync()
{
// Uses the extension method defined above
return (await GetQueryableAsync()).IncludeDetails();
}
Module Class
- Do define a module class for the Entity Framework Core integration package.
- Do add
DbContext
to theIServiceCollection
using theAddAbpDbContext<TDbContext>
method. - Do add implemented repositories to the options for the
AddAbpDbContext<TDbContext>
method. Example:
[DependsOn(
typeof(AbpIdentityDomainModule),
typeof(AbpEntityFrameworkCoreModule)
)]
public class AbpIdentityEntityFrameworkCoreModule : AbpModule
{
public override void ConfigureServices(ServiceConfigurationContext context)
{
context.Services.AddAbpDbContext<IdentityDbContext>(options =>
{
options.AddRepository<IdentityUser, EfCoreIdentityUserRepository>();
options.AddRepository<IdentityRole, EfCoreIdentityRoleRepository>();
});
}
}