cdata-cli-adonet

SKILL：CData CLI — .NET / ADO.NET 构建

cdata-cli 技能的构建阶段配套指南。cdata-cli 使用 JDBC 驱动完成发现工作（连接、探索架构、验证 SQL）；开始使用 CData ADO.NET Data Provider 编写 .NET 应用代码后，本技能将接手后续工作。

发现阶段验证的所有内容都可以直接沿用：所有 CData 驱动共享相同的关系模型和 SQL 方言，因此通过 cdatacli 确认的表名、列名和 SQL，通过 ADO.NET 提供程序也无需修改即可使用。

---

语言 / 驱动版本

语言	CData 版本	.NET 命名空间
C#（也包括 VB.NET、F#）	CData ADO.NET Data Provider	System.Data.CData.<Source>

该提供程序遵循标准 ADO.NET 命名规范。对于 <Source>（例如 Salesforce）：

• <Source>Connection、<Source>Command、<Source>DataReader、<Source>DataAdapter、 <Source>Parameter、<Source>CommandBuilder、<Source>ConnectionStringBuilder
• 程序集/DLL：System.Data.CData.<Source>.dll

---

前提条件：先完成发现

如果本次会话尚未使用 cdata-cli，请停止并先调用它。 本技能仅涵盖构建阶段——继续操作前，必须通过 cdata-cli 完成连接设置、架构发现和 SQL 验证。

本技能假定你已使用 cdata-cli 确认可以连接数据源，并验证应用将运行的确切表、列和 SQL。请在此处沿用这些结果。如果发现阶段创建的 cdatacli 连接通过浏览器完成了 OAuth 登录，请记下其 OAuthSettingsLocation — .NET 应用可以指向同一个缓存令牌文件，从而跳过重新验证（参见 连接）。

就运行时而言，CLI 只能直接使用 Java/JDBC。 它无法安装、激活或创建 ADO.NET Data Provider 的连接——这些正是本技能涵盖的内容。ADO.NET 提供程序是独立的运行时驱动版本，必须单独获取并授权（步骤如下）。

CLI 的 drivers download 只会下载 JDBC jar；ADO.NET 提供程序需通过 NuGet 获取（见下文）。

---

步骤 1：获取提供程序（NuGet）

ADO.NET 提供程序由 CDataSoftware 以 CData.<Source>（例如 CData.Salesforce）的形式发布到 NuGet。推荐的安装方式是在项目中添加包引用：

dotnet add package CData.<Source>

• 获取普通的 CData.<Source> 包 — 这就是 ADO.NET 提供程序。CData.<Source>.EntityFrameworkCore* 包是 EF Core 附加包；只有使用 Entity Framework 时才添加。
• 如需固定版本：dotnet add package CData.<Source> --version <x.y.z>。

本地已经安装？ 独立的 ADO.NET 提供程序产品与 NuGet 包属于不同的发行渠道，可能提供不同的目标文件夹集合。如果已安装在计算机上，可以直接引用其 DLL，而不必从 NuGet 获取：

C:\Program Files\CData\CData ADO.NET Provider for <Source> <Year>\lib\<target>\System.Data.CData.<Source>.dll

其中 <target> 是 lib\ 下现有的某个文件夹（例如 net8.0、net6.0、netstandard2.0）。

---

步骤 2：引用它并选择目标框架

NuGet 包会在 lib/ 下附带其构建目标。具体集合可能因连接器和版本而异，因此请检查包的 lib/ 文件夹；此处验证的连接器包含 netstandard2.0 和 net40：

包中的目标	用途
netstandard2.0	.NET Core / .NET 5+（net6.0、net8.0、net10.0，……）——需要激活许可证（步骤 3）
net40	.NET Framework（4.x）——NuGet 安装时自动获取许可证

根据已安装的 SDK 选择 TargetFramework，而不是根据运行时列表选择。 dotnet new --framework 和构建只接受已安装的 SDK 支持的 TFM——一台只安装了 .NET 10 SDK 的机器会拒绝 net6.0/net8.0，即使这些运行时已存在。检查 dotnet --version（或 dotnet --list-sdks），并默认选择与 SDK 匹配的 TFM（例如 .NET 10 SDK → net10.0，WinForms/WPF UI 则用 net10.0-windows）；由于 SDK 附带自己的运行时，因此该目标既能构建，也能运行。

只有在有意针对较旧的 TFM 时，才需要安装该 TFM 的运行时（dotnet --list-runtimes）——否则启动时会失败，并显示 "You must install or update .NET to run this application."。netstandard2.0 提供程序本身可用于 net6.0 / net8.0 / net10.0，因此限制因素是工具链，而不是驱动程序。

有两种方式引用该提供程序：

• PackageReference（通过 dotnet add package）——最简单；NuGet 会还原 DLL。
• 直接使用 HintPath——引用解压后的 netstandard2.0\System.Data.CData.<Source>.dll。 适用于需要将 DLL（及其已激活的 .lic）放在已知本地路径的情况：

<ItemGroup>
  <Reference Include="System.Data.CData.<Source>">
    <HintPath>..\packages\CData.<Source>\lib\netstandard2.0\System.Data.CData.<Source>.dll</HintPath>
  </Reference>
</ItemGroup>

---

步骤 3：激活许可证

cdatacli 连接正常并不意味着此处已激活。 cdatacli 使用 JDBC 驱动程序运行，因此它只能证明 JDBC 已获许可——ADO.NET 提供程序需要单独的许可证。

许可证取决于构建目标，并且按计算机单独授权，与 JDBC/Python/ODBC 版本分开：

• .NET Framework（net40）——NuGet 包在还原时自动安装许可证； 无需操作。
• .NET Core / .NET（netstandard2.0）——必须使用包中 tools/ 文件夹附带的 install-license 工具激活，否则首次查询时会报错 "Could not find a valid license…"。

该工具是一个 .NET 应用。其文件夹中包含 install-license.dll、install-license.runtimeconfig.json 和 prod.inf；可在包中找到它：

<project>\packages\CData.<Source>\tools\install-license.dll          # extracted package
%USERPROFILE%\.nuget\packages\cdata.<source>\<ver>\tools\install-license.dll   # global NuGet cache

它会从当前目录读取 prod.inf，因此请在工具自身的文件夹中运行它。传入 --name/--email 可非交互式运行（build 26.0.9704+；较旧版本会提示输入）。

cd "<project>/packages/CData.<Source>/tools"
dotnet ./install-license.dll --name "First Last" --email [email protected]               # trial — safe to run here
dotnet ./install-license.dll --name "First Last" --email [email protected] <PRODUCT-KEY> # key is a secret — user runs outside the AI session

激活会将 System.Data.CData.<Source>.lic 写入提供程序 DLL 所在目录（lib\netstandard2.0\）。如果通过 HintPath 引用 DLL，请将 .lic 放在该 DLL 副本旁边。

---

步骤 4：连接（ADO.NET）

标准的 ADO.NET 用法——与某些其他版本不同，这些对象确实实现了 IDisposable，因此使用 using 块是合适的模式：

using System.Data.CData.Salesforce;

using var conn = new SalesforceConnection(connectionString);
conn.Open();

using var cmd = new SalesforceCommand(
    "SELECT Id, Name FROM Account WHERE Name LIKE @name", conn);
cmd.Parameters.Add(new SalesforceParameter("@name", "%Acme%"));

using var reader = cmd.ExecuteReader();
while (reader.Read())
    Console.WriteLine(reader["Name"]);

• 命名参数——占位符为 @name，并添加 <Source>Parameter 对象。 始终对用户输入使用参数化查询。
• INSERT/UPDATE/DELETE 使用 ExecuteNonQuery()；单个值使用 ExecuteScalar()； 使用 <Source>DataAdapter + DataTable 填充网格。

连接字符串与身份验证（沿用发现配置，避免将机密写入代码）

从配置（例如 appsettings.json）传入已通过 cdatacli 验证的相同属性，不要硬编码。对于 OAuth 数据源，将 OAuthSettingsLocation 指向发现连接已填充的令牌文件，这样应用就能在后台刷新，无需浏览器流程：

AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;UseSandbox=true;OAuthSettingsLocation=C:\...\OAuthSettings-xxx.txt

对于没有内置 OAuth 应用的数据源，即使只是刷新，也需要用户自己的 OAuthClientId/ OAuthClientSecret——从环境变量 / 用户机密中读取，切勿提交它们。

---

步骤 5：端到端示例

一个最简控制台/存储库代码片段（可根据需要封装在 WinForms/WPF/ASP.NET 中）：

using System.Data;
using System.Data.CData.Salesforce;

const string CS =
    @"AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;UseSandbox=true;OAuthSettingsLocation=C:\...\OAuthSettings-sbx.txt";

static IEnumerable<(string Id, string Name)> ListAccounts(string? search, int limit = 50)
{
    using var conn = new SalesforceConnection(CS);
    conn.Open();
    var sql = "SELECT Id, Name FROM Account"
              + (string.IsNullOrWhiteSpace(search) ? "" : " WHERE Name LIKE @s")
              + $" ORDER BY Name LIMIT {limit}";
    using var cmd = new SalesforceCommand(sql, conn);
    if (!string.IsNullOrWhiteSpace(search))
        cmd.Parameters.Add(new SalesforceParameter("@s", $"%{search}%"));
    using var r = cmd.ExecuteReader();
    while (r.Read())
        yield return (r["Id"].ToString()!, r["Name"].ToString()!);
}

static void CreateAccount(string name, string? industry)
{
    using var conn = new SalesforceConnection(CS);
    conn.Open();
    using var cmd = new SalesforceCommand(
        "INSERT INTO Account (Name, Industry) VALUES (@n, @i)", conn);
    cmd.Parameters.Add(new SalesforceParameter("@n", name));
    cmd.Parameters.Add(new SalesforceParameter("@i", (object?)industry ?? DBNull.Value));
    cmd.ExecuteNonQuery();
}

运行 dotnet build，确认引用解析成功。

---

故障排查

错误	原因 / 解决方法
Could not find a valid license for using CData ADO.NET Provider for <source>	此计算机上的 netstandard2.0 构建未激活 — 从软件包的 tools/ 文件夹运行 install-license（步骤 3）。net40 会自行授权，因此此问题仅影响 .NET Core / .NET 目标。
You must install or update .NET to run this application	尚未安装目标 TFM 的运行时。最简单的方法是使用 SDK 自带的版本作为目标（步骤 2），它附带匹配的运行时；否则请安装缺失的运行时。
'OAuthClientId' and 'OAuthClientSecret' are needed to initiate OAuth	源没有内置 OAuth 应用；请在连接字符串中提供客户端 ID/密钥（从环境变量 / 用户机密中读取），并确保与缓存刷新令牌的应用相匹配。
未找到引用/using System.Data.CData.<Source>	软件包未还原或软件包错误。确保运行 dotnet add package CData.<Source>（使用普通提供程序，而非 EntityFrameworkCore 变体），然后运行 dotnet restore。
install-license.dll 崩溃（NullReferenceException）	Name 或 Email 为空。请传入 --name/--email（步骤 3）；26.0.9704 之前的构建版本只能在提示时接收这些参数。务必从 tools/ 文件夹运行，以便程序找到 prod.inf。