diff --git a/docs/en/Entity-Framework-Core-Migrations.md b/docs/en/Entity-Framework-Core-Migrations.md index 33e8c8fe87..ee889683f0 100644 --- a/docs/en/Entity-Framework-Core-Migrations.md +++ b/docs/en/Entity-Framework-Core-Migrations.md @@ -63,21 +63,21 @@ The example configuration about tells to the ABP Framework to use the second con #### Module Tables -Every module uses its own databases tables. For example, the [Identity Module](Modules/Identity.md) has some tables to manage the users and roles in the system. +Every module uses its **own databases tables**. For example, the [Identity Module](Modules/Identity.md) has some tables to manage the users and roles in the system. ##### Table Prefixes -Since it is allowed to share a single database by all modules (it is the default configuration), a module typically uses a prefix to group its own tables. +Since it is allowed to share a single database by all modules (it is the default configuration), a module typically uses a **table name prefix** to group its own tables. The fundamental modules, like [Identity](Modules/Identity.md), [Tenant Management](Modules/Tenant-Management.md) and [Audit Logs](Modules/Audit-Logging.md), use the `Abp` prefix, while some other modules use their own prefixes. [Identity Server](Modules/IdentityServer.md) module uses the `IdentityServer` prefix for example. -If you want, you can change the database table name prefix for a module for your application. Example: +If you want, you can **change the database table name prefix** for a module for your application. Example: ````csharp Volo.Abp.IdentityServer.AbpIdentityServerDbProperties.DbTablePrefix = "Ids"; ```` -This code changes the prefix of the [Identity Server](Modules/IdentityServer.md) module. Write this code at the very beginning in your application. +This code changes the prefix of the [Identity Server](Modules/IdentityServer.md) module. Write this code **at the very beginning** in your application. > Every module also defines `DbSchema` property (near to `DbTablePrefix`), so you can set it for the databases support the schema usage. @@ -89,7 +89,7 @@ From the database point of view, there are three important projects those will b This project has the `DbContext` class (`BookStoreDbContext` for this sample) of your application. -Every module uses its own `DbContext` class to access to the database. Likewise, your application has its own `DbContext`. You typically use this `DbContext` in your application code (in your custom [repositories](Repositories.md) if you follow the best practices). It is almost an empty `DbContext` since your application don't have any entities at the beginning, except the pre-defined `AppUser` entity: +**Every module uses its own `DbContext` class** to access to the database. Likewise, your application has its own `DbContext`. You typically use this `DbContext` in your application code (in your custom [repositories](Repositories.md) if you follow the best practices). It is almost an empty `DbContext` since your application don't have any entities at the beginning, except the pre-defined `AppUser` entity: ````csharp [ConnectionStringName("Default")] @@ -198,9 +198,9 @@ public class BookStoreMigrationsDbContext : AbpDbContext` (default repository) Working with an entity of a module is easy if you want to use the entity as is. However, you may want to define your own entity class and map to the same database table in the following cases; -* You want to add a new field to the table and map it to a property in the entity. You can't use the module's entity since it doesn't have the related property. -* You want to use a subset of the table fields. You don't want to access to all properties of the entity and hide the unrelated properties (from a security perspective or just by design). -* You don't want to directly depend on a module entity class. +* You want to **add a new field** to the table and map it to a property in the entity. You can't use the module's entity since it doesn't have the related property. +* You want to **use a subset of the table fields**. You don't want to access to all properties of the entity and hide the unrelated properties (from a security perspective or just by design). +* You don't want to directly **depend on** a module entity class. In any case, the progress is same. Assume that you want to create an entity, named `AppRole`, mapped to the same table of the `IdentityRole` entity of the [Identity module](Modules/Identity.md). -Here, we will show the implementation, then **will discuss the limitations** (and reasons of the limitations) of this approach. +Here, we will show the implementation, then **will discuss the limitations** of this approach. First, create a new `AppRole` class in your `.Domain` project: @@ -351,7 +351,7 @@ namespace Acme.BookStore.Roles * It's inherited from [the `AggregateRoot` class](Entities.md) and implements [the `IMultiTenant` interface](Multi-Tenancy.md) because the `IdentityRole` also does the same. * You can add any properties defined by the `IdentityRole` entity. This examples add only the `TenantId` and `Name` properties since we only need them here. You can make the setters private (like in this example) to prevent changing Identity module's properties accidently. * You can add custom (additional) properties. This example adds the `Title` property. -* The constructor is provide, so it is not allowed to directly create a new `AppRole` entity. Creating a role is a responsibility of the Identity module. You can query roles, set/update your custom properties, but you should not create or delete a role in your code, as a best practice (while there is nothing restricts you). +* The **constructor is private**, so it is not allowed to directly create a new `AppRole` entity. Creating a role is a responsibility of the Identity module. You can query roles, set/update your custom properties, but you should not create or delete a role in your code, as a best practice (while there is nothing restricts you). Now, it is time to define the EF Core mappings. Open the `DbContext` of your application (`BookStoreDbContext` in this sample) and add the following property: @@ -412,8 +412,8 @@ public static void ConfigureCustomRoleProperties(this EntityTypeBuilder @@ -654,13 +656,13 @@ The easiest way to create a second project (`.csproj`) for the second migration ```` -You can just copy & modify the content of the original `.DbMigrations` project. This project references to the `.EntityFrameworkCore` project. Only difference is the `RootNamespace` value. +You can just copy & modify the content of the original `.DbMigrations` project. This project references to the `.EntityFrameworkCore` project. **Only difference** is the `RootNamespace` value. **Add a reference** to this project from the `.Web` project (otherwise, EF Core tooling doesn't allow to use the `Add-Migration` command). ### Create the Second DbMigrationDbContext -Create a new DbContext for the migrations and call the extension methods to configure database tables for the related modules: +Create a new `DbContext` for the migrations and call the **extension methods** of the modules to configure the database tables for the related modules: ````csharp [ConnectionStringName("AbpPermissionManagement")] @@ -686,9 +688,9 @@ public class BookStoreSecondMigrationsDbContext : } ```` -> `[ConnectionStringName(...)]` attribute is important here and tells to the ABP Framework which connection string should be used for this `DbContext`. +> `[ConnectionStringName(...)]` attribute is important here and tells to the ABP Framework which connection string should be used for this `DbContext`. We've used `AbpPermissionManagement`, but all are the same. -Create a Design Time Db Factory class, that is used by the EF Core tooling (by `Add-Migration` and `Update-Database` PCM commands for example): +Create a **Design Time Db Factory** class, that is used by the EF Core tooling (by `Add-Migration` and `Update-Database` PCM commands for example): ````csharp /* This class is needed for EF Core console commands @@ -719,7 +721,7 @@ public class BookStoreSecondMigrationsDbContextFactory This is similar to the class inside the `.EntityFrameworCore.DbMigrations` project, except this one uses the `AbpPermissionManagement` connection string. -Now, you can open the Package Manager Console, select the `.EntityFrameworkCore.DbMigrationsForSecondDb` project as the default project (make sure the `.Web` project is still the startup project) and run the `Add-Migration` and `Update-Database` commands as shown below: +Now, you can open the Package Manager Console, select the `.EntityFrameworkCore.DbMigrationsForSecondDb` project as the default project (make sure the `.Web` project is still the startup project) and run the `Add-Migration "Initial"` and `Update-Database` commands as shown below: ![pmc-add-migration-initial-update-database](images/pmc-add-migration-initial-update-database.png) @@ -729,7 +731,7 @@ Now, you should have a new database contains only the tables needed by the relat ### Remove Modules from the Main Database -We've created a second database contains tables for the Audit Logging, Permission Management and Setting Management modules. So, we should delete these tables from the main database. It is pretty easy. +We've **created a second database** contains tables for the Audit Logging, Permission Management and Setting Management modules. So, we should **delete these tables from the main database**. It is pretty easy. First, remove the following lines from the `MigrationsDbContext` class (`BookStoreMigrationsDbContext` for this example): @@ -786,7 +788,7 @@ Notice that you've also **deleted some initial seed data** (for example, permiss ### Automate the Second Database Schema Migration -`.DbMigrator` console application can run the seed code across multiple databases, without any additional configuration. However, it can not run the EF Core Code First Migrations inside the second database migration project. Now, you will see how to configure the console migration application to handle both databases. +`.DbMigrator` console application can run the database seed code across multiple databases, without any additional configuration. However, it can not run the EF Core Code First Migrations inside the second database migration project. Now, you will see how to configure the console migration application to handle both databases. #### Implementing the IBookStoreDbSchemaMigrator @@ -807,7 +809,7 @@ public class EntityFrameworkCoreBookStoreDbSchemaMigrator public async Task MigrateAsync() { - /* We intentionally resolving the BookStoreMigrationsDbContext + /* We are intentionally resolving the BookStoreMigrationsDbContext * from IServiceProvider (instead of directly injecting it) * to properly get the connection string of the current tenant in the * current scope. @@ -821,7 +823,7 @@ public class EntityFrameworkCoreBookStoreDbSchemaMigrator } ```` -It implements the `IBookStoreDbSchemaMigrator` and replaces existing services (see the first line). +It implements the `IBookStoreDbSchemaMigrator` and **replaces existing services** (see the first line). Remove the `[Dependency(ReplaceServices = true)]` line, because we will have two implementations of this interface and we want to use both. We don't want to replace one of them. @@ -841,7 +843,7 @@ public class EntityFrameworkCoreSecondBookStoreDbSchemaMigrator public async Task MigrateAsync() { - /* We intentionally resolving the BookStoreSecondMigrationsDbContext + /* We are intentionally resolving the BookStoreSecondMigrationsDbContext * from IServiceProvider (instead of directly injecting it) * to properly get the connection string of the current tenant in the * current scope. @@ -861,7 +863,7 @@ We, now, have two implementations of the `IBookStoreDbSchemaMigrator` interface, #### Define a Module Class for the Second Migration Project -It is time to define the module class for this second migrations (`Acme.BookStore.EntityFrameworkCore.DbMigrationsForSecondDb`) project: +It is time to define the [module](Module-Development-Basics.md) class for this second migrations (`Acme.BookStore.EntityFrameworkCore.DbMigrationsForSecondDb`) project: ````csharp [DependsOn( @@ -891,15 +893,15 @@ public class BookStoreDbMigratorModule : AbpModule } ```` -We had a reference to the `Acme.BookStore.EntityFrameworkCore.DbMigrationsForSecondDb` project from the `Acme.BookStore.Web` project, but hadn't added module dependency since we hadn't created it yet. But, now we have it and we need to add `typeof(BookStoreEntityFrameworkCoreSecondDbMigrationsModule)` to the dependency list of the `BookStoreWebModule` class. +We had a reference to the `Acme.BookStore.EntityFrameworkCore.DbMigrationsForSecondDb` project from the `Acme.BookStore.Web` project, but hadn't added module dependency since we hadn't created it before. But, now we have it and we need to add `typeof(BookStoreEntityFrameworkCoreSecondDbMigrationsModule)` to the dependency list of the `BookStoreWebModule` class. #### BookStoreDbMigrationService You need one final touch to the `BookStoreDbMigrationService` inside the `Acme.BookStore.Domain` project. It is currently designed to work with a single `IBookStoreDbSchemaMigrator` implementation, but now we have two. -It injects `IBookStoreDbSchemaMigrator`. Replace it with an `IEnumerable` injection. +It injects `IBookStoreDbSchemaMigrator`. Replace it with an `IEnumerable` injection ([Dependency Injection System](Dependency-Injection.md) allows to inject multiple implementations of an interface just like that). -Now, you have a collection of migrators instead of a single one. Find the lines like: +Now, you have **a collection of schema migrators** instead of a single one. Find the lines like: ````csharp await _dbSchemaMigrators.MigrateAsync(); @@ -914,7 +916,7 @@ foreach (var migrator in _dbSchemaMigrators) } ```` -You can run the `.DbMigrator` application to migrate & seed the databases. To test, you can delete both databases and run the application to see if they are created. +You can run the `.DbMigrator` application to migrate & seed the databases. To test, you can delete both databases and run the `.DbMigrator` application again to see if it creates both of the databases. ## Conclusion