KingbaseES客户端编程开发框架-Ef6.pdf

KingbaseES 客户端编程开发框架-Ef6 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 2.1 2.2 3 KingbaseES 的 EF6 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1.1 Entity Framework 6 (EF6) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1.2 Entity Framework Core (EF Core) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 KingbaseES 的 EF6 方言包 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 第 3 章 KingbaseES 的 EF6 编程指南 3.1 3.2 环境搭建 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.1 工程搭建 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.2 服务的配置方法和参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 程序开发示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2.1 连接数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.2 参考用例一 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.3 参考用例二 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 版权声明 13 服务周期承诺 14 I 第 1 章 前言 1 第 章 前言 本文档描述了 Entity Framework 6 的相关背景和 KingbaseES 方言包，并指导如何使用 KingbaseES 方言包进行 编程开发。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES EF6 指南向所有使用 KingbaseES 数据库的用户，主要是使用 EF6 框架进行应用程序开发的开发人 员。 1.2 相关文档 有关 EF6 的更多信息，请参阅以下资源： Entity Framework 6 1.3 术语 无 1 第 1 章 前言 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 本部分描述了 Entity Framework 6 的开发背景，以及目前 KingbaseES 对 EF6 的兼容情况。 本部分包含以下章节： • KingbaseES 的 EF6 简介 • KingbaseES 的 EF6 方言包 2.1 KingbaseES 的 EF6 简介 微软为了支持.NET 开发人员使用.NET 对象处理数据库的对象关系映射程序 (O/RM)，开发出了一种 (O/RM) 框架 Entity Framework。该框架不要求开发人员编写大部分数据访问代码。Entity Framework 目前支持两个版本： Entity Framework 6 和 Entity Framework Core。 • Entity Framework 6 (EF6) • Entity Framework Core (EF Core) 2.1.1 Entity Framework 6 (EF6) Entity Framework 6 是一种久经验证的数据访问技术。 2008 年，它作为.NET Framework 3.5 SP1 和 Visual Studio 2008 SP1 的一部分首次发布。 从 4.1 版开始，已作为 EntityFramework NuGet 包发布。 2.1.2 Entity Framework Core (EF Core) Entity Framework Core (EF Core) 是在 2016 年首次发布的 EF6 的基础上完全重写。 它附带于 Nuget 包中， 是 Microsoft.EntityFrameworkCore 的主要组成部分。 EF Core 是一种跨平台产品，可以在.NET Core 或.NET Framework 上运行。 EF Core 旨在为开发人员提供类似 EF6 的体验。EF6 支持多个数据库引擎，包括 KingbaseES，为了支持 EF6， KingbaseES 提供了 EntityFramework6.Kdbndp。 3 第 2 章 概述 2.2 KingbaseES 的 EF6 方言包 EntityFramework6.Kdbndp 是 Kdbndp 实体框架（EF）核心程序。它的行为与其他 EF6 引擎驱动程序（例如 SQL Server）类似。 目前 KingbaseES 支持.NET Framework 4.0 以上版本。 注意: EF6 在.NET Framework 4.x 上运行，这意味着它仅在 Windows 上运行。 方言包 适用范围 net40.rar .net framework 4.0 net45.zip .net framework 4.5 4 第3章 3 第 章 KINGBASEES 的 EF6 编程指南 KingbaseES 的 EF6 编程指南 本部分描述了 KingbaseES 的 EF6 的环境搭建以及程序开发示例。 • 环境搭建 • 程序开发示例 3.1 环境搭建 • 工程搭建 • 服务的配置方法和参数说明 3.1.1 工程搭建 工程搭建步骤可参考参考用例一 中的步骤 1。 3.1.2 服务的配置方法和参数说明 相关使用，以及参数设置可参考 KingbaseES 客户端编程接口指南-ado.net 中 kdbndp 中连接字符串的解析。 3.2 程序开发示例 • 连接数据库 • 参考用例一 • 参考用例二 您可前往 人大金仓官网 下载 EF6 测试用例 。 5 第3章 3.2.1 KINGBASEES 的 EF6 编程指南 连接数据库 作用： 连接数据库参数配置。 格式： 相关使用以及参数设置可参考 KingbaseES 客户端编程接口指南-ado.net 中 kdbndp 中连接字串的解析。 3.2.2 参考用例一 目的 通过本用例可了解如何引用 EntityFramework6.Kdbndp.dll，在程序中如何使用 EntityFramework6.Kdbndp。 系统必备 所需 VS 版本不低于 Visual Studio 2010，如果使用 Visual Studio 2010，您还需要安装 NuGet 。 步骤 1) 创建应用程序； 为了方便起见，我们要构建使用 Code First 来执行数据访问的基本的控制台应用程序： 1. 打开 Visual Studio； 2. 文件-> 新增-> 项目...； 3. 选择 Windows 左侧的菜单和控制台应用程序； 4. 输入 kb_ef6_test 作为名称； 5. 单击“确定”。 2) 定义模型； 1. 添加类文件 Modules.cs； 2. 在添加类文件中添加如下代码： public enum State { None, 有用, 无用 } public class Test { [Key] public Guid Id { get; set; } 6 第3章 KINGBASEES 的 EF6 编程指南 public Guid? Ids { get; set; } public string Name { get; set; } public bool Sex { get; set; } public bool? Sexy { get; set; } public int Age { get; set; } public int? Ager { get; set; } public DateTime Birth { get; set; } public DateTime? Birthy { get; set; } public float Money { get; set; } public float? Moneies { get; set; } public double Pi { get; set; } public double? Pis { get; set; } public State State { get; set; } public State? States { get; set; } public byte[] RowVersion { get; set; } } 注意: byte[] 定义的变量属性不能用 Data Annatation 标记为 [TimeStamp]，标记会出现错误。 3) 创建上下文； 1. 定义派生的上下文，它表示我们在数据库中能够查询和保存数据的会话。 定义的上下文，它派生自 Sys- tem.Data.Entity.DbContext； 2. 为了使用实体框架中的类型，我们需要添加 EntityFramework NuGet 包。在 Nuget 控制台中输入命令： Install-Package EntityFramework 3. 在“引用”中添加 EntityFramework6.Kdbndp.dll，Kdbndp.dll 的引用； 4. 在 Modules.cs 的顶部添加 using 语句： using System.Data.Entity; using System.ComponentModel.DataAnnotations; C# public class BloggingContext : DbContext { public BloggingContext() : base("name=TestKbContext") { } public DbSet Blogs { get; set; } } 红色标记为连接数据库字符串名。 7 第3章 KINGBASEES 的 EF6 编程指南 4) 在 App.config 或 Web.config 1. 连接数据库的配置： 2. 添加 provider 相关信息，标红部分： 3. 添加 system.data： 8 第3章 KINGBASEES 的 EF6 编程指南 5) 创建模型； 在 Nuget 控制台中依次输入以下命令： Enable-Migrations Add-Migration InitialCreate Update-Database 执行完前两条命令会生成类似 201908080542058_KB_Test2s.cs 文件。 6) 操作使用模型。 using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; namespace kb_ef6_test { class Program { static void Print(Modules db,String strShowInfo) { var query = from b in db.KB_Tests orderby b.Name select b; Console.WriteLine(strShowInfo); foreach (var item in query) { Console.WriteLine(item.Name); } Console.WriteLine("data search over...."); } static void Main(string[] args) { using (var db = new Modules()) { var blog = new Test { Id = Guid.NewGuid(), Ids = Guid.NewGuid(), Name = " 刘备", Sex = true, 9 第3章 KINGBASEES 的 EF6 编程指南 Sexy = true, Age = 45, Ager = 45, Birth = DateTime.Now, Birthy = DateTime.Now, Money = 1.5f, Moneies = 1.5f, Pi = 36.25, Pis = 36.25, State = State. 无用, States = State. 有用, RowVersion = Enumerable.Repeat((byte)0x08, 10).ToArray() }; db.KB_Tests.Add(blog); db.SaveChanges(); Print(db, "search data after add"); var temp = db.KB_Tests.FirstOrDefault(s => s.Name == " 刘备"); temp.Name = " 张飞"; db.SaveChanges(); Print(db, "search data after update"); temp = db.KB_Tests.FirstOrDefault(s => s.Name == " 刘备"); db.KB_Tests.Remove(temp); db.SaveChanges(); Print(db, "search data after delete"); } Console.WriteLine("press any key to exit......."); Console.ReadKey(); } } } 3.2.3 参考用例二 在参考用例一 的基础上，如果需要在模型中添加新的表或者为原有模型表中添加字段，则可使用以下步骤： 10 第3章 KINGBASEES 的 EF6 编程指南 1) 更新模型数据 Update-Database –Verbose 注意: 添加参数–Verbose 可以看到更新打印的详细信息，这样有助查询更新失败或者错误的原因。 2) 通过 Migration 生成新的模型文件 Add-Migration 模型名称 3) 更新模型数据到数据库 Update-Database –Verbose 4) 简单实例 在参考用例一 的基础上添加新表类。 public class Test2 { [Key] public Guid Id { get; set; } public Guid? Ids { get; set; } public string Name { get; set; } public bool Sex { get; set; } public bool? Sexy { get; set; } public int Age { get; set; } public int? Ager { get; set; } public DateTime Birth { get; set; } public DateTime? Birthy { get; set; } public float Money { get; set; } public float? Moneies { get; set; } public double Pi { get; set; } public double? Pis { get; set; } public State State { get; set; } public State? States { get; set; } public byte[] RowVersion { get; set; } } public class BloggingContext : DbContext { public BloggingContext() : base("name=TestKbContext") { } public DbSet Blogs { get; set; } 11 第3章 KINGBASEES 的 EF6 编程指南 public DbSet Test2s{ get; set; } } 在“程序包管理控制台”执行： Add-Migration Test2s 会生成类似 201908080542058_KB_Test2s.cs 文件。 继续执行： Update-Database –Verbose 即可在数据库中生成新添加的类对应的表。 12 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 13 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 14 服务周期承诺 开方式宣布产品服务终止日期。 15