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 を検証済みであることを前提としています。その結果をここで再利用してください。検出時に OAuth ブラウザーサインインを実行する cdatacli 接続を作成した場合は、OAuthSettingsLocation を控えておいてください。.NET アプリで同じキャッシュ済みトークンファイルを指定すれば、再認証を省略できます（接続を参照）。

実行時、CLI が直接扱うのは Java／JDBC のみです。 ADO.NET Data Provider のインストール、アクティベーション、接続の作成はできません。これらはこのスキルで扱います。ADO.NET プロバイダーは別の実行時ドライバーエディションであり、別途入手してライセンスを取得する必要があります（以下の手順を参照）。

CLI の drivers download がダウンロードするのは JDBC の jar のみです。ADO.NET プロバイダーは NuGet から入手します（以下を参照）。

---

手順 1：プロバイダーを入手する（NuGet）

ADO.NET プロバイダーは、NuGet で CDataSoftware により CData.<Source>（例：CData.Salesforce）として公開されています。一般的なインストール方法は、プロジェクトにパッケージ参照を追加することです。

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 パッケージとは別の配布形態であり、公開されるターゲットフォルダーの構成も異なる場合があります。マシンにインストール済みであれば、NuGet から取得せず、DLL を直接参照できます。

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 のインストール時にライセンスが自動適用されます

TargetFramework はランタイムの一覧ではなく、インストール済み SDK に基づいて選択してください。 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 で動作するため、制限要因はドライバーではなくツールチェーンです。

プロバイダーを参照する方法は 2 つあります。

• PackageReference（dotnet add package を使用）— 最も簡単な方法です。DLL は NuGet によって復元されます。
• 直接 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 を渡します（ビルド 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

有効化すると、プロバイダー DLL（lib\netstandard2.0\）と同じ場所に System.Data.CData.<Source>.lic が書き込まれます。HintPath で DLL を参照する場合は、そのコピーの隣に .lic を置いてください。

---

ステップ 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 を使用します。

接続文字列と認証（探索結果を再利用し、シークレットをコードに含めない）

cdatacli で検証したものと同じプロパティを、ハードコードせずに設定ファイル（例：appsettings.json）から渡します。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／シークレットを指定してください（環境変数／user-secrets から取得）。キャッシュされているリフレッシュトークンに対応するアプリのものを使用してください。
参照／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 より前のビルドでは、プロンプトでのみ指定できます。prod.inf を見つけられるよう、必ず tools/ フォルダーから実行してください。