MicroCloud.EntityFrameworkCore.Relationals 7.2.0.2

MicroCloud 一体化数据访问组件

说明

1. MicroCloud 一体化数据访问组件，封装 Cosmos(Azure Cosmos DB 的 SQL API)、Kdbndp(人大金仓)、MySql、Oracle、PostgreSql、Sqlite、SqlServer 类型数据访问功能的实现。
2. 便于项目部署后可通过配置动态切换数据库而不用调整项目代码依赖逻辑。

用法

可按照如下配置方式使用：

1. 通过nuget引用 MicroCloud.EntityFrameworkCore.Allinone 程序集

Install-Package MicroCloud.EntityFrameworkCore.Allinone

2. 在 appsettings.json 中的 MicroCloud 节点下根据具体使用的上下文类型添加对应的配置节点(具体见各数据组件说明)，示例如下：

{
    //数据库上下文集合
    "DbContexts": {
      //数据库上下文
      "XXXDbContext": {
        "DbContextTypeName": "MicroCloud.Entity.XXXDbContext,MicroCloud.EntityFrameworkCore", //上下文类型全名
        "DatabaseType": "Cosmos/Kdbndp/MySql/Oracle/PostgreSql/Sqlite/SqlServer", //数据库类型："Cosmos"(Azure Cosmos DB 的 SQL API)、"Kdbndp"(人大金仓)、"MySql"、"Oracle"、"PostgreSql"、"Sqlite"、"SqlServer"
        //"ConnectionString": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;DatabaseName=MicroCloud_DEV;Persist Security Info=true", //连接字符串(Cosmos)
        //"ConnectionString": "Server=127.0.0.1(IP地址);Port=55001(端口号);UID=system(数据库身份验证ID);PWD=***(密码);database=MicroCloud_DEV(数据库名)", //连接字符串(Kdbndp)
        //"ConnectionString": "server=localhost;port=3306;database=MicroCloud_DEV;uid=XXXXX;pwd=XXXXX;Persist Security Info=true", //连接字符串(MySql)
        //"ConnectionString": "Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=172.19.19.187)(PORT=6521))(CONNECT_DATA=(SERVICE_NAME=MicroCloud_DEV)));User ID=User;Password=p@ssw0rd;Persist Security Info=true", //连接字符串(Oracle)
        //"ConnectionString": "User ID=postgres;Password=abc123456;Host=localhost;Port=5432;Database=MicroCloud_DEV;Persist Security Info=true", //连接字符串(PostgreSql)
        //"ConnectionString": "data source=MicroCloud_DEV.db", //连接字符串(Sqlite)
        //"ConnectionString": "Data Source=IP地址;Initial Catalog=数据库名;User ID=数据库身份验证ID;Password=密码;Pooling=true(是否汇入连接池);Min Pool Size=1(最小连接池连接数);Max Pool Size=20(最大连接数);Integrated Security=true(false:用户名密码验证、true：windows身份验证);Persist Security Info=true(保存密码);Connect Timeout=60(连接超时时长(秒));Application Name=应用程序名称;Encrypt=true(加密连接);TrustServerCertificate=true(信任服务器证书);", //连接字符串(SqlServer)
        //从数据库配置
        "SlaveDatabase": {
          "SlaveSelector": "Weight", //从数据库选择策略：Weight(平滑权重)、Random(随机)、Sequence(顺序轮询)
          //从数据库集合
          "SlaveDatabases": [
            {
              "Name": "MicroCloud_DEV_Slave01", //数据库名
              "Weight": 2, //权重(1-100)
              "ConnectionString": "", //连接字符串
            },
            {
              "Name": "MicroCloud_DEV_Slave02", //数据库名
              "Weight": 5, //权重(1-100)
              "ConnectionString": "", //连接字符串
            }
          ]
        },
        "LazyLoadingProxiesEnabled": true, //是否启用延迟加载代理
        "DateTimeUtcFormatEnabled": false, //是否启用时间UTC格式
        "AuditEntityEnabled": true, //是否允许审计实体
        "MigrationAssemblyName": "MicroCloud.Svc.Web", //迁移的程序集名称(为空时默认"DesignTimeXXXDbContextFactory"所在程序集)，PS：Cosmos暂不支持
        "MigrationEnabled": true //启用自动迁移，PS：Cosmos暂不支持
      }
    },
}

3. 在[Your Object]项目 Startup → ConfigureServices 中加入 AddPack<DefaultDbContextMigrationPack>()

• 注意：建议生产环境配置MigrationEnabled: false，然后通过SQL脚本的模式进行手动迁移。

数据迁移使用说明(处理系统 Code First 模式下 EF Core 的数据迁移)

用法

1. 在数据上下文配置节点中设置MigrationAssemblyName为您的迁移文件管理项目(后续执行迁移命令的默认项目)。
2. 打开程序包管理器控制台，位于工具-Nuget包管理器-程序包管理器控制台。
3. 在程序包管理器控制台输入如下指令：Add-Migration [-Name] <String> ，例如：Add-Migration -Name InitialCreate，生成数据库迁移脚本。

• 自动迁移：若配置配置MigrationEnabled: true，然后直接启动服务。
• 手动迁移：若配置配置MigrationEnabled: false，然后控制台执行Update-Database更新数据库或者执行Script-Migration生成SQL迁移脚本交由DBA处理数据库迁移(生产环境下建议使用)。

EF Core 数据库迁移总结(程序包管理器控制台)：

EF Core 继承了EF的大部分特性和功能，做了更多的优化和升级。总结一下EF Core中的常用的数据迁移计划，如下都是使用visual studio“ 程序包管理器控制台”方式。

创建迁移

执行添加迁移命令即默认完成启用操作，命令如下：

Add-Migration 迁移名称

第一次命令执行后，会在目录下增加一个Migrations目录，包含两个文件

• 20210331014734_initDb.cs 主迁移文件，包含升级的 Up 和降级的 Down 方法。
• MyContextModelSnapshot.cs 当前数据库的快照，这个在EF中是没有的，查了下新的数据库迁移表，简化了 model 列等，看样子是把迁移跟踪放到快照中了。

另外在迁移时增加了两个新的命令，可以指定迁移的输出路径、命名空间。

Add-Migration InitialCreate -OutputDir zhan\lis

用于输出文件的目录, 路径相对于目标项目目录。(以上命令会在将迁移文件输出到zhan/lisy路径下，并且命名空间为 *.zhan.lis)

Add-Migration InitialCreate -Namespace zhan.lisy

要用于生成的类的命名空间，在 EF Core 5.0 中添加。(执行结果，在Migrations目录下新增迁移文件，命名空间为 *.zhan.lisy)

Add-Migration 
    -Name <String>           #迁移的名称。
    -OutputDir <String>      #要使用的目录（和子命名空间）。路径是相对于项目目录的。默认为“Migrations”。
    -Context <String>        #要使用的DbContext类型。
    -Project <String>        #要使用的项目。
    -StartupProject <String> #要使用的启动项目。默认为解决方案的启动项目。
    <CommonParameters>
        此 Cmdlet 支持常见参数: Verbose、Debug、
        ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer、PipelineVariable 和 OutVariable。有关详细信息，请参阅
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216)。

删除迁移

Remove-Migration

EF Core新增命令，配合数据快照进行最后一次迁移的回滚(EF是直接删除迁移代码)。 避免删除已应用到生产数据库的任何迁移。 这样做意味着你将无法从数据库还原这些迁移，并且可能会破坏后续迁移所做的假设。

列出迁移(EF Core 5.0 新增)

Get-Migration

这个命令比直接看迁移代码多出来一个是否迁移的状态。

生成迁移SQL脚本(生产环境建议通过生成 SQL 脚本，将迁移部署到生产数据库。)

Script-Migration [From] [to] -output 输出路径

可以生成a版本到b版本之前的迁移sql。当生产环境下发生迁移时非常好用。

Script-DbContext

可以生成整个数据库的生成脚本，忽略一切迁移。就是直接搞出来一个数据库初始化脚本，也非常有用。

Script-Migration

生成一个从空白数据库到最新迁移的 SQL 脚本。

Script-Migration [From]

使用 From（to 隐含）：生成一个从给定迁移到最新迁移的 SQL 脚本。

Script-Migration [From] [to]

使用 From 和 To：生成一个从指定 from 迁移到指定 to 迁移的 SQL 脚本。可以使用比 to 新的 from 来生成回退脚本。

幂等 SQL 脚本

上面生成的 SQL 脚本只能用于将架构从一个迁移更改为另一个迁移；你需要适当地应用脚本，并且仅应用于处于正确迁移状态的数据库。 EF Core 还支持生成幂等脚本， 此类脚本将在内部检查已经应用哪些迁移（通过迁移历史记录表），并且只应用缺少的迁移。 如果不确知应用到数据库的最后一个迁移，或者需要部署到多个可能分别处于不同迁移的数据库，此类脚本非常有用。

Script-Migration -Idempotent

执行数据库迁移

Update-Database [migration name]

执行迁移计划，可以通过指定迁移名称迁移到数据到指定版本，如果迁移名称为0，则撤销所有迁移。

自定义迁移代码

当进行一些迁移时，生成的结果可能和我们预期不一致，此时，可以手动修改迁移代码，如我们重命名列后，生成的迁移计划如下：

migrationBuilder.DropColumn(
    name: "Name",
    table: "Customers");

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customers",
    nullable: true);

实际上，我们只是修改了一列的列名，我们可以将内容替换成：

migrationBuilder.RenameColumn(
    name: "Name",
    table: "Customers",
    newName: "FullName");

迁移代码中执行sql命令

如我们将[FirstName]和[LastName]合并成一列，但是迁移时生成命令会删除列然后新增列，这就造成已有数据的丢失，生成迁移如下：

migrationBuilder.DropColumn(
name: "FirstName",
table: "Customer");

migrationBuilder.DropColumn(
name: "LastName",
table: "Customer");
migrationBuilder.AddColumn<string>(
name: "FullName",
table: "Customer",
nullable: true);

我们可以做如下修改：

migrationBuilder.AddColumn<string>(
    name: "FullName",
    table: "Customer",
    nullable: true);

migrationBuilder.Sql(@"UPDATE Customer SET FullName = FirstName + ' ' + LastName;");

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");
    migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

sqlserver 查询某个表的列名称、说明、备注、类型等

SELECT 
    表名       = case when a.colorder=1 then d.name else '' end,
    表说明     = case when a.colorder=1 then isnull(f.value,'') else '' end,
    字段序号   = a.colorder,
    字段名     = a.name,
    标识       = case when COLUMNPROPERTY( a.id,a.name,'IsIdentity')=1 then '√'else '' end,
    主键       = case when exists(SELECT 1 FROM sysobjects where xtype='PK' and parent_obj=a.id and name in (
                     SELECT name FROM sysindexes WHERE indid in( SELECT indid FROM sysindexkeys WHERE id = a.id AND colid=a.colid))) then '√' else '' end,
    类型       = b.name,
    占用字节数 = a.length,
    长度       = COLUMNPROPERTY(a.id,a.name,'PRECISION'),
    小数位数   = isnull(COLUMNPROPERTY(a.id,a.name,'Scale'),0),
    允许空     = case when a.isnullable=1 then '√'else '' end,
    默认值     = isnull(e.text,''),
    字段说明   = isnull(g.[value],'')
FROM 
    syscolumns a
left join 
    systypes b 
on 
    a.xusertype=b.xusertype
inner join 
    sysobjects d 
on 
    a.id=d.id  and d.xtype='U' and  d.name<>'dtproperties'
left join 
    syscomments e 
on 
    a.cdefault=e.id
left join 
sys.extended_properties   g 
on 
    a.id=G.major_id and a.colid=g.minor_id  
left join
sys.extended_properties f
on 
    d.id=f.major_id and f.minor_id=0
where 
    d.name='YourTable'    --如果只查询指定表,加上此where条件，tablename是要查询的表名；去除where条件查询所有的表信息
order by 
    a.id,a.colorder

多个数据上下文配置(多个数据库的使用)说明

1. 在既定项目工程(自由选择)中定义全新的数据上下文 [Your Namespace].[Your Name]DbContext ，并继承数据上下文基类 MicroCloud.Entity.DbContextBase ，示例如下：

namespace [Your Namespace]
{
    #region "[Your Name]数据上下文"
    /// <summary>
    /// [Your Name]数据上下文
    /// </summary>
    public class [Your Name]DbContext : DbContextBase
    {
        #region "构造函数"
        #region "初始化一个[Your Name]数据上下文的新实例"
        /// <summary>
        /// 初始化一个[Your Name]数据上下文 <see cref="[Your Name]DbContext"/> 的新实例
        /// </summary>
        /// <param name="options">数据上下文配置选项</param>
        /// <param name="serviceProvider">服务提供者</param>
        public [Your Name]DbContext(DbContextOptions<[Your Name]DbContext> options, IServiceProvider serviceProvider)
            : base(options, serviceProvider)
        { }
        #endregion

        #endregion

    }
    #endregion

}

2. 在既定项目工程(自由选择)中定义设计时数据库上下文工厂 [Your Namespace].DesignTime[Your Name]DbContextFactory ，并继承数据上下文基类 MicroCloud.Entity.DesignTimeDbContextFactory<TDbContext> ，示例如下：

namespace [Your Namespace]
{
    #region "[Your Name]设计时数据上下文工厂(用于执行迁移)"
    /// <summary>
    /// [Your Name]设计时数据上下文工厂(用于执行迁移)
    /// </summary>
    public class DesignTime[Your Name]DbContextFactory : MicroCloud.Entity.DesignTimeDbContextFactory<[Your Name]DbContext>
    {
        #region "构造函数"
        #region "初始化一个 <see cref="DesignTime[Your Name]DbContextFactory"/> 类型的新实例"
        /// <summary>
        /// 初始化一个 <see cref="DesignTime[Your Name]DbContextFactory"/> 类型的新实例
        /// </summary>
        public DesignTime[Your Name]DbContextFactory()
            : base(null)
        { }
        #endregion
        #region "初始化一个 <see cref="DesignTime[Your Name]DbContextFactory"/> 类型的新实例"
        /// <summary>
        /// 初始化一个 <see cref="DesignTime[Your Name]DbContextFactory"/> 类型的新实例
        /// </summary>
        /// <param name="provider">服务提供者</param>
        public DesignTime[Your Name]DbContextFactory(IServiceProvider provider)
           : base(provider)
        { }
        #endregion

        #endregion

    }
    #endregion

}

3. 在既定项目工程(自由选择)中根据数据库类型定义 [Your Namespace].[Database][Your Name]DbContextMigrationPack ，并继承数据上下文基类 MicroCloud.Entity.[Database].[Database]DbContextMigrationPackBase<TDbContext> ，SqlServer示例如下：

namespace [Your Namespace]
{
    #region "SqlServer-[Your Name]DbContext迁移模块"
    /// <summary>
    /// SqlServer-[Your Name]DbContext迁移模块
    /// </summary>
    [DependsOnPacks(typeof(SqlServerEntityFrameworkCorePack))]
    [Description("SqlServer-[Your Name]DbContext迁移模块")]
    public class SqlServer[Your Name]DbContextMigrationPack : MicroCloud.Entity.SqlServer.SqlServerDbContextMigrationPackBase<DefaultDbContext>
    { }
    #endregion

}

3.1. 如果想设计成根据数据库类型自动适配，可参考如下示例：

namespace MicroCloud.Entity
{
    #region "DefaultDbContext迁移模块"
    /// <summary>
    /// DefaultDbContext迁移模块
    /// </summary>
    [Description("DefaultDbContext迁移模块")]
    public class DefaultDbContextMigrationPack : PackBase
    {
        //字段
        private MicroCloudOptions _options;

        #region "属性"
        #region "获取 模块级别"
        /// <summary>
        /// 获取 模块级别，级别越小越先启动
        /// </summary>
        public override PackLevel Level => PackLevel.Framework;
        #endregion

        #endregion

        #region "方法"
        #region "将模块服务添加到依赖注入服务容器中"
        /// <summary>
        /// 将模块服务添加到依赖注入服务容器中
        /// </summary>
        /// <param name="services">依赖注入服务容器</param>
        /// <returns></returns>
        public override IServiceCollection AddServices(IServiceCollection services)
        {
            _options = services.GetMicroCloudOptions();
            var dbContextOptions = _options?.GetDbContextOptions(typeof(DefaultDbContext));
            if (dbContextOptions?.DatabaseType == null)
            {
                return services;
            }
            var builder = services.GetMicroCloudBuilder();
            switch (dbContextOptions.DatabaseType)
            {
                case DatabaseType.SqlServer:
                    builder.AddPack<SqlServerDefaultDbContextMigrationPack>();
                    break;
                case DatabaseType.MySql:
                    builder.AddPack<MySqlDefaultDbContextMigrationPack>();
                    break;
                case DatabaseType.Oracle:
                    builder.AddPack<OracleDefaultDbContextMigrationPack>();
                    break;
                case DatabaseType.PostgreSql:
                    builder.AddPack<PostgreSqlDefaultDbContextMigrationPack>();
                    break;
                case DatabaseType.Kdbndp:
                    builder.AddPack<KdbndpDefaultDbContextMigrationPack>();
                    break;
                case DatabaseType.Sqlite:
                    builder.AddPack<SqliteDefaultDbContextMigrationPack>();
                    break;
                case DatabaseType.Cosmos:
                    builder.AddPack<CosmosDefaultDbContextMigrationPack>();
                    break;
            }

            return services;
        }
        #endregion
        #region "应用模块服务"
        /// <summary>
        /// 应用模块服务
        /// </summary>
        /// <param name="provider">服务提供者</param>
        public override void UsePack(IServiceProvider provider)
        {
            IsEnabled = true;
        }
        #endregion

        #endregion

    }
    #endregion

}

4. 在需要使用当前数据上下文的实体配置类XXXEntityConfiguration增加以下代码，指定DbContext类型：

namespace [Your Namespace]
{
    #region "[Your Entity]映射配置"
    /// <summary>
    /// [Your Entity]映射配置
    /// </summary>
    public partial class [Your Entity]Configuration : EntityTypeConfigurationBase<[Your Entity], [Your Entity Id Type]>
    {
        /// <summary>
        /// 获取 所属的上下文类型
        /// <para>如为null，将使用默认上下文，否则使用指定类型的上下文类型。</para>
        /// </summary>
        public override Type DbContextType { get; } = typeof([Your Name]DbContext);

    }
    #endregion

}

5. 在[Your Object]项目 Startup → ConfigureServices 中加入 AddPack<[Your Name]DbContextMigrationPack>() 并配置数据上下文配置节点：

{
    //数据库上下文集合
    "DbContexts": {
      //数据库上下文
      "[Your Name]DbContext": {
        "DbContextTypeName": "[Your Namespace].[Your Name]DbContext,MicroCloud.EntityFrameworkCore", //上下文类型全名
        "DatabaseType": "Cosmos/Kdbndp/MySql/Oracle/PostgreSql/Sqlite/SqlServer", //数据库类型："Cosmos"(Azure Cosmos DB 的 SQL API)、"Kdbndp"(人大金仓)、"MySql"、"Oracle"、"PostgreSql"、"Sqlite"、"SqlServer"
        //"ConnectionString": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;DatabaseName=MicroCloud_DEV;Persist Security Info=true", //连接字符串(Cosmos)
        //"ConnectionString": "Server=127.0.0.1(IP地址);Port=55001(端口号);UID=system(数据库身份验证ID);PWD=***(密码);database=MicroCloud_DEV(数据库名)", //连接字符串(Kdbndp)
        //"ConnectionString": "server=localhost;port=3306;database=MicroCloud_DEV;uid=XXXXX;pwd=XXXXX;Persist Security Info=true", //连接字符串(MySql)
        //"ConnectionString": "Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=172.19.19.187)(PORT=6521))(CONNECT_DATA=(SERVICE_NAME=MicroCloud_DEV)));User ID=User;Password=p@ssw0rd;Persist Security Info=true", //连接字符串(Oracle)
        //"ConnectionString": "User ID=postgres;Password=abc123456;Host=localhost;Port=5432;Database=MicroCloud_DEV;Persist Security Info=true", //连接字符串(PostgreSql)
        //"ConnectionString": "data source=MicroCloud_DEV.db", //连接字符串(Sqlite)
        //"ConnectionString": "Data Source=IP地址;Initial Catalog=数据库名;User ID=数据库身份验证ID;Password=密码;Pooling=true(是否汇入连接池);Min Pool Size=1(最小连接池连接数);Max Pool Size=20(最大连接数);Integrated Security=true(false:用户名密码验证、true：windows身份验证);Persist Security Info=true(保存密码);Connect Timeout=60(连接超时时长(秒));Application Name=应用程序名称;Encrypt=true(加密连接);TrustServerCertificate=true(信任服务器证书);", //连接字符串(SqlServer)
        //从数据库配置
        "SlaveDatabase": {
          "SlaveSelector": "Weight", //从数据库选择策略：Weight(平滑权重)、Random(随机)、Sequence(顺序轮询)
          //从数据库集合
          "SlaveDatabases": [
            {
              "Name": "MicroCloud_DEV_Slave01", //数据库名
              "Weight": 2, //权重(1-100)
              "ConnectionString": "", //连接字符串
            },
            {
              "Name": "MicroCloud_DEV_Slave02", //数据库名
              "Weight": 5, //权重(1-100)
              "ConnectionString": "", //连接字符串
            }
          ]
        },
        "LazyLoadingProxiesEnabled": true, //是否启用延迟加载代理
        "DateTimeUtcFormatEnabled": false, //是否启用时间UTC格式
        "AuditEntityEnabled": true, //是否允许审计实体
        "MigrationAssemblyName": "[Your Migration Assembly Name]", //迁移的程序集名称(为空时默认"DesignTime[Your Name]DbContextFactory"所在程序集)，PS：Cosmos暂不支持
        "MigrationEnabled": true //启用自动迁移，PS：Cosmos暂不支持
      }
    },
}

6. 在程序包管理控制台中执行Add-Migration -Context DefaultDbContext [Your Name]DbContext，创建迁移脚本，若系统中存在多个DbContext，所以需要指定上下文-Context [Your Name]DbContext。

7. 执行迁移(详见上述迁移说明)。

交流

QQ群号：863605868	微信号：SeonHu