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

);
ParameterTypeMeaning
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<DocumentInfo>. Await the Task.

PropertyType
Idstring
FileNamestring
Revisionlong
ObjectCountint
CanUndobool
CanRedobool
LengthUnitstring
CoordinateSystemstring

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

);
ParameterTypeMeaning
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<CapabilityInfo>. Await the Task.

PropertyType
Majorint
Minorint
CoordinateSystemstring
LengthUnitstring
OperationsOperationInfo[]
Limitationsstring[]
LicenseLicenseCapabilities

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

);
ParameterTypeMeaning
operationstringRegistered operation name from GetCapabilitiesAsync.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<OperationSchema>. Await the Task.

PropertyType
OperationOperationInfo
ParametersSchemaText.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

);
ParameterTypeMeaning
requestDocumentRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<LayerPage>. Await the Task.

PropertyType
DocumentDocumentInfo
LayersLayerInfo[]
LinePatternsstring[]
LineWidthsstring[]

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

);
ParameterTypeMeaning
requestOperationRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestCreateGeometryRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestCreateCurvesRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
offsetintNumber of entries to skip; zero-based.
limitintMaximum items per page within this method’s limit.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<SelectionInfo>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Totalint
Offsetint

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

);
ParameterTypeMeaning
requestEntityQueryConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EntityPage>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Totalint
Offsetint

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

);
ParameterTypeMeaning
requestEntityDetailsRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EntityDetailsResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityDetail[]

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

);
ParameterTypeMeaning
requestEntityEditRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestEntityDetailsRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<AttributePage>. Await the Task.

PropertyType
DocumentDocumentInfo
ItemsAttributeInfo[]

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

);
ParameterTypeMeaning
requestTopologyRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<TopologyPage>. Await the Task.

PropertyType
DocumentDocumentInfo
ItemsTopologyItem[]
Totalint
Offsetint

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

);
ParameterTypeMeaning
requestQueryRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<QueryResult>. Await the Task.

PropertyType
DocumentDocumentInfo
DataText.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

);
ParameterTypeMeaning
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<InteractiveCommandInfo[]>. Await the Task.

PropertyType
Idstring
Groupstring
Availablebool
UnavailableReasonstring
UnavailableCodestring
LicenseRestrictionLicenseRestriction

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

);
ParameterTypeMeaning
requestInteractiveCommandRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<InteractiveCommandResult>. Await the Task.

PropertyType
CommandIdstring
Statestring
Messagestring

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

);
ParameterTypeMeaning
requestTranslateEntitiesRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestEntityEditRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestHistoryRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestHistoryRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestStartOperationRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<JobInfo>. Await the Task.

PropertyType
Idstring
DocumentIdstring
SourceRevisionlong
Operationstring
Statestring
Stagestring
ResultCountint
ErrorCodestring
Messagestring

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

);
ParameterTypeMeaning
jobIdstringJobInfo.Id returned by StartOperationAsync.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<JobInfo>. Await the Task.

PropertyType
Idstring
DocumentIdstring
SourceRevisionlong
Operationstring
Statestring
Stagestring
ResultCountint
ErrorCodestring
Messagestring

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

);
ParameterTypeMeaning
jobIdstringJobInfo.Id returned by StartOperationAsync.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<JobInfo>. Await the Task.

PropertyType
Idstring
DocumentIdstring
SourceRevisionlong
Operationstring
Statestring
Stagestring
ResultCountint
ErrorCodestring
Messagestring

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

);
ParameterTypeMeaning
requestCommitJobRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<EditResult>. Await the Task.

PropertyType
DocumentDocumentInfo
EntitiesEntityInfo[]
Changedbool

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

);
ParameterTypeMeaning
requestJobDataRequestConstruct the request type below. Editing requires current document/revision and a new UUID.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<JobDataPage>. Await the Task.

PropertyType
JobJobInfo
Sectionstring
DataText.Json.JsonElement
Totalint
Offsetint

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

);
ParameterTypeMeaning
apiICadApiHost API; test and cast to the required extended interface.
cancellationTokenCancellationTokenCancellation token; cancels queued work before it begins. A short atomic edit completes once started.

Return value

Task<CommandResult>. Await the Task.

PropertyType
Messagestring

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

);
ParameterTypeMeaning
tabRibbonTabRibbonTab 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

);
ParameterTypeMeaning
contextIAddinContextHost 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

MethodCategory
CancelFileOperationAsyncOpen, save and export
CancelJobAsync3D and background operations
CommitJobAsync3D and background operations
CreateCurvesAsyncDrawing: lines, circles and closed profiles
CreateGeometryAsyncDrawing: lines, circles and closed profiles
DeleteEntitiesAsyncEditing, copying and history
ExecuteAsyncCommand registration and add-ins
ExecuteOperationAsyncSettings and connection
ExportDocumentAsyncOpen, save and export
GetAttributesAsyncSelection and geometry inspection
GetCapabilitiesAsyncSettings and connection
GetDocumentAsyncSettings and connection
GetEntitiesAsyncSelection and geometry inspection
GetEntityDetailsAsyncSelection and geometry inspection
GetFileFormatsAsyncOpen, save and export
GetFileOperationAsyncOpen, save and export
GetInteractiveCommandsAsyncInput and interactive commands
GetJobAsync3D and background operations
GetJobDataAsyncMeasurement and analysis
GetLayersAsyncSettings and connection
GetOperationSchemaAsyncSettings and connection
GetSelectionAsyncSelection and geometry inspection
GetTopologyAsyncSelection and geometry inspection
LaunchInteractiveCommandAsyncInput and interactive commands
OnShutdownCommand registration and add-ins
OnStartupCommand registration and add-ins
QueryAsyncSelection and geometry inspection
RedoAsyncEditing, copying and history
RegisterTabCommand registration and add-ins
SaveDocumentAsyncOpen, save and export
SetSelectionAsyncSelection and geometry inspection
StartOperationAsync3D and background operations
TranslateEntitiesAsyncEditing, copying and history
UndoAsyncEditing, copying and history