JDesignCAD / API 1.4 / 2026-10-16

保存・書き出し API / MCP

1. 保存と書き出しの違い

本体・計算ワーカー・MCP・SDKは、同じ配布セットのファイルを使用します。更新時はCADとMCP接続を再起動してください。

保存・書き出しはICadFileApiと対応するMCPツールで実行します。開始受付と書込み完了を区別してください。

目的呼出し完了時の図面
編集を続ける図面の保存SaveDocumentAsync / cad_save_document現在の保存先を変更、変更済み表示を解除
受渡し用のコピーExportDocumentAsync / cad_export_document現在の保存先・変更済み状態・Undoを維持
1. Requestpath / format / revision2. runningsnapshot + conversion3. completedfilePath / bytes / sha256failed / cancelled → error.code + error.message
runningは処理中です。completedだけが書込み完了を示します。

保存ダイアログは開きません。スナップショットを取り、別プロセスで変換し、確定直前に図面・保存先・ライセンスを再確認します。図面変更や出力失敗で確定できない場合は、元の保存ファイルを保持します。ファイル出力は図形のUndoの対象外です。

公開メソッドは34、MCPツールは31、構造化操作は75です。利用可能な操作と入力条件は実行中のCADから取得してください。DLLはICadFileApiをis/TryCastで確認します。旧インターフェースの宣言は変更していません。

2. 対応形式とFree版

format拡張子用途必要プラン対象・注意
jdc.jdc保存・コピーFree編集情報を保持
jdc.json.jdc.json / .json保存・コピーFreeネイティブJSON
dwg / dxf.dwg / .dxf保存・コピーSTD / Pro交換形式。編集元JDCも保管
jww.jww保存・コピーSTD / Pro既存の2D変換仕様に従う
p21 / sfc.p21 / .sfc保存・コピーSTD / ProSXF。XY平面外はエラー
step.step / .stpコピーのみSTD / Proアクティブモデルの形状
stl.stl / .stla / .stlbコピーのみFree三角形メッシュ
obj.objコピーのみSTD / Proメッシュ+MTL材質ファイル
svg.svgコピーのみSTD / Pro対応する2D図形、XY投影
ifc.ifcコピーのみSTD / Proソリッド群を1つの部品として出力

形式は12種類。formatは表の値を1つ指定します(stp→step、json→jdc.jsonの別名も可)。拡張子は自動追加しません。FreeでもMCP接続、JDC/JSON保存・コピー、STL書き出しができます。外部DLLは従来どおり同梱サンプルのみです。自作DLL・交換形式・板金・解析の制限は維持します。

GetFileFormatsAsync/cad_get_file_formatsのAvailableを確認します。拒否はlicense_requiredと、currentPlan・requiredPlansを含むLicenseRestrictionを返します。開始時だけでなく確定時にも再判定します。AIは必要プランを伝え、制限を別経路で回避しません。

STL/OBJは線・文字や正確な曲面定義を保持しません。面が1つも出力されなければ失敗します。OBJはadditionalFilesのMTLを同じフォルダーに置いて受け渡してください。既存OBJを上書きしても古いMTLは削除しません。IFCはifc4Advanced(既定)/ifc4Faceted/ifc2x3Facetedを選べ、複数ソリッドは1部品になります。

STEP/メッシュ/SVG/IFCの全体出力はアクティブモデルが対象です。交換形式では板金履歴などネイティブ編集情報の完全な往復を保証しません。編集用JDCを残し、Warningsを確認してください。Availableはライセンス上の利用可否であり、任意形状の変換成功を保証しません。

3. 公開メソッドリファレンス

名前空間はJDesignCAD.Api。追加インターフェースはICadFileApi : ICadInteractionApi。LocalCadClientも実装します。

GetFileFormatsAsync

Task<FileFormatInfo[]> GetFileFormatsAsync(
    CancellationToken cancellationToken = default);

対応形式、拡張子、CanSave/CanExport、Available、UnavailableCode、LicenseRestrictionを取得します。図面を変更しません。実行直前にも利用条件を確認してください。

SaveDocumentAsync

Task<FileOperationInfo> SaveDocumentAsync(
    SaveDocumentRequest request,
    CancellationToken cancellationToken = default);

図面全体を指定先へ保存します。戻り値runningは受付です。completedで初めて図面の保存先が変わり、変更済み状態が解除されます。

ExportDocumentAsync

Task<FileOperationInfo> ExportDocumentAsync(
    ExportDocumentRequest request,
    CancellationToken cancellationToken = default);

図面全体または明示した図形のコピーを書き出します。図面の保存先・変更済み状態・Undo履歴を維持します。現在の図面ファイルへの出力は拒否します。

GetFileOperationAsync

Task<FileOperationInfo> GetFileOperationAsync(
    string operationId,
    CancellationToken cancellationToken = default);

開始時と同じoperationIdで結果を取得します。running中は適度な間隔で再取得します。状態確認は図面を変更しません。

CancelFileOperationAsync

Task<FileOperationInfo> CancelFileOperationAsync(
    string operationId,
    CancellationToken cancellationToken = default);

確定前の処理を中止します。戻り値の状態を確認してください。すでにcompletedなら保存結果を取り消しません。

CancellationTokenは開始前の待機や個々の呼出しを中止します。受付済みのファイル処理は、通信切断・ポーリング中止だけでは停止しません。CancelFileOperationAsyncを明示的に呼び、結果を確認してください。

4. 要求型・引数

引数(.NET / JSON)意味
DocumentId / documentId取得し直した図面ID。別図面への適用を防ぐ
ExpectedRevision / expectedRevision取得し直したrevision。処理中の変更も検出
OperationId / operationId新しいUUID、D形式。通信再試行だけ同じID・同じ入力
FilePath / filePath絶対パス。親フォルダーは事前に作成。拡張子とformatを一致
Format / format対応表から1形式を指定。保存とコピーの可否も確認
Overwrite / overwrite既定false。既存ファイルを上書きする場合だけtrue
TimeoutSeconds / timeoutSeconds既定300、1~1800秒。スナップショット後の待ち時間と変換を含む
EntityIds / entityIdsExportのみ。null=全体、1~1000個のトップレベルID=指定図形
BasePoint / basePointExportの明示選択のみ。WCS mm。用途は下記参照
Ifc / ifcExportのIFCのみ。Output(既定ifc4Advanced)、Name(任意、最大512文字)

BasePointはJDC/JSON/DWG/DXFの挿入基点、SVGの原点、IFCの部品原点です。DWG/DXFの図形座標を移動する値ではありません。選択出力で省略した場合の挿入基点は(0,0,0)、全体出力は既存の基点を保持します。STEP/STL/OBJ/JWW/SXFへのBasePoint指定はエラーです。

正規の型宣言はSDKのApi/Contracts/FileContracts.csに収録しています。SaveDocumentRequestの必須引数は最初の5つ、ExportDocumentRequestも同じ5つです。後続はすべて任意引数です。

5. C#の使用例

既存フォルダーD:\CAD_Outputを例にしています。実際の保存先に変更してください。最初はJDC保存、次は選択図形のDXF出力です。DXFにはSTD/Proが必要です。

using JDesignCAD.Api;
// api: ICadApi supplied by the DLL host, or a LocalCadClient.
if (api is not ICadFileApi files)
    throw new NotSupportedException("Requires API 1.4");
var formats = await files.GetFileFormatsAsync(ct);
if (!formats.Any(x => x.Format == "jdc" && x.Available))
    throw new InvalidOperationException("Format unavailable");
var doc = await api.GetDocumentAsync(ct);
var request = new SaveDocumentRequest(
    doc.Id, doc.Revision, Guid.NewGuid().ToString("D"),
    @"D:\CAD_Output\part.jdc", "jdc", Overwrite: false);
var result = await files.SaveDocumentAsync(request, ct);
while (result.State == "running")
{
    await Task.Delay(500, ct);
    result = await files.GetFileOperationAsync(
        request.OperationId, ct);
}
if (result.State != "completed")
    throw new InvalidOperationException(
        $"{result.Error?.Code}: {result.Error?.Message}");
// result.FilePath / Bytes / Sha256 / Warnings
// File output is NOT reverted by geometry Undo.
var selection = await api.GetSelectionAsync(0, 1000, ct);
if (selection.Total == 0 || selection.Total > 1000)
    throw new InvalidOperationException("Select 1..1000 objects");
var request = new ExportDocumentRequest(
    selection.Document.Id, selection.Document.Revision,
    Guid.NewGuid().ToString("D"),
    @"D:\CAD_Output\part.dxf", "dxf",
    EntityIds: selection.Entities.Select(x => x.Id).ToArray(),
    BasePoint: new Point3(100, 200, 0));
var result = await files.ExportDocumentAsync(request, ct);
// Poll GetFileOperationAsync as in the save example.
// DXF/DWG basePoint sets INSBASE; it does not move WCS geometry.

上の処理で失敗・中止となったらError.Code/Message/LicenseRestrictionを表示します。通信が切れた場合は保存済みのrequestをそのまま再送します。失敗原因を直して実行し直す場合は、図面情報を再取得して新しいOperationIdを使います。

6. MCPとAIの完了確認

ツール用途
cad_get_file_formats対応形式と利用可否
cad_save_document図面全体の保存開始
cad_export_document全体/指定図形のコピー開始
cad_get_file_operation状態と結果を取得
cad_cancel_file_operation確定前に中止

①cad_list_sessionsで対象を選び、cad_get_documentで図面IDとrevisionを取得。②cad_get_file_formatsで利用可否を確認。③下の入力をcad_save_documentへ送信。④同じsessionIdとoperationIdでcad_get_file_operationを呼び、running中は0.5~1秒程度の間隔で確認します。例のID・42は実値に置き換えます。

{
  "sessionId": "<current-session-id>",
  "request": {
    "documentId": "<current-document-id>",
    "expectedRevision": 42,
    "operationId": "<new-UUID-in-D-format>",
    "filePath": "D:/CAD_Output/part.jdc",
    "format": "jdc",
    "overwrite": false,
    "timeoutSeconds": 300
  }
}
{
  "sessionId": "<same-session-id>",
  "operationId": "<same-operation-id>"
}

completedのときだけ「保存完了」と報告し、filePath・bytes・sha256とwarningsを伝えます。OBJではadditionalFilesも渡します。failed/cancelledならerror.code・messageを報告し、licenseRestrictionがあれば必要プランを示します。状態照会自体が成功しても、state=failedなら書出しは失敗です。開始時の拒否はMCPのisError=true、受付後の失敗は状態結果のerrorに入ります。cad_commit_jobは呼びません。

7. 結果型・エラーと復旧

FileOperationInfo意味
OperationId / DocumentId / SourceRevision要求ID・対象図面・処理開始時revision
Kind / FilePath / Formatsave/export、絶対パス、正規化した形式
Staterunning / completed / failed / cancelled
DocumentSavedSaveのcompletedのみtrue
Bytes / Sha256確定した主ファイルのサイズとSHA256
Warnings / AdditionalFiles変換時の注意、OBJのMTL(パス・サイズ・SHA256)
ErrorFileOutputError: Code / Message / Retryable / LicenseRestriction
コード対処
license_required利用プランを説明。無条件再試行しない
unsupported_format / format_extension_mismatch対応形式・用途・拡張子を修正
invalid_argument / directory_not_found入力と親フォルダーを確認
file_exists / active_document_target上書き意図を確認。現図面へはSaveを使用
file_locked / access_denied / io_error他アプリのロック・読取専用・権限等を確認
destination_changed / file_busy他処理の更新・使用中の保存先を確認
revision_conflict / document_changed / cad_busy図面・編集状態を確認して情報を再取得
operation_conflict / file_operation_not_found同一IDの異なる要求、別セッションを確認
file_operation_limit128件の履歴上限。処理完了後にCADを再起動
worker_unavailable / worker_failed本体と対応ワーカーの配置を確認
export_failed / unsupported_geometry変換対象の形状・形式を見直す
operation_timeout / cancelled未完了。条件を見直して新規要求

履歴はCADウィンドウの存続中だけ保持します。同じIDの完了結果は過去の書込みの記録で、後から消されたファイルを再作成しません。再起動後に結果が不明なら実ファイルを確認してから判断してください。無条件の新ID再送は上書きや二重出力の原因になります。