API reference by task
Browse settings, drawing, selection, input, editing, 3D, sheet metal, analysis, layouts and file output. Method details and working examples are grouped by purpose.
Download the runnable examples (.NET 8)
Prepare to run the examples
The supplied Samples.cs compiles against JDesignCAD.Api.dll on .NET 8 with implicit usings. It uses System, LINQ, threading/tasks, collections, System.Text.Json and JDesignCAD.Api. Connect externally with Connect(processId), or cast IAddinContext.Api to ICadFileApi inside an add-in. Pass CancellationToken.None or a token from your own CancellationTokenSource.
Run geometry-changing examples in a new practice drawing. Use a fresh OperationId UUID; only an identical transport retry reuses it. Never hide a conflict by changing only the revision. Inspect CadApiException.Code and distinguish availability, licensing and invalid geometry.
In ApiExamples, run dotnet build. Open a practice drawing in JDesignCAD and run dotnet run -- --list to find its ProcessId. For example, dotnet run -- 1234 drawing creates a line and circle; replace 1234 with the actual ProcessId. inspect reads the selection, rectangle draws a closed profile, box creates a solid and sheet creates a sheet-metal base. Program.cs is the entry point; Samples.cs contains the implementations.
Settings and connection
Operation reference: styles.lineWidth, styles.linePattern
Pass a ProcessId obtained from FindSessions to Connect; do not silently choose the first window. Lengths are WCS millimetres regardless of display units, and angles are degrees. SettingsAsync creates or updates the Example layer; inspect Layers in the returned page.
Working example: connect
public static ICadFileApi Connect(int processId)
{
SessionInfo session = LocalProtocol.FindSessions()
.Single(s => s.ProcessId == processId);
return new LocalCadClient(session);
}Working example: settings
public static async Task<LayerPage> SettingsAsync(
ICadAutomationApi cad, CancellationToken ct = default)
{
CapabilityInfo caps = await cad.GetCapabilitiesAsync(ct);
if (!caps.Operations.Any(o => o.Name == "layers.set" && o.Available))
throw new InvalidOperationException("layers.set is unavailable.");
OperationSchema schema = await cad.GetOperationSchemaAsync("layers.set", ct);
Console.WriteLine(schema.ParametersSchema.GetRawText());
DocumentInfo doc = await cad.GetDocumentAsync(ct);
EditResult edit = await cad.ExecuteOperationAsync(doc.Operation("layers.set",
new SetLayerParameters("Example", new CadColor("rgb", "0080C0"))), ct);
return await cad.GetLayersAsync(
new DocumentRequest(edit.Document.Id, edit.Document.Revision), ct);
}ICadApi.GetDocumentAsync
Read the active drawing — Returns the document ID, revision, object count and Undo/Redo availability. Call immediately before constructing an edit request.
Declaration
Task<DocumentInfo> GetDocumentAsync(
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<DocumentInfo>. Await the Task.
| Property | Type |
|---|---|
| Id | string |
| FileName | string |
| Revision | long |
| ObjectCount | int |
| CanUndo | bool |
| CanRedo | bool |
| LengthUnit | string |
| CoordinateSystem | string |
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadAutomationApi.GetCapabilitiesAsync
Discover operations and license conditions — Returns registered names, parameter types, execution modes, availability, restriction details and current plan. Do not invent operation names; check Available.
Declaration
Task<CapabilityInfo> GetCapabilitiesAsync(
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<CapabilityInfo>. Await the Task.
| Property | Type |
|---|---|
| Major | int |
| Minor | int |
| CoordinateSystem | string |
| LengthUnit | string |
| Operations | OperationInfo[] |
| Limitations | string[] |
| License | LicenseCapabilities |
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadAutomationApi.GetOperationSchemaAsync
Read an operation schema — Returns JSON Schema for a registered operation, including required fields, types, nullability and nested objects. JSON names use camelCase.
Declaration
Task<OperationSchema> GetOperationSchemaAsync(
string operation,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| operation | string | Registered operation name from GetCapabilitiesAsync. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<OperationSchema>. Await the Task.
| Property | Type |
|---|---|
| Operation | OperationInfo |
| ParametersSchema | Text.Json.JsonElement |
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadAutomationApi.GetLayersAsync
List layers and line styles — Returns layer definitions and available line pattern/width names. Use these names when changing drawing attributes.
Declaration
Task<LayerPage> GetLayersAsync(
DocumentRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | DocumentRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<LayerPage>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Layers | LayerInfo[] |
| LinePatterns | string[] |
| LineWidths | string[] |
Request record
public sealed record DocumentRequest(string DocumentId, long ExpectedRevision);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadAutomationApi.ExecuteOperationAsync
Execute an immediate operation — Executes an immediate operation as one Undo step. Send worker operations to StartOperationAsync. Unknown parameter fields are rejected.
Declaration
Task<EditResult> ExecuteOperationAsync(
OperationRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | OperationRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record OperationRequest(string DocumentId, long ExpectedRevision, string OperationId,
string Operation, JsonElement Parameters, bool SelectResult = true);Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
Drawing: lines, circles and closed profiles
Operation reference: geometry.clothoid, geometry.clothoid.basic, geometry.clothoid.stations
DrawingAsync creates a 60 mm line and radius-10 circle in one Undo step. RectangleAsync creates a closed 80 × 50 polyline; do not repeat the first vertex when Closed=true. Pass returned entity IDs to later edits.
Working example: drawing
public static async Task<EditResult> DrawingAsync(
ICadApi cad, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
var request = new CreateGeometryRequest(doc.Id, doc.Revision,
Guid.NewGuid().ToString("D"),
new[] { new LineDefinition(new(0, 0, 0), new(60, 0, 0)) },
new[] { new CircleDefinition(new(30, 20, 0), 10, new(0, 0, 1)) });
EditResult result = await cad.CreateGeometryAsync(request, ct);
Console.WriteLine($"Created: {result.Entities.Length}; revision: {result.Document.Revision}");
return result;
}Working example: curves
public static async Task<EditResult> RectangleAsync(
ICadModelApi cad, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
var rectangle = new PolylineDefinition(new Point3[] {
new(0, 0, 0), new(80, 0, 0), new(80, 50, 0), new(0, 50, 0)
}, Closed: true);
return await cad.CreateCurvesAsync(new CreateCurvesRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D"),
new[] { rectangle }, Array.Empty<ArcDefinition>()), ct);
}ICadApi.CreateGeometryAsync
Create lines and circles — Creates 1–1000 lines/circles in one atomic Undo batch. Pass empty arrays for unused kinds and a nonzero circle normal.
Declaration
Task<EditResult> CreateGeometryAsync(
CreateGeometryRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | CreateGeometryRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record CreateGeometryRequest(string DocumentId, long ExpectedRevision, string OperationId,
LineDefinition[] Lines, CircleDefinition[] Circles, bool SelectCreated = true);Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadModelApi.CreateCurvesAsync
Create polylines and arcs — Creates up to 1000 curves and 4096 polyline vertices. Do not repeat the first point to close a polyline. Arc sweeps are signed right-hand angles with 0 < absolute sweep < 360 degrees.
Declaration
Task<EditResult> CreateCurvesAsync(
CreateCurvesRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | CreateCurvesRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record CreateCurvesRequest(string DocumentId, long ExpectedRevision, string OperationId,
PolylineDefinition[] Polylines, ArcDefinition[] Arcs, bool SelectCreated = true);Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
Selection and geometry inspection
Point input, rubber bands and entity selection: C#/VB.NET examples
Selection results may be paged; check Total and Offset. Inspection paging must use the same revision. Refresh face and edge references after edits; do not reuse a hard-coded subobject index on another shape.
Working example: selection
public static async Task<SelectionInfo> SelectCreatedAsync(
ICadModelApi cad, CancellationToken ct = default)
{
EditResult created = await DrawingAsync(cad, ct);
DocumentInfo doc = await cad.GetDocumentAsync(ct);
await cad.SetSelectionAsync(new EntityEditRequest(doc.Id, doc.Revision,
Guid.NewGuid().ToString("D"), created.Entities.Select(e => e.Id).ToArray()), ct);
SelectionInfo selection = await cad.GetSelectionAsync(0, 256, ct);
Console.WriteLine($"Selected {selection.Entities.Length} of {selection.Total}");
return selection;
}Working example: inspect
public static async Task InspectAsync(
ICadAutomationApi cad, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
int offset = 0;
while (true)
{
EntityPage page = await cad.GetEntitiesAsync(
new EntityQuery(doc.Id, doc.Revision, offset, 100), ct);
if (page.Entities.Length == 0) break;
var request = new EntityDetailsRequest(doc.Id, doc.Revision,
page.Entities.Select(e => e.Id).ToArray());
EntityDetailsResult details = await cad.GetEntityDetailsAsync(request, ct);
AttributePage attributes = await cad.GetAttributesAsync(request, ct);
foreach (EntityDetail item in details.Entities)
Console.WriteLine($"{item.Entity.Id}: {item.GeometryStatus}");
foreach (AttributeInfo item in attributes.Items)
Console.WriteLine($"Layer: {item.Entity.Layer}; locked: {item.LayerLocked}");
offset += page.Entities.Length;
if (offset >= page.Total) break;
}
}Working example: topology
public static async Task<TopologyItem[]> EdgesAsync(
ICadAutomationApi cad, string entityId, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
var edges = new List<TopologyItem>();
do
{
TopologyPage page = await cad.GetTopologyAsync(new TopologyRequest(
doc.Id, doc.Revision, entityId, "edge", edges.Count, 128), ct);
edges.AddRange(page.Items);
if (edges.Count >= page.Total || page.Items.Length == 0) break;
} while (true);
return edges.ToArray();
}ICadApi.GetSelectionAsync
Read the selection — Pages through selected entities with IDs, types, layers and WCS bounds. Offset is zero-based; limit is 1–1000.
Declaration
Task<SelectionInfo> GetSelectionAsync(
int offset = 0,
int limit = 256,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| offset | int | Number of entries to skip; zero-based. |
| limit | int | Maximum items per page within this method’s limit. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<SelectionInfo>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Total | int |
| Offset | int |
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadModelApi.GetEntitiesAsync
List model entities — Lists top-level model entities in drawing order. Keep the same revision across pages; restart paging if the drawing changes.
Declaration
Task<EntityPage> GetEntitiesAsync(
EntityQuery request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | EntityQuery | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EntityPage>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Total | int |
| Offset | int |
Request record
public sealed record EntityQuery(string DocumentId, long ExpectedRevision, int Offset = 0, int Limit = 256);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadModelApi.GetEntityDetailsAsync
Read basic entity geometry — Reads exact line, circle, arc and linear polyline definitions for 1–100 IDs. Inspect GeometryStatus: unsupported/too_large does not mean geometry was returned.
Declaration
Task<EntityDetailsResult> GetEntityDetailsAsync(
EntityDetailsRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | EntityDetailsRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EntityDetailsResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityDetail[] |
Request record
public sealed record EntityDetailsRequest(string DocumentId, long ExpectedRevision, string[] EntityIds);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadModelApi.SetSelectionAsync
Replace the selection — Selects explicit top-level IDs; an empty array clears selection. Changes highlighting without adding an Undo step.
Declaration
Task<EditResult> SetSelectionAsync(
EntityEditRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | EntityEditRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record EntityEditRequest(string DocumentId, long ExpectedRevision, string OperationId, string[] EntityIds);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadAutomationApi.GetAttributesAsync
Read entity attributes — Reads color, line pattern, line width and layer lock for 1–100 IDs. Distinguishes byLayer/byBlock/foreground/rgb colors.
Declaration
Task<AttributePage> GetAttributesAsync(
EntityDetailsRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | EntityDetailsRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<AttributePage>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Items | AttributeInfo[] |
Request record
public sealed record EntityDetailsRequest(string DocumentId, long ExpectedRevision, string[] EntityIds);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadAutomationApi.GetTopologyAsync
Read face edge and vertex references — Pages through faces, edges or vertices of a solid, shell or face. Kind is face/edge/vertex; limit is 1–256. SubobjectRef expires on revision changes.
Declaration
Task<TopologyPage> GetTopologyAsync(
TopologyRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | TopologyRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<TopologyPage>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Items | TopologyItem[] |
| Total | int |
| Offset | int |
Request record
public sealed record TopologyRequest(string DocumentId, long ExpectedRevision, string EntityId,
string Kind = "face", int Offset = 0, int Limit = 128);Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadWorkspaceApi.QueryAsync
Query extended drawing data — Kind geometry reads extended geometry; sheet reads sheet-metal data; blocks lists definitions/direct model insertions; styles lists style names. Use 1–100 IDs for geometry/sheet and an empty array otherwise.
Declaration
Task<QueryResult> QueryAsync(
QueryRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | QueryRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<QueryResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Data | Text.Json.JsonElement |
Request record
public sealed record QueryRequest(string DocumentId,long ExpectedRevision,string Kind,string[] EntityIds);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
Input and interactive commands
Point input, rubber bands and entity selection: C#/VB.NET examples
ICadInputApi returns user input without launching a standard drawing command. Await GetPointAsync or another input method, check Accepted, then use Point or Entities to create/edit geometry. Never use .Wait()/.Result on the UI thread. Carry the returned Document into the next request.
Working example: input
public static async Task<InteractiveCommandResult> LaunchInputAsync(
ICadInteractionApi cad, string commandId,
CancellationToken ct = default)
{
InteractiveCommandInfo[] commands = await cad.GetInteractiveCommandsAsync(ct);
InteractiveCommandInfo command = commands.Single(c => c.Id == commandId);
if (!command.Available)
throw new InvalidOperationException(command.UnavailableReason);
DocumentInfo doc = await cad.GetDocumentAsync(ct);
return await cad.LaunchInteractiveCommandAsync(new InteractiveCommandRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D"), command.Id), ct);
}ICadInteractionApi.GetInteractiveCommandsAsync
List interactive GUI commands — Lists 266 registered GUI command IDs and their availability. These launch user interactions; they are not parameterized geometry APIs.
Declaration
Task<InteractiveCommandInfo[]> GetInteractiveCommandsAsync(
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<InteractiveCommandInfo[]>. Await the Task.
| Property | Type |
|---|---|
| Id | string |
| Group | string |
| Available | bool |
| UnavailableReason | string |
| UnavailableCode | string |
| LicenseRestriction | LicenseRestriction |
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadInteractionApi.LaunchInteractiveCommandAsync
Queue an interactive GUI command — Queues a GUI command for the user to complete. queued acknowledges dispatch; it does not confirm geometry creation, saving or analysis completion.
Declaration
Task<InteractiveCommandResult> LaunchInteractiveCommandAsync(
InteractiveCommandRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | InteractiveCommandRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<InteractiveCommandResult>. Await the Task.
| Property | Type |
|---|---|
| CommandId | string |
| State | string |
| Message | string |
Request record
public sealed record InteractiveCommandRequest(string DocumentId,long ExpectedRevision,string OperationId,string CommandId);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
Editing, copying and history
CopySelectionAsync makes a copy 100 mm along X and preserves the source. The delete/history example targets only its own newly created objects. Do not interleave unrelated user edits with Undo/Redo; carry the returned document revision forward.
Working example: edit
public static async Task<EditResult> CopySelectionAsync(
ICadModelApi cad, CancellationToken ct = default)
{
SelectionInfo selected = await cad.GetSelectionAsync(0, 256, ct);
if (selected.Total == 0 || selected.Total > selected.Entities.Length)
throw new InvalidOperationException("Select 1 to 256 complete model objects.");
DocumentInfo doc = selected.Document;
return await cad.TranslateEntitiesAsync(new TranslateEntitiesRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D"),
selected.Entities.Select(e => e.Id).ToArray(),
new Point3(100, 0, 0), Copy: true), ct);
}Working example: history
public static async Task DeleteOwnExampleAndUndoAsync(
ICadModelApi cad, CancellationToken ct = default)
{
EditResult made = await DrawingAsync(cad, ct);
DocumentInfo doc = made.Document;
EditResult deleted = await cad.DeleteEntitiesAsync(new EntityEditRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D"),
made.Entities.Select(e => e.Id).ToArray()), ct);
doc = deleted.Document;
EditResult undone = await cad.UndoAsync(new HistoryRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D")), ct);
doc = undone.Document;
if (doc.CanRedo)
await cad.RedoAsync(new HistoryRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D")), ct);
}ICadModelApi.TranslateEntitiesAsync
Move or copy entities — Translates 1–1000 top-level entities by WCS displacement. Copy=true preserves originals and their attributes; the entire batch is one Undo step.
Declaration
Task<EditResult> TranslateEntitiesAsync(
TranslateEntitiesRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | TranslateEntitiesRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record TranslateEntitiesRequest(string DocumentId, long ExpectedRevision, string OperationId,
string[] EntityIds, Point3 Displacement, bool Copy = false, bool SelectResult = true);Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadModelApi.DeleteEntitiesAsync
Delete entities — Deletes 1–1000 explicit IDs after inspection. Locked layers and stale/removed IDs are rejected.
Declaration
Task<EditResult> DeleteEntitiesAsync(
EntityEditRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | EntityEditRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record EntityEditRequest(string DocumentId, long ExpectedRevision, string OperationId, string[] EntityIds);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadApi.UndoAsync
Undo the latest operation — Undoes the latest drawing operation, including manual edits. This is not restricted to edits made by the API.
Declaration
Task<EditResult> UndoAsync(
HistoryRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | HistoryRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record HistoryRequest(string DocumentId, long ExpectedRevision, string OperationId);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadApi.RedoAsync
Redo the latest undone operation — Check CanRedo first. The returned Document describes the resulting drawing state.
Declaration
Task<EditResult> RedoAsync(
HistoryRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | HistoryRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record HistoryRequest(string DocumentId, long ExpectedRevision, string OperationId);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
3D and background operations
RunEditAsync implements start, polling, ready and commit. A drawing change during calculation invalidates the result; refresh selections and references before restarting. Cancellation also calls CancelJobAsync. BoxAsync creates an 80 × 50 × 20 mm solid.
Working example: worker
public static async Task<EditResult> RunEditAsync<T>(
ICadJobApi cad, string operation, T parameters,
CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
JobInfo job = await cad.StartOperationAsync(new StartOperationRequest(
doc.Operation(operation, parameters), TimeoutSeconds: 120), ct);
try
{
while (job.State == "running")
{
await Task.Delay(200, ct);
job = await cad.GetJobAsync(job.Id, ct);
}
if (job.State != "ready")
throw new InvalidOperationException($"{job.State}: {job.ErrorCode}: {job.Message}");
return await cad.CommitJobAsync(new CommitJobRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D"), job.Id), ct);
}
catch (OperationCanceledException)
{
await cad.CancelJobAsync(job.Id, CancellationToken.None);
throw;
}
}Working example: solid
public static Task<EditResult> BoxAsync(
ICadJobApi cad, CancellationToken ct = default) =>
RunEditAsync(cad, "solid.primitive",
new PrimitiveParameters("box", new(0, 0, 0),
Size: new Point3(80, 50, 20)), ct);ICadJobApi.StartOperationAsync
Start an isolated calculation — Calculates detached geometry in a separate worker process without editing the drawing. At most four pending running/ready jobs and one active worker; timeout is 1–1800 seconds.
Declaration
Task<JobInfo> StartOperationAsync(
StartOperationRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | StartOperationRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<JobInfo>. Await the Task.
| Property | Type |
|---|---|
| Id | string |
| DocumentId | string |
| SourceRevision | long |
| Operation | string |
| State | string |
| Stage | string |
| ResultCount | int |
| ErrorCode | string |
| Message | string |
Request record
public sealed record StartOperationRequest(OperationRequest Request, int TimeoutSeconds = 120);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadJobApi.GetJobAsync
Read calculation state — Distinguishes running, ready, completed, failed, cancelled and committed. A ready result has not yet been applied to the drawing.
Declaration
Task<JobInfo> GetJobAsync(
string jobId,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| jobId | string | JobInfo.Id returned by StartOperationAsync. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<JobInfo>. Await the Task.
| Property | Type |
|---|---|
| Id | string |
| DocumentId | string |
| SourceRevision | long |
| Operation | string |
| State | string |
| Stage | string |
| ResultCount | int |
| ErrorCode | string |
| Message | string |
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadJobApi.CancelJobAsync
Cancel a job or discard a ready result — Cancels running work or discards ready geometry. Use UndoAsync to undo a committed edit.
Declaration
Task<JobInfo> CancelJobAsync(
string jobId,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| jobId | string | JobInfo.Id returned by StartOperationAsync. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<JobInfo>. Await the Task.
| Property | Type |
|---|---|
| Id | string |
| DocumentId | string |
| SourceRevision | long |
| Operation | string |
| State | string |
| Stage | string |
| ResultCount | int |
| ErrorCode | string |
| Message | string |
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
ICadJobApi.CommitJobAsync
Commit a ready result — Commits a ready result in one Undo step. Rejects drawing changes since calculation started and rechecks permissions. Use a new commit UUID, separate from the start UUID.
Declaration
Task<EditResult> CommitJobAsync(
CommitJobRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | CommitJobRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<EditResult>. Await the Task.
| Property | Type |
|---|---|
| Document | DocumentInfo |
| Entities | EntityInfo[] |
| Changed | bool |
Request record
public sealed record CommitJobRequest(string DocumentId, long ExpectedRevision, string OperationId, string JobId);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
Sheet metal
SheetAsync first displays the project defaults, then creates an example plate with thickness 1, inner radius 2 and K factor 0.4. These example values are not universal manufacturing defaults. Obtain fresh edge references before adding flanges.
Working example: sheet
public static async Task<EditResult> SheetAsync(
ICadWorkspaceApi cad, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
QueryResult defaults = await cad.QueryAsync(new QueryRequest(
doc.Id, doc.Revision, "sheetDefaults", Array.Empty<string>()), ct);
Console.WriteLine(defaults.Data.GetRawText());
EditResult profile = await RectangleAsync(cad, ct);
// This example intentionally specifies t=1, R=2, K=0.4.
// Use the drawing or the inspected project defaults for production parts.
return await RunEditAsync(cad, "sheet.plate", new SheetPlateParameters(
profile.Entities.Single().Id, new SheetRules(1, 2, .4)), ct);
}Measurement and analysis
Operation reference: measure.contour, measure.highlight, analysis.assembly.contacts, analysis.assembly.mesh, analysis.assembly.solve
Measurement/analysis operations return worker-data, retrieved with GetJobDataAsync after completed. AnalysisAsync is a single-material example. Assemblies use analysis.assembly.contacts/mesh/solve with per-body materials. Retrieve all pages of points, elements and boundaries before solving.
Working example: data
public static async Task<JobDataPage> MeasureAsync(
ICadWorkspaceApi cad, string[] entityIds, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
JobInfo job = await cad.StartOperationAsync(new StartOperationRequest(
doc.Operation("measure.geometry", new MeasureParameters(entityIds))), ct);
while (job.State == "running")
{
await Task.Delay(200, ct);
job = await cad.GetJobAsync(job.Id, ct);
}
if (job.State != "completed")
throw new InvalidOperationException($"{job.State}: {job.Message}");
return await cad.GetJobDataAsync(new JobDataRequest(job.Id, "summary"), ct);
}Working example: analysis
public static async Task<JobInfo> RunDataAsync<T>(
ICadWorkspaceApi cad, string operation, T parameters,
CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
JobInfo job = await cad.StartOperationAsync(new StartOperationRequest(
doc.Operation(operation, parameters), TimeoutSeconds: 120), ct);
while (job.State == "running")
{
await Task.Delay(200, ct);
job = await cad.GetJobAsync(job.Id, ct);
}
if (job.State != "completed")
throw new InvalidOperationException($"{job.State}: {job.Message}");
return job;
}
public static async Task<T[]> ReadArrayAsync<T>(
ICadWorkspaceApi cad, string jobId, string section,
CancellationToken ct = default)
{
var items = new List<T>();
do
{
JobDataPage page = await cad.GetJobDataAsync(
new JobDataRequest(jobId, section, items.Count, 128), ct);
T[] batch = page.Data.Deserialize<T[]>(LocalProtocol.Json)
?? throw new InvalidOperationException("Missing result data.");
items.AddRange(batch);
if (items.Count >= page.Total || batch.Length == 0) break;
} while (true);
return items.ToArray();
}
public static async Task<JobDataPage> AnalysisAsync(
ICadWorkspaceApi cad, CancellationToken ct = default)
{
EditResult box = await BoxAsync(cad, ct);
JobInfo job = await RunDataAsync(cad, "analysis.mesh",
new AnalysisMeshParameters(new[] { box.Entities.Single().Id }, 3, 10), ct);
double[][] points = await ReadArrayAsync<double[]>(cad, job.Id, "points", ct);
int[][] elements = await ReadArrayAsync<int[]>(cad, job.Id, "elements", ct);
AnalysisBoundaryData[] boundaries = await ReadArrayAsync<AnalysisBoundaryData>(
cad, job.Id, "boundaries", ct);
int[] GroupsAt(double x) => boundaries.Where(b =>
b.Nodes.All(n => Math.Abs(points[n][0] - x) < 1e-6))
.Select(b => b.Group).Distinct().ToArray();
int[] fixedGroups = GroupsAt(0), loadedGroups = GroupsAt(80);
if (fixedGroups.Length == 0 || loadedGroups.Length == 0)
throw new InvalidOperationException("Expected end faces were not found.");
var mesh = new AnalysisMeshData(3, points, elements, boundaries);
var conditions = new[] {
new AnalysisConditionData("fixed", Groups: fixedGroups),
new AnalysisConditionData("totalforce", Groups: loadedGroups, Z: -100)
};
JobInfo result = await RunDataAsync(cad, "analysis.solve",
new AnalysisSolveParameters(mesh, new AnalysisMaterialData(), conditions), ct);
return await cad.GetJobDataAsync(new JobDataRequest(result.Id, "summary"), ct);
}ICadWorkspaceApi.GetJobDataAsync
Read completed measurement or analysis data — Reads summary or a named result array from a completed data job, 1–256 items per page. Data jobs require no commit.
Declaration
Task<JobDataPage> GetJobDataAsync(
JobDataRequest request,
CancellationToken cancellationToken = default
);| Parameter | Type | Meaning |
|---|---|---|
| request | JobDataRequest | Construct the request type below. Editing requires current document/revision and a new UUID. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<JobDataPage>. Await the Task.
| Property | Type |
|---|---|
| Job | JobInfo |
| Section | string |
| Data | Text.Json.JsonElement |
| Total | int |
| Offset | int |
Request record
public sealed record JobDataRequest(string JobId,string Section="summary",int Offset=0,int Limit=128);
Errors and conditions
Check no_document, invalid_argument and document_changed/revision_conflict/entity_not_found as applicable. Editing may return cad_busy/layer_locked/undo_disabled. Restricted operations return license_required; reading a schema does not authorize execution. Jobs may return job_not_found/job_not_ready; calculations may fail with geometry_failed/invalid_result. See the shared error guide.
Layouts, annotations and preview
Operation reference: layout.view, section.plane, section.generate, animation.view, animation.drive, animation.schedule, animation.control
LayoutAsync places an independent top view on landscape A4. Paper coordinates are sheet millimetres; ModelOrigin is WCS model millimetres. Match VisibleLayers to the geometry and use a unique layout name. Add native leaders with layout.annotations and verify rendering with view.capture. This is distinct from interactive VIEWBASE/VIEWPROJ projection relationships. layout.view supports creating, updating and removing views, including projection relations while preserving associated dimensions. layout.view supports creating, updating and removing views, including projection relations while preserving associated dimensions.
Working example: layout
public static async Task<EditResult> LayoutAsync(
ICadAutomationApi cad, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
var view = new LayoutViewParameters(new(0, 0, -1), new(0, 1, 0),
new(40, 25, 0), new(100, 110, 0), 1,
new LayoutRectangle(20, 180, 50, 180),
new[] { "Standard", "0", "Example" });
return await cad.ExecuteOperationAsync(doc.Operation("layout.create",
new LayoutCreateParameters("Example-A4", 297, 210, new[] { view },
Array.Empty<GeometryDefinition>(), Array.Empty<LayoutDimensionParameters>())), ct);
}Open, save and export
Use an absolute path and wait for completed; verify Bytes and Sha256. Overwrite is false by default. Save changes the drawing filename; Export writes a copy. Inspect Warnings. document.open requires a drawing with no unsaved changes. Geometry Undo does not undo file output.
Working example: files
public static async Task<FileOperationInfo> SaveAsync(
ICadFileApi cad, string absolutePath, CancellationToken ct = default)
{
FileFormatInfo[] formats = await cad.GetFileFormatsAsync(ct);
if (!formats.Any(f => f.Format == "jdc" && f.CanSave && f.Available))
throw new InvalidOperationException("JDC saving is unavailable.");
DocumentInfo doc = await cad.GetDocumentAsync(ct);
FileOperationInfo operation = await cad.SaveDocumentAsync(new SaveDocumentRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D"), absolutePath, "jdc"), ct);
return await WaitFileAsync(cad, operation, ct);
}
public static async Task<FileOperationInfo> ExportStepAsync(
ICadFileApi cad, string absolutePath, CancellationToken ct = default)
{
DocumentInfo doc = await cad.GetDocumentAsync(ct);
FileOperationInfo operation = await cad.ExportDocumentAsync(new ExportDocumentRequest(
doc.Id, doc.Revision, Guid.NewGuid().ToString("D"), absolutePath, "step"), ct);
return await WaitFileAsync(cad, operation, ct);
}
public static async Task<FileOperationInfo> WaitFileAsync(
ICadFileApi cad, FileOperationInfo operation, CancellationToken ct = default)
{
try
{
while (operation.State == "running")
{
await Task.Delay(200, ct);
operation = await cad.GetFileOperationAsync(operation.OperationId, ct);
}
}
catch (OperationCanceledException)
{
await cad.CancelFileOperationAsync(operation.OperationId, CancellationToken.None);
throw;
}
if (operation.State != "completed")
throw new InvalidOperationException($"{operation.State}: {operation.Error?.Message}");
foreach (string warning in operation.Warnings ?? Array.Empty<string>())
Console.WriteLine(warning);
Console.WriteLine($"{operation.FilePath}: {operation.Bytes} bytes; {operation.Sha256}");
return operation;
}ICadFileApi.GetFileFormatsAsync
Task<FileFormatInfo[]> GetFileFormatsAsync(CancellationToken cancellationToken = default);
The files example in this category shows complete request construction, status polling and result handling.
ICadFileApi.SaveDocumentAsync
Task<FileOperationInfo> SaveDocumentAsync(SaveDocumentRequest request, CancellationToken cancellationToken = default);
The files example in this category shows complete request construction, status polling and result handling.
ICadFileApi.ExportDocumentAsync
Task<FileOperationInfo> ExportDocumentAsync(ExportDocumentRequest request, CancellationToken cancellationToken = default);
The files example in this category shows complete request construction, status polling and result handling.
ICadFileApi.GetFileOperationAsync
Task<FileOperationInfo> GetFileOperationAsync(string operationId, CancellationToken cancellationToken = default);
The files example in this category shows complete request construction, status polling and result handling.
ICadFileApi.CancelFileOperationAsync
Task<FileOperationInfo> CancelFileOperationAsync(string operationId, CancellationToken cancellationToken = default);
The files example in this category shows complete request construction, status polling and result handling.
Command registration and add-ins
Build ExampleAddin and Samples in the same project. OnStartup registers the ribbon; button ExecuteAsync performs drawing. OnShutdown should release your event subscriptions and timers; this sample has none. Custom add-ins require a supporting license.
Working example: addin
public sealed class ExampleAddin : ICadAddin
{
public void OnStartup(IAddinContext context)
{
context.RegisterTab(new RibbonTab("example", "Example", new[] {
new RibbonPanel("draw", "Draw", new[] {
new RibbonButton("line-circle", "Line and circle",
"Create example geometry", new DrawCommand())
})
}));
}
public void OnShutdown() { }
private sealed class DrawCommand : IAddinCommand
{
public async Task<CommandResult> ExecuteAsync(ICadApi api, CancellationToken ct)
{
EditResult result = await Samples.DrawingAsync(api, ct);
return new CommandResult($"Created {result.Entities.Length} objects.");
}
}
}IAddinCommand.ExecuteAsync
Implement an add-in button — Called by the ribbon button. Access the drawing through api and forward the cancellation token. The host displays a nonempty returned Message.
Declaration
Task<CommandResult> ExecuteAsync(
ICadApi api,
CancellationToken cancellationToken
);| Parameter | Type | Meaning |
|---|---|---|
| api | ICadApi | Host API; test and cast to the required extended interface. |
| cancellationToken | CancellationToken | Cancellation token; cancels queued work before it begins. A short atomic edit completes once started. |
Return value
Task<CommandResult>. Await the Task.
| Property | Type |
|---|---|
| Message | string |
Tabs are installed only after successful startup registration. Free executes the built-in sample only; loading custom or modified DLLs requires STD/Pro.
IAddinContext.RegisterTab
Register a ribbon tab — Call only during OnStartup. IDs must be unique. Limits: 10 tabs/add-in, 1–20 panels/tab and 1–50 buttons/panel.
Declaration
void RegisterTab(
RibbonTab tab
);| Parameter | Type | Meaning |
|---|---|---|
| tab | RibbonTab | RibbonTab containing panel and button definitions. |
Return value
void
Tabs are installed only after successful startup registration. Free executes the built-in sample only; loading custom or modified DLLs requires STD/Pro.
ICadAddin.OnStartup
Register an add-in at startup — Called by the host after loading the add-in. Register tabs/panels/buttons through context.RegisterTab; defer calculations and drawing edits to commands.
Declaration
void OnStartup(
IAddinContext context
);| Parameter | Type | Meaning |
|---|---|---|
| context | IAddinContext | Host registration context exposing Api and AddinDirectory. |
Return value
void
Tabs are installed only after successful startup registration. Free executes the built-in sample only; loading custom or modified DLLs requires STD/Pro.
ICadAddin.OnShutdown
Release add-in resources — Called when the host disposes the add-in. Release owned resources and subscriptions; do not hide drawing-save operations here.
Declaration
void OnShutdown();
No parameters.
Return value
void
Tabs are installed only after successful startup registration. Free executes the built-in sample only; loading custom or modified DLLs requires STD/Pro.
Method index
| Method | Category |
|---|---|
| CancelFileOperationAsync | Open, save and export |
| CancelJobAsync | 3D and background operations |
| CommitJobAsync | 3D and background operations |
| CreateCurvesAsync | Drawing: lines, circles and closed profiles |
| CreateGeometryAsync | Drawing: lines, circles and closed profiles |
| DeleteEntitiesAsync | Editing, copying and history |
| ExecuteAsync | Command registration and add-ins |
| ExecuteOperationAsync | Settings and connection |
| ExportDocumentAsync | Open, save and export |
| GetAttributesAsync | Selection and geometry inspection |
| GetCapabilitiesAsync | Settings and connection |
| GetDocumentAsync | Settings and connection |
| GetEntitiesAsync | Selection and geometry inspection |
| GetEntityDetailsAsync | Selection and geometry inspection |
| GetFileFormatsAsync | Open, save and export |
| GetFileOperationAsync | Open, save and export |
| GetInteractiveCommandsAsync | Input and interactive commands |
| GetJobAsync | 3D and background operations |
| GetJobDataAsync | Measurement and analysis |
| GetLayersAsync | Settings and connection |
| GetOperationSchemaAsync | Settings and connection |
| GetSelectionAsync | Selection and geometry inspection |
| GetTopologyAsync | Selection and geometry inspection |
| LaunchInteractiveCommandAsync | Input and interactive commands |
| OnShutdown | Command registration and add-ins |
| OnStartup | Command registration and add-ins |
| QueryAsync | Selection and geometry inspection |
| RedoAsync | Editing, copying and history |
| RegisterTab | Command registration and add-ins |
| SaveDocumentAsync | Open, save and export |
| SetSelectionAsync | Selection and geometry inspection |
| StartOperationAsync | 3D and background operations |
| TranslateEntitiesAsync | Editing, copying and history |
| UndoAsync | Editing, copying and history |