Save/export, five methods and MCP tools, formats, completion and errors
Customization guide
Choose an extension method
An add-in DLL runs inside JDesignCAD and registers ribbon buttons. A separate .NET application uses LocalCadClient. An AI client uses the supplied MCP executable. All three use the same public drawing API; the SDK does not contain a standalone CAD engine.
Free runs the ten built-in API sample commands. Custom DLLs and modified samples require an active STD or Pro license. In Free, replacing the sample DLL or copying its ID does not execute external code: JDesignCAD uses its embedded release sample. MCP remains available in Free, while licensed sheet-metal and analysis APIs are denied.
Install the supplied API sample
- Save your drawings and close JDesignCAD.
- Open the installed Customization folder, normally C:\Program Files\JDesignCADV1\Customization.
- Copy the complete SampleAddin folder into %LOCALAPPDATA%\JDesignCAD\Addins\JDesignCAD.Customization.Sample. Alternatively run Install-Sample.ps1 from PowerShell.
- Restart CAD. Open Customization → Add-in status, then check the API sample tab.
- Open a drawing and select the target entities before running a sample command.
powershell -File "C:\Program Files\JDesignCADV1\Customization\Install-Sample.ps1"
The script stops if the destination already exists. Preserve any edited source or existing add-in before updating it manually. The sample tab and its commands currently use Japanese labels in both UI languages.
Prepare Visual Studio
- Install Visual Studio 2022 version 17.8 or newer with the .NET desktop development workload and .NET 8 SDK.
- Copy Customization\SDK to a writable development directory. Keep Api and Samples in their original relative positions.
- Open Samples\Customization.Workshop\Customization.Workshop.csproj for C#, or Samples\Customization.WorkshopVB\Customization.WorkshopVB.vbproj for VB.NET.
- Build Release for x64. The practical ten-command sample is Samples\Customization.Sample\Customization.Sample.csproj.
Reference SDK\Api\JDesignCAD.Api.dll with Copy Local=False. Keep the XML file beside the DLL for IntelliSense. Ribbon registration requires no reference to internal JDesignCore or Krypton types. Class libraries cannot be run directly with F5.
Create a new project
Select a .NET class library, not a .NET Framework class library. Set the target framework and reference as below. Add UseWindowsForms=true when you create Windows Forms input dialogs.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.0-windows</TargetFramework>
<PlatformTarget>x64</PlatformTarget>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>
<ItemGroup>
<Reference Include="JDesignCAD.Api">
<HintPath>..\..\Api\JDesignCAD.Api.dll</HintPath>
<Private>false</Private>
</Reference>
<None Update="addin.json;*.png" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
</Project>
Register a tab and button
Implement ICadAddin with a public parameterless constructor. OnStartup registers a RibbonTab containing RibbonPanel groups and RibbonButton commands. Each command implements IAddinCommand.ExecuteAsync. Keep startup registration short; perform drawing work when the user presses the button.
Use await in C# or Await in VB.NET. Do not block the UI thread with Task.Result or Wait(). The API dispatches drawing changes to the CAD UI thread. Use StartOperationAsync for heavy geometry calculations and commit a ready result explicitly.
Configure addin.json
{
"id": "MyCompany.MyTool",
"name": "My drawing tools",
"apiVersion": 1,
"assembly": "MyTool.dll",
"entryType": "MyCompany.MyTool.MyAddin",
"enabled": true
}| Field | Meaning |
|---|---|
| id | Unique add-in identifier. Retain it for updates to the same add-in; use your own ID when editing a sample. |
| apiVersion | Major version 1, including API 1.2, 1.3 and 1.4. |
| assembly | DLL path relative to this add-in folder. |
| entryType | Fully qualified public ICadAddin implementation with a parameterless constructor. |
| enabled | false disables startup loading. |
VB.NET combines RootNamespace with the class namespace. The supplied VB sample omits a Namespace block to avoid duplicating the root namespace.
Set button images
RibbonButton.SmallIconPath and LargeIconPath are paths relative to the add-in directory. Supply 24×24 and 48×48 PNG images for the usual small/large sizes. Omitted paths leave the button without an image. The first button image is also used when its group collapses.
var button = new RibbonButton("line", "Line", "Draw a line", command,
SmallIconPath: "line24.png", LargeIconPath: "line48.png");Place the PNG files beside addin.json or in its subfolder. Paths cannot escape the add-in directory. These are runtime images from the add-in folder; they are not entries in the application's Resources.resx.
Build install and debug
- Build Release/x64, then save drawings and close CAD.
- Create %LOCALAPPDATA%\JDesignCAD\Addins\MyCompany.MyTool.
- Copy your DLL, addin.json, generated deps.json, required dependency DLLs and icons. Share the host's JDesignCAD.Api.dll.
- Restart CAD and check Customization → Add-in status. Use an active STD/Pro license for a custom or modified DLL.
- For debugging, deploy the Debug DLL and PDB, then attach Visual Studio to JDesignCAD.exe as managed .NET code. Check the loaded module path and symbols if a breakpoint is not hit.
Updates require restarting CAD. The loader isolates dependency contexts; this is not a security sandbox. Add-ins run with the user's Windows privileges. The startup log is %LOCALAPPDATA%\JDesignCAD\Automation\addins.log.
Ten practical sample commands
| Ribbon label | Behavior and scope |
|---|---|
| 文字連番 | Number selected ordinary text while retaining positions and formatting. |
| 文字置換 | Case-sensitive replacement in selected text. |
| 大文字・小文字 | Change selected Latin text to upper or lower case. |
| 文字囲み | Frame WCS XY text with rectangles or circles. |
| 等間隔複写 | Copy by WCS X/Y/Z spacing and count; retain originals. |
| 同種・同層選択 | Select the same entity type and layer as one reference entity. |
| 重複線整理 | Review and remove duplicate lines/circles with matching attributes; partial overlaps are excluded. |
| 色をByLayer | Set only selected entity colors to ByLayer. |
| 長さ・面積集計 | Calculate curve lengths and closed profile areas in a worker. |
| ブロック集計 | Count named block references directly in model space, not recursive nested occurrences. |
Revision and retry rules
GetDocumentAsync returns a session-scoped ID and Revision. Use the current values to construct a request and a new UUID for each new edit. After a transport failure, resend the exact same request and operationId to recover its result. Do not generate a new UUID blindly. A different request with the same operationId is rejected. Requery face/edge references after any revision change.
Coordinate values are WCS millimetres even when the UI uses another unit. Angles are degrees. Successful edits are atomic Undo batches. Undo includes manual user actions. Read-only queries and selection changes do not add an Undo step.
Shared errors and recovery
| Code | What to do |
|---|---|
| no_document / unsupported_view | Open the intended drawing in model space. |
| cad_busy | Finish or cancel the current command/dialog. |
| document_changed / revision_conflict | Reinspect the drawing and rebuild the request from current IDs. |
| entity_not_found / entity_not_in_model | Requery top-level entity IDs in this document session. |
| layer_locked / undo_disabled | Review drawing state before editing. |
| license_required | Read LicenseRestriction and RequiredPlans. Do not retry unchanged requests to bypass the restriction. |
| geometry_failed / invalid_result | Review dimensions, topology and engine-supported geometry. The calculation does not guarantee success for every BRep input. |
| worker_unavailable | Use a complete installation containing matching Automation.Worker files. |
| message_too_large | Reduce page or request size; the local bridge limit is 1 MiB per message. |