简介：面向C#开发者的Oracle实体类自动生成工具包，基于OracleCodeGenerator-master项目，帮助使用Entity Framework等ORM框架的开发者在C#中快速对接Oracle数据库，减少手写数据访问层代码，也适合入门者理解C#与Oracle交互的完整流程。压缩包共62个文件、约2.99MB，包含18个cs源码、9个dll依赖库、3个xml配置、3个xaml界面、2个exe可执行程序及完整VS工程配置（sln/csproj），另有pdb调试符号、baml界面资源、ico图标等辅助文件；从连接配置、类型映射、界面交互到程序入口皆有覆盖，目录结构清晰，便于按模块学习。内容兼顾实操与原理：生成器可直接运行，选择数据库表或视图即可自动产出对应的C#实体类，类中属性与字段类型匹配；同时整理Entity Framework与Oracle集成的连接字符串写法、实体类设计原则（主键标记、表名映射）、DbContext调用示例，以及Code First迁移、Repository与Unit of Work模式、查询优化等扩展思路，让读者既能直接落地生成工具，也能理解背后映射原理，方便后续维护与二次开发。已有211人学习下载，适合希望借助自动化工具提升Oracle数据层开发效率的中高级C#程序员。
1. 把 Oracle 表变成 C# 实体类：手工写太累，自动生成又到处是坑
Oracle 数据字典里的表、注释、约束都齐整，可一到了 C# 这边，实体类就全靠人力去凑：几十个字段的表手敲一遍，字段一多就眼花，改表结构时又漏改映射；用工具自动生成也不省心，类型映射错、表名大小写对不上、主键自增拿不到，每一个都能让你在运行时才翻车。「C# Oracle 创建实体类操作」看起来是一次性工作，实际是每个 Oracle 项目的持续负担。这篇笔记把选型、最小生成流程和排障方法串成一条可复现路径，适合正在接 Oracle 数据、想批量产出实体类的 .NET 后端开发者，也适合刚拿到老库准备重建数据服务的中级工程师。
2. 三条生成路线的选型：EF6、EF Core 与 T4 模板哪个适合你
实体类生成不是只有一种玩法。选错路线的代价不在生成那一瞬间，而是以后每次改表都要跟工具斗智斗勇。我一般先看项目骨架再定方案：老 .NET Framework + EF6 的项目走 Database First，新 .NET + EF Core 的项目直接走脚手架命令，纯 Dapper 或 ADO.NET 的项目就自己写一个生成器，连 EF 都不引入。三条路线的原理、边界和坑不一样，下面分开讲。
2.1 EF6 的 Database First：胜在集成，输在配置
EF6 时代，Oracle 支持靠的是 ODP.NET 提供的 EF 提供程序。操作路径是在 Visual Studio 里用「ADO.NET 实体数据模型」向导连接 Oracle，勾选表或视图后生成一个 .edmx 文件，再由模板生成实体类和 DbContext。这套流程集成度高，点几下鼠标能出来几十个类，适合一次性把老库结构搬进代码。
它的问题也很集中。首先是配置：EF6 需要在 app.config 里同时配好连接和 provider 注册，有一处对不上就报「找不到 Entity Framework 提供程序」。常见做法是让 NuGet 包安装时把 provider 注入配置，而不是手写强名称：
<entityFramework> <providers> <provider invariantName="Oracle.ManagedDataAccess.Client" type="Oracle.ManagedDataAccess.EntityFramework.EFOracleProviderServices, Oracle.ManagedDataAccess.EntityFramework" /> </providers> </entityFramework>注意 type 里的强名称版本号别自己编，以项目还原出来的包版本为准。其次是 .edmx 是 XML 模型文件，多人协作时改一点就冲突，编不过时错误信息还特别隐晦。最后是更新模型：表结构变了要走向导，老版本 ODP.NET 有时会把外键导航属性直接丢掉，生成的实体少一半关系。
我的经验是 EF6 只留给存量项目，新项目别往这个坑里跳。如果老项目里只是缺几个实体类，也可以不走向导，单独引入 EF6 的 T4 模板只生成 POCO，绕开 .edmx 全家桶。向导默认全表生成，几十张表一次拖进来，生成出来的东西一半是没人用的，后面每次编译都拖慢速度。应提前过滤掉不需要的表，或者生成完就把多余文件删掉，保持目录干净。
2.2 EF Core 的脚手架反向工程：可重复执行的实体工厂
EF Core 把「从数据库生成实体」做成了命令行能力，一条 dotnet ef dbcontext scaffold 命令就能把指定表的实体、DbContext 和 Fluent 配置一次性生成。原理是连接 Oracle 后读取数据字典（ALL_TAB_COLUMNS、ALL_CONSTRAINTS、ALL_TAB_COMMENTS 等），按类型映射规则产出模型，再在 OnModelCreating 里写出列和关系配置。
和 EF6 最大的区别是过程可脚本化：命令可以反复执行、只生成指定表、固定输出目录和命名空间，甚至可以进 CI 当模型的基线检查。Oracle 在 EF Core 下要使用 Oracle.EntityFrameworkCore 提供程序，注意提供程序名称在 dotnet-ef 参数里大小写敏感，写错了会直接提示找不到提供程序。
脚手架默认行为要心里有数：它对英文表名做复数处理（CUSTOMER 变成实体 Customers），把下划线列名转成 PascalCase（user_id 变成 UserId），这对大多数 Oracle 库问题不大；但遇到刻意用小写名或带特殊字符的表，就要加参数控制。另外，脚手架默认会把连接串写进 OnConfiguring 方法，这在本地实验没问题，进生产之前一定要去掉，改成从配置来源读取。
选型建议：只要项目最终会用 EF Core 查询，就选这条路。即便你只想在 Dapper 项目里借用生成器，也可以临时建一个类库去 scaffold，再把生成的 POCO 复制过来——我经常这么干，比手敲快而且字段不会漏。这里有个常见误区：有人把带连接串的 DbContext 直接提交进仓库，结果换了环境就编译不过，实际是口令被当成代码的一部分写死了，属于典型的部署期炸弹。
2.3 T4 模板：只想要 POCO 时的轻量方案
当项目用 Dapper 或原生 ADO.NET、不需要 DbContext 时，引入整套 EF Core 只为生成实体不划算。这时候自写生成器最可控：要么用 Visual Studio 的 T4 模板在设计时连库出文件，要么写个小控制台程序在构建前跑。T4 的思路是模板代码里连 Oracle，查 all_tab_columns 和 all_col_comments，拿到列名、类型、注释、可空性，循环拼出属性和注释。下面是模板的核心循环示意：
<#@ template debug="false" hostspecific="false" language="C#" #> <#@ assembly name="System.Core" #> <#@ import namespace="Oracle.ManagedDataAccess.Client" #> <#@ output extension=".cs" #> <# var connStr = "User Id=app;Password=****;Data Source=127.0.0.1:1521/ORCL"; var tableName = "CUSTOMER"; using (var conn = new OracleConnection(connStr)) { conn.Open(); var cmd = conn.CreateCommand(); cmd.CommandText = @"SELECT column_name, data_type, nullable FROM all_tab_columns WHERE table_name = :t ORDER BY column_id"; cmd.Parameters.Add(new OracleParameter("t", tableName)); var reader = cmd.ExecuteReader(); while (reader.Read()) { #> /// <summary><#= tableName #>.<#= reader["COLUMN_NAME"] #></summary> public string <#= reader["COLUMN_NAME"] #> { get; set; } <# } } #>这段模板只为说明结构，实际还要处理类型映射、PascalCase 转换和注释来源。T4 的优点是完全定制，缺点是要维护模板，而且 T4 在 VS 里设计时执行时，进程位数和 Oracle 客户端位数不一致就可能连不上库。我的使用边界是：只生成简单实体，不生成导航属性、不做表间关系推断，复杂映射手写；几十张表批量生成时，一定要按列顺序输出稳定文件，并过滤掉系统默认列，否则每次生成的 diff 全是噪音。
三条路线的取舍可以压成一张表：
| 路线 | 典型场景 | 主要痛点 | | EF6 Database First | 存量 .NET Framework 项目 | provider 配置与 .edmx 维护 | | EF Core scaffold | 新项目且要用 ORM | Oracle 类型映射需人工校正 | | T4 / 自研生成器 | Dapper / ADO.NET 项目 | 模板本身的维护成本 |
一句话收束选型：能用 EF Core 脚手架解决的别手写，老框架只能接受 EF6，纯粹要实体就把它当一个代码生成问题来解决。
3. 最小可跑生成流程：从连接串到第一条查询
3.1 环境准备与连接串的两种写法
动手之前先把环境配齐：一台能连到 Oracle 的开发机、.NET SDK、dotnet-ef 全局工具。Oracle 连接串有两种主流写法，决定了后面排查问题的方向。
第一种是 Easy Connect 格式，直接把主机、端口、服务名写进 Data Source，不依赖任何客户端配置文件：
Data Source=192.168.1.5:1521/ORCLPDB1;User Id=app_user;Password=****;第二种是 TNS 别名格式，Data Source 写 tnsnames.ora 里的别名，例如 Data Source=PRODDB。这种写法依赖 TNS_ADMIN 环境变量或客户端安装目录能读到 tnsnames.ora，服务环境下经常读不到。新项目我默认用 Easy Connect，少一层配置就少一个坑。
接下来建一个临时控制台项目来承载脚手架，命令如下：
dotnet new console -n OracleScaffold cd OracleScaffold dotnet add package Oracle.EntityFrameworkCore dotnet add package Microsoft.EntityFrameworkCore.Design dotnet tool install --global dotnet-ef dotnet ef --version说明：Oracle.EntityFrameworkCore 是脚手架读取 Oracle 数据字典所需的提供程序；Microsoft.EntityFrameworkCore.Design 提供 dotnet ef 在设计时需要的服务；dotnet-ef 是命令行工具本体。最后一步打印出版本号，能显示就说明工具链通了。这里的包版本不需要手动指定，系统会解析出与当前 SDK 兼容的一套；如果公司内网有私有 NuGet 源，记得先配置好源地址，否则还原会卡住。
注意：口令不要直接写进项目文件。本地脚手架阶段图省事可以临时用，但生成完的代码一旦要进仓库，连接串必须移到环境变量或密钥托管服务里。
3.2 执行脚手架命令，生成指定表的实体
环境就绪后，核心就一条命令。我一般只生成当前模块用到的表，避免把全库几百张表一次拖进代码库：
dotnet ef dbcontext scaffold \ "User Id=app_user;Password=****;Data Source=192.168.1.5:1521/ORCLPDB1" \ Oracle.EntityFrameworkCore \ --table CUSTOMER \ --table ORDERS \ --output-dir Entities \ --context-dir Data \ --context AppDbContext \ --no-onconfiguring \ --no-pluralize参数含义：
| 参数 | 作用 | 备注 | | --table | 指定生成的表，可重复写 | 不写则生成全库 | | --output-dir | 实体类输出目录 | 相对于项目根目录 | | --context | DbContext 类名 | 默认按库名推断 | | --context-dir | DbContext 输出目录 | 与实体目录分开更清晰 | | --no-onconfiguring | 不把连接串写进代码 | 生产环境必须加 | | --no-pluralize | 关闭表名单复数自动转换 | 表名与实体名保持一致 |
生成成功后，解决方案里会出现 Data/AppDbContext.cs、Entities/Customer.cs、Entities/Order.cs 几个文件。打开 Customer.cs 会看到类名是 Customer，属性 user_id 变成了 UserId，列注释会变成 XML 文档注释，这正是脚手架的价值：它把人工容易漏的注释和字段一次性对齐。
这里有个常见误区：不要急着一口气生成全库。ORM 生成实体和 SQL 不同，全库生成后编译时间长，且大量无用表会干扰你判断哪些映射是有问题的。按业务模块分批生成，每批验证编译通过后再继续，翻车时容易定位。生成完先编译一次，Oracle 的类型映射问题在这一步就会暴露一大部分，尤其是那些带特殊列的老表。
3.3 连接串迁移与第一轮手工修正
--no-onconfiguring 意味着 DbContext 里没有连接串，运行前必须注入。常见做法是把连接串放到配置来源，在 Program.cs 里注册：
builder.Services.AddDbContext<AppDbContext>(options => options.UseOracle(builder.Configuration.GetConnectionString("Oracle")));逻辑说明：AddDbContext 注册的是每个请求一个上下文的生命周期；UseOracle 是 Oracle 提供程序给 DbContextOptionsBuilder 的扩展方法，参数就是连接串。连接串从 appsettings.json 的 ConnectionStrings:Oracle 读取，部署时用环境变量覆盖，避免把口令提交进代码库。
这一轮手工修正我固定查五个点：
- 无主键的表或视图，实体会被标记为无键实体，查询用 ToView 处理。
- NUMBER(1) 列如果被生成为 short，按业务需要改成 bool 并配置转换。
- 表名带引号创建的，确认实体 ToTable 的名称与数据字典完全一致。
- 导航属性在 API 项目里建议关闭延迟加载，避免序列化死循环。
- 生成的 DbContext 里如果有 OnModelCreating 的重复配置，合并同类项。
其中 NUMBER(1) 的改法最常见，配置示例：
builder.Entity<Customer>(entity => { entity.Property(c => c.IsActive) .HasColumnType("NUMBER(1)") .HasConversion<int>(); });HasConversion 告诉 EF：C# 的 bool 在数据库里用 0/1 整数表示；HasColumnType 把列类型钉死为 NUMBER(1)，防止数据库迁移时推断成其他数值类型。两步缺一不可，少了 HasConversion 会生成 Boolean 的 SQL 条件导致 ORA-00932，少了 HasColumnType 则可能被推断成 NUMBER(10)。
4. Oracle 实体类实战避坑：五个高频翻车点与排查方法
生成实体只是开始，真正消耗时间的是类型映射和命名问题。下面五条是我在多个 Oracle 项目里实际踩过的坑，每条按现象、原因、解决三个步骤写，方便你对照排查。
4.1 NUMBER(1) 生成成 short，改成 bool 后查询报 ORA-00932
现象：手动把实体属性从 short 改成 bool 后，编译通过，但查询执行报 ORA-00932「数据类型不一致」，或者 Linq 的 where 条件返回空集。
原因：Oracle 没有布尔列，NUMBER(1) 按精度被脚手架生成成 short 或 byte。你改了 C# 属性类型，但 EF 并不知道该用哪种数据库类型做转换，生成的 SQL 里条件类型和列类型对不上。
解决：属性保留为 bool，并在 Fluent 配置里同时写 HasConversion () 和 HasColumnType("NUMBER(1)")，代码见 3.3 节。如果不想改类型，就把属性保持 short，查询时手动比较 c.IsActive == 1，代价是业务代码里到处是魔法数字。还有第三种做法：在 Oracle 侧把布尔语义用 CHAR(1) 存 Y/N，映射成 string，查询条件用 'Y' 比较，适合老表无法改动的场景。
4.2 CLOB 大字段拖慢列表查询，取出来还是空串
现象：列表接口只展示摘要，但响应时间从 50ms 涨到 500ms 以上；某些行的大字段读出来是空字符串。
原因：EF 默认会把整行所有列物化，CLOB 内容随行一起取回。ODP.NET 对 LOB 的处理还受连接串里 LOB 读取相关配置影响，配置不当或字段为 NULL 与大字段混用时，读出的值表现异常。更隐蔽的是，有人对 CLOB 列做 OrderBy 或 Distinct，Oracle 对 LOB 直接排序会抛错误。
解决：列表查询用 Select 投影到不含 CLOB 的 DTO，详情接口再按主键单独取大字段；实体里把 CLOB 属性拆到单独实体或视图是更好的做法。如果必须排序，改用 DBMS_LOB.SUBSTR 截取前 N 字符在 SQL 里排序，不要在内存里排序。排查时先看生成的 SQL，确认 CLOB 列是否被带进 SELECT 和 ORDER BY。
4.3 表名大小写引发 ORA-00942：表或视图不存在
现象：脚手架正常生成，编译正常，运行查询时报 ORA-00942。
原因：建表语句带了双引号，比如 CREATE TABLE "customer"，数据字典里存的名字是小写 customer；EF 生成的 SQL 里不带引号的标识符会被 Oracle 折叠成大写，于是 FROM customer 实际查的是 CUSTOMER，报不存在。反过来，表建的时候不带引号，存的是大写 CUSTOMER，实体配置里写 "customer" 也会报同样的错。
解决：先查 ALL_TABLES 确认真实存储名：
SELECT table_name FROM all_tables WHERE owner = 'APP_USER';如果是大小写敏感的库，优先统一建表规范，新建表一律不加引号；存量表无法改名的，查询走 FromSql 手写 SQL，并给标识符加双引号：
var rows = db.Customer .FromSqlRaw("SELECT * FROM \"customer\"") .ToList();注意 FromSqlRaw 里直接拼表名有 SQL 注入风险，这里表名来自代码常量，不是用户输入，所以可控；如果你的表名会被外部传入，一定要做白名单校验。
4.4 主键是序列加触发器，插入报 ORA-01400 或拿不到新 ID
现象：插入实体后 SaveChanges 直接报 ORA-01400「无法将 NULL 插入主键列」；或者保存成功但实体主键还是 0。
原因：老库的主键通常由序列 + BEFORE INSERT 触发器生成，数据库本身不接受显式 NULL。EF 默认认为主键由客户端提供，INSERT 语句会带主键列的 NULL 值；触发器在 BEFORE 阶段改写后，EF 并不知道新值，内存里主键还停留在 0。
解决：先确认主键生成机制到底在触发器还是序列默认值。如果是触发器，保证执行 INSERT 的用户有对应权限；然后在实体配置里把主键属性设为数据库生成：
entity.HasKey(e => e.Id); entity.Property(e => e.Id) .ValueGeneratedOnAdd();ValueGeneratedOnAdd 告诉 EF 插入时跳过主键列，让数据库侧的触发器或序列生成值，插入后 EF 会尝试回读新主键。如果表是用 GENERATED AS IDENTITY（12c 及以上）建的，确认提供程序是否识别，识别不了就在配置里换成对应提供程序的 Identity 列扩展方法。排查时先在 PL/SQL 里手动执行一次不带主键的 INSERT，若触发器可用，问题就只出在 EF 配置。
4.5 TNS 别名连不上，但 PL/SQL 工具能连
现象：同样的连接串在 PL/SQL 开发工具里正常，程序一跑就报 ORA-12154「无法解析指定的连接标识符」。
原因：连接串里写的是 TNS 别名（Data Source=PRODDB），解析依赖 tnsnames.ora 的路径。开发工具会自己加载客户端配置，而应用服务进程未必设置 TNS_ADMIN，或读的是另一份 tnsnames.ora。
解决：先 tnsping PRODDB 看服务端解析；生产环境我直接改成 Easy Connect 格式，绕开 TNS 依赖；如果公司规范强制 TNS，就把 tnsnames.ora 复制到应用配置目录，并在启动时显式设置环境变量：
Environment.SetEnvironmentVariable("TNS_ADMIN", AppContext.BaseDirectory);再强调一句：连接串千万别写死在代码里，环境变量和配置文件都是更稳妥的载体；TNS 问题在容器部署时尤其多，因为镜像里根本没有 Oracle 客户端，Easy Connect 是最省心的选择。
5. 让实体类和数据库保持同步：一个启动自检脚本
实体类生成完不代表就完事了。数据库在不停演进，加列、删列、改类型是常态，实体类很容易比库旧又没人发现。我习惯在服务启动阶段加一段自检：把 EF 模型里的实体列集合和数据字典里的实际列集合做差，启动时打印警告，让它成为 CI 的一道软检查。
using var conn = db.Database.GetDbConnection(); conn.Open(); foreach (var entity in db.Model.GetEntityTypes()) { var table = entity.GetTableName(); var modelColumns = entity.GetProperties() .Select(p => p.GetColumnName()).ToHashSet(); var cmd = conn.CreateCommand(); cmd.CommandText = @"SELECT column_name FROM all_tab_columns WHERE owner = SYS_CONTEXT('USERENV','CURRENT_SCHEMA') AND table_name = :t"; cmd.Parameters.Add(new OracleParameter("t", table.ToUpperInvariant())); var actual = new HashSet<string>(); using (var r = cmd.ExecuteReader()) while (r.Read()) actual.Add(r.GetString(0)); foreach (var extra in actual.Except(modelColumns)) Console.WriteLine($"[WARN] {table} 缺实体属性: {extra}"); foreach (var stale in modelColumns.Except(actual)) Console.WriteLine($"[WARN] {table} 实体多余字段: {stale}"); }逻辑说明：GetEntityTypes 拿到所有实体元数据，GetColumnName 取映射后的数据库列名；all_tab_columns 是当前用户可见列。两个集合做差集，缺实体属性的列说明实体没跟上库，实体多余的字段说明库侧可能删了列。用 SYS_CONTEXT 拿当前 schema，避免多用户下串库。这个脚本是只读检查，不阻塞启动，适合和日志平台接在一起做趋势观察。
更进阶的用法是把它放到 CI 流水线里：连接测试库的只读账号，跑一遍生成加自检，任何列差异让构建失败，从源头拦住「库改了、代码没改」的静默故障。我在一个模拟项目X上就靠这个脚本在发布前抓出过三次列变更遗漏，每次都是临近发布才发现的，那时的心情现在还记得。
自检脚本不是银弹，它只能感知列的存在与否，感知不了语义变化，比如同一列从字符变成数字。所以我给自己定的规矩是：每次改库结构，顺手跑一遍生成命令，让差异自然暴露，而不是等运行时错乱。这套从选型、生成到自检的流程，现在已经是我的标准动作，希望帮到你。
本文还有配套的精品资源，点击获取
