From 1257581c9b105e55d135f1a3edc8348480cd6617 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Thu, 2 Jan 2020 08:56:40 +0300 Subject: [PATCH] Complete the "Switch to EF Core MySQL Provider" document. --- docs/en/Entity-Framework-Core-MySQL.md | 49 +++++++++++++++++++-- docs/en/Entity-Framework-Core-PostgreSQL.md | 16 +++---- docs/en/Modules/IdentityServer.md | 3 ++ docs/en/Modules/Index.md | 2 +- docs/en/docs-nav.json | 8 +++- 5 files changed, 63 insertions(+), 15 deletions(-) create mode 100644 docs/en/Modules/IdentityServer.md diff --git a/docs/en/Entity-Framework-Core-MySQL.md b/docs/en/Entity-Framework-Core-MySQL.md index 911db6a010..8effd5159d 100644 --- a/docs/en/Entity-Framework-Core-MySQL.md +++ b/docs/en/Entity-Framework-Core-MySQL.md @@ -1,4 +1,4 @@ -# Entity Framework Core MySQL Database Provider +# Switch to EF Core MySQL Provider This document explains how to switch to the **MySQL** database provider for **[the application startup template](Startup-Templates/Application.md)** which comes with SQL Server provider pre-configured. @@ -10,8 +10,49 @@ This document explains how to switch to the **MySQL** database provider for **[t Find ***YourProjectName*EntityFrameworkCoreModule** class inside the `.EntityFrameworkCore` project, remove `typeof(AbpEntityFrameworkCoreSqlServerModule)` from the `DependsOn` attribute, add `typeof(AbpEntityFrameworkCoreMySQLModule)` (also replace `using Volo.Abp.EntityFrameworkCore.SqlServer;` with `using Volo.Abp.EntityFrameworkCore.MySQL;`). -## Call UseMySQL +## UseMySQL() -Find `UseSqlServer()` calls in your solution, replace with `UseMySQL()` +Find `UseSqlServer()` calls in your solution, replace with `UseMySQL()`. Check the following files: -TODO \ No newline at end of file +* *YourProjectName*EntityFrameworkCoreModule.cs inside the `.EntityFrameworkCore` project. +* *YourProjectName*MigrationsDbContextFactory.cs inside the `.EntityFrameworkCore.DbMigrations` project. + +> Depending on your solution structure, you may find more code files need to be changed. + +## Change the Connection Strings + +MySQL connection strings are different than SQL Server connection strings. So, check all `appsettings.json` files in your solution and replace the connection strings inside them. See the [connectionstrings.com]( https://www.connectionstrings.com/mysql/ ) for details of MySQL connection string options. + +You typically will change the `appsettings.json` inside the `.DbMigrator` and `.Web` projects, but it depends on your solution structure. + +## Change the Migrations DbContext + +MySQL DBMS has some slight differences than the SQL Server. Some module database mapping configuration (especially the field lengths) causes problems with MySQL. For example, some of the the [IdentityServer module](Modules/IdentityServer.md) tables has such problems and it provides an option to configure the fields based on your DBMS. + +The startup template contains a *YourProjectName*MigrationsDbContext which is responsible to maintain and migrate the database schema. This DbContext basically calls extension methods of the depended modules to configure their database tables. + +Open the *YourProjectName*MigrationsDbContext and change the `builder.ConfigureIdentityServer();` line as shown below: + +````csharp +builder.ConfigureIdentityServer(options => +{ + options.DatabaseProvider = EfCoreDatabaseProvider.MySql; +}); +```` + +Then `ConfigureIdentityServer()` method will set the field lengths to not exceed the MySQL limits. Refer to related module documentation if you have any problem while creating or executing the database migrations. + +## Re-Generate the Migrations + +The startup template uses [Entity Framework Core's Code First Migrations](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/). EF Core Migrations depend on the selected DBMS provider. So, changing the DBMS provider will cause the migration fails. + +* Delete the Migrations folder under the `.EntityFrameworkCore.DbMigrations` project and re-build the solution. +* Run `Add-Migration "Initial"` on the Package Manager Console (select the `.DbMigrator` (or `.Web`) project as the startup project in the Solution Explorer and select the `.EntityFrameworkCore.DbMigrations` project as the default project in de Package Manager Console). + +This will create a database migration with all database objects (tables) configured. + +Run the `.DbMigrator` project to create the database and seed the initial data. + +## Run the Application + +It is ready. Just run the application and enjoy coding. \ No newline at end of file diff --git a/docs/en/Entity-Framework-Core-PostgreSQL.md b/docs/en/Entity-Framework-Core-PostgreSQL.md index 2f6dd03be7..541554020a 100644 --- a/docs/en/Entity-Framework-Core-PostgreSQL.md +++ b/docs/en/Entity-Framework-Core-PostgreSQL.md @@ -1,8 +1,8 @@ -## Entity Framework Core PostgreSQL Integration +# Switch to EF Core PostgreSQL Provider > See [Entity Framework Core Integration document](../Entity-Framework-Core.md) for the basics of the EF Core integration. -### EntityFrameworkCore Project Update +## EntityFrameworkCore Project Update - In `Acme.BookStore.EntityFrameworkCore` project replace package `Volo.Abp.EntityFrameworkCore.SqlServer` with `Volo.Abp.EntityFrameworkCore.PostgreSql` - Update to use PostgreSQL in `BookStoreEntityFrameworkCoreModule` @@ -11,17 +11,17 @@ - In other projects update the PostgreSQL connection string in necessary `appsettings.json` files - more info of [PostgreSQL connection strings](https://www.connectionstrings.com/postgresql/),You need to pay attention to `Npgsql` in this document -### EntityFrameworkCore.DbMigrations Project Update +## EntityFrameworkCore.DbMigrations Project Update - Update to use PostgreSQL in `XXXMigrationsDbContextFactory` - Replace the `new DbContextOptionsBuilder().UseSqlServer()` with the `new DbContextOptionsBuilder().UseNpgsql()` -### Delete Existing Migrations +## Delete Existing Migrations Delete all existing migration files (including `DbContextModelSnapshot`) ![postgresql-delete-initial-migrations](images/postgresql-delete-initial-migrations.png) -### Regenerate Initial Migration +## Regenerate Initial Migration Set the correct startup project (usually a web project) @@ -34,11 +34,11 @@ Run `Add-Migration` command. PM> Add-Migration Initial ```` -### Update the Database +## Update the Database You have two options to create the database. -#### Using the DbMigrator Application +## Using the DbMigrator Application The solution contains a console application (named `Acme.BookStore.DbMigrator` in this sample) that can create database, apply migrations and seed initial data. It is useful on development as well as on production environment. @@ -52,7 +52,7 @@ Hit F5 (or Ctrl+F5) to run the application. It will have an output like shown be ![set-as-startup-project](../images/db-migrator-app.png) -#### Using EF Core Update-Database Command +### Using EF Core Update-Database Command Ef Core has `Update-Database` command which creates database if necessary and applies pending migrations. diff --git a/docs/en/Modules/IdentityServer.md b/docs/en/Modules/IdentityServer.md new file mode 100644 index 0000000000..0d2ab35c21 --- /dev/null +++ b/docs/en/Modules/IdentityServer.md @@ -0,0 +1,3 @@ +# IdentityServer Module + +TODO \ No newline at end of file diff --git a/docs/en/Modules/Index.md b/docs/en/Modules/Index.md index 9d1c1d301f..8616ed2281 100644 --- a/docs/en/Modules/Index.md +++ b/docs/en/Modules/Index.md @@ -17,7 +17,7 @@ There are some **free and open source** application modules developed and mainta * **Blogging**: Used to create fancy blogs. ABP's [own blog](https://abp.io/blog/abp/) already using this module. * [**Docs**](Docs.md): Used to create technical documentation pages. ABP's [own documentation](https://docs.abp.io) already using this module. * **Identity**: Used to manage roles, users and their permissions. -* **Identity Server**: Integrates to IdentityServer4. +* **IdentityServer**: Integrates to IdentityServer4. * **Permission Management**: Used to persist permissions. * **[Setting Management](Setting-Management.md)**: Used to persist and manage the [settings](../Settings.md). * **Tenant Management**: Used to manage tenants for a [multi-tenant](../Multi-Tenancy.md) application. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index c4a864f4de..f42a484b02 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -262,9 +262,13 @@ { "text": "Entity Framework Core Integration", "path": "Entity-Framework-Core.md", - "items": [ + "items": [ { - "text": "PostgreSQL Integration", + "text": "Switch to MySQL", + "path": "Entity-Framework-Core-MySQL.md" + }, + { + "text": "Switch to PostgreSQL", "path": "Entity-Framework-Core-PostgreSQL.md" } ]