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

  1. Save your drawings and close JDesignCAD.
  2. Open the installed Customization folder, normally C:\Program Files\JDesignCADV1\Customization.
  3. Copy the complete SampleAddin folder into %LOCALAPPDATA%\JDesignCAD\Addins\JDesignCAD.Customization.Sample. Alternatively run Install-Sample.ps1 from PowerShell.
  4. Restart CAD. Open Customization → Add-in status, then check the API sample tab.
  5. 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

  1. Install Visual Studio 2022 version 17.8 or newer with the .NET desktop development workload and .NET 8 SDK.
  2. Copy Customization\SDK to a writable development directory. Keep Api and Samples in their original relative positions.
  3. Open Samples\Customization.Workshop\Customization.Workshop.csproj for C#, or Samples\Customization.WorkshopVB\Customization.WorkshopVB.vbproj for VB.NET.
  4. 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
}
FieldMeaning
idUnique add-in identifier. Retain it for updates to the same add-in; use your own ID when editing a sample.
apiVersionMajor version 1, including API 1.2, 1.3 and 1.4.
assemblyDLL path relative to this add-in folder.
entryTypeFully qualified public ICadAddin implementation with a parameterless constructor.
enabledfalse 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

  1. Build Release/x64, then save drawings and close CAD.
  2. Create %LOCALAPPDATA%\JDesignCAD\Addins\MyCompany.MyTool.
  3. Copy your DLL, addin.json, generated deps.json, required dependency DLLs and icons. Share the host's JDesignCAD.Api.dll.
  4. Restart CAD and check Customization → Add-in status. Use an active STD/Pro license for a custom or modified DLL.
  5. 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 labelBehavior 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.
色をByLayerSet 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

CodeWhat to do
no_document / unsupported_viewOpen the intended drawing in model space.
cad_busyFinish or cancel the current command/dialog.
document_changed / revision_conflictReinspect the drawing and rebuild the request from current IDs.
entity_not_found / entity_not_in_modelRequery top-level entity IDs in this document session.
layer_locked / undo_disabledReview drawing state before editing.
license_requiredRead LicenseRestriction and RequiredPlans. Do not retry unchanged requests to bypass the restriction.
geometry_failed / invalid_resultReview dimensions, topology and engine-supported geometry. The calculation does not guarantee success for every BRep input.
worker_unavailableUse a complete installation containing matching Automation.Worker files.
message_too_largeReduce page or request size; the local bridge limit is 1 MiB per message.