Mac OS环境.NET连接Oracle失败报ORA-12514错误

问题表现 #

• 运行环境：MacOS系统，使用Rider开发.NET应用，依赖Oracle.ManagedDataAccess.Client访问Oracle数据库
• 连通性交叉验证结果：同设备下DataGrip、sqlplus均可正常连接目标数据库；Windows环境下使用完全一致的连接字符串可正常建立连接
• 触发异常：Mac端.NET应用调用OracleConnection.Open()时抛出如下错误：

Oracle.ManagedDataAccess.Client.OracleException (0x80004005): ORA-12514: TNS:listener does not currently know of service requested in connect descriptor
 ---> OracleInternal.Network.NetworkException (0x000030E2): ORA-12514: TNS:listener does not currently know of service requested in connect descriptor
   at OracleInternal.Network.OracleCommunication.DoConnect(String tnsDescriptor)
   at OracleInternal.Network.OracleCommunication.Connect(String tnsDescriptor, Boolean doNAHandshake, String IName, ConnectionOption CO)
   at OracleInternal.ServiceObjects.OracleConnectionImpl.Connect(ConnectionString cs, Boolean bOpenEndUserSession, OracleConnection connRefForCriteria, String instanceName)
   at OracleInternal.ConnectionPool.PoolManager`3.Get(ConnectionString csWithDiffOrNewPwd, Boolean bGetForApp, OracleConnection connRefForCriteria, String affinityInstanceName, Boolean bForceMatch)
   at OracleInternal.ConnectionPool.OraclePoolManager.Get(ConnectionString csWithNewPassword, Boolean bGetForApp, OracleConnection connRefForCriteria, String affinityInstanceName, Boolean bForceMatch)
   at OracleInternal.ConnectionPool.OracleConnectionDispenser`3.Get(ConnectionString cs, PM conPM, ConnectionString pmCS, SecureString securedPassword, SecureString securedProxyPassword, OracleConnection connRefForCriteria)
   at Oracle.ManagedDataAccess.Client.OracleConnection.Open()
   at System.Data.Common.DbConnection.OpenAsync(CancellationToken cancellationToken)
--- End of stack trace from previous location ---

可行解决方案 #

以下为同类问题开发者验证过的有效修复方案，按出现概率从高到低排序：

• 连接字符串参数解析兼容问题
  Oracle.ManagedDataAccess跨平台版本在MacOS下对连接字符串的参数名大小写、多余字符的解析逻辑和Windows版本不一致：Windows环境下驱动不区分参数名大小写，会自动过滤参数值前后的多余空格、末尾冗余分号，但MacOS环境下如果参数名不是全大写、SERVICE_NAME值前后带空格、连接串末尾多写分号，都可能导致驱动解析到错误的服务名，触发ORA-12514。
  修复操作：将连接字符串中所有Oracle相关参数名调整为官方规范的全大写格式，清理SERVICE_NAME值前后的空格，删除连接串末尾多余的分号，参考格式：

  DATA SOURCE=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=数据库IP地址)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=数据库服务名)));PERSIST SECURITY INFO=True;USER ID=数据库账号;PASSWORD=数据库密码
  

  注意：不要使用Data Source=这类驼峰写法的参数名，Mac端驱动对非全大写参数的兼容存在已知bug。
• TNS配置文件读取路径不匹配
  如果使用TNS别名方式连接，Windows环境下驱动会自动读取注册表、系统环境变量指定路径下的tnsnames.ora配置，但MacOS环境下驱动只会按固定优先级查找配置：程序运行目录、~/.oracle/目录、/etc/oracle/目录，不会主动读取sqlplus、DataGrip存放的自定义TNS配置，导致无法匹配到对应服务。
  修复操作：
  • 优先选择直接将完整的DESCRIPTION连接描述串写入DATA SOURCE参数，不依赖TNS别名，兼容性最好
  • 如果要保留别名配置方式，将能正常连通的tnsnames.ora文件拷贝到~/.oracle/目录下，为当前用户授予文件读权限即可
• 驱动版本跨平台兼容bug
  21.3、21.4等早期版本的Oracle.ManagedDataAccess.Core在MacOS 12及以上版本存在TNS握手阶段的参数传递bug，会错误截断SERVICE_NAME字段值，触发12514错误。
  修复操作：通过Nuget将Oracle.ManagedDataAccess.Core升级到21.10.0及以上的稳定版本即可。
• SID与SERVICE_NAME参数混用
  DataGrip、sqlplus等客户端会自动兼容SID和SERVICE_NAME的参数差异，但Mac端的Managed驱动不会做自动适配，如果数据库是通过服务名注册到监听器，连接串中错误使用SID=xxx写法就会报12514，将参数替换为SERVICE_NAME=xxx即可。

内容的提问来源于stack exchange，提问作者semper fi