C# voor AutoCAD: Bouw een boutgatenpatroon-commando

Wat we bouwen

Typ BOUTGATEN in AutoCAD, kies een middelpunt, voer een steekcirkeldiameter, het aantal gaten en de gatdiameter in — en het commando tekent het volledige patroon: elk gat op de juiste positie, de steekcirkel als hartlijn, en een kruismarkering in het midden. Precies wat je handmatig zou tekenen op een flens, lagerbehuizing of voetplaat, gedaan in seconden.

Dit is een realistische eerste add-in. Het behandelt alles wat je nodig hebt in 90% van het AutoCAD-automatiseringswerk: de gebruiker om invoer vragen, lagen programmatisch aanmaken, de geometrieberekeningen uitvoeren en entiteiten naar de tekening schrijven.

Vereisten

• Visual Studio 2019 of 2022 (Community is gratis)
• AutoCAD 2020 of later geïnstalleerd
• Het lijntype CENTER geladen in AutoCAD (standaard meegeleverd met elke installatie)
• Basiskennis C# — classes, methoden, lussen

Heb je je project en referenties nog niet ingesteld, volg dan eerst de eerste helft van onze installatiegids en kom daarna terug.

Het eindresultaat

Voor de code: dit is precies wat het commando produceert voor een 6-gatenpatroon, steekcirkeldiameter 100 mm, gatdiameter 8 mm:

• Een cirkel met diameter 100 op laag CENTRE-LINE (rood, lijntype CENTER)
• Zes cirkels met diameter 8, gelijkmatig verdeeld, op laag OBJECT (wit)
• Een klein kruis op het hoofdmiddelpunt op laag CENTRE-LINE
• Een kort hartlijnkruis in elk gat

Elk element landt automatisch op de juiste laag — geen handmatig laagwisselen nodig.

Volledige code

Maak een nieuw class-bestand aan in je project en plak dit erin:

using System;
using Autodesk.AutoCAD.ApplicationServices;
using Autodesk.AutoCAD.Colors;
using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.EditorInput;
using Autodesk.AutoCAD.Geometry;
using Autodesk.AutoCAD.Runtime;

[assembly: CommandClass(typeof(KleverCAD.BoltHoleCommand))]

namespace KleverCAD
{
    public class BoltHoleCommand
    {
        // ── Laagnamen ────────────────────────────────────────────────────────
        // Als constanten opslaan: een typfout wordt opgemerkt door de compiler,
        // niet als een stille verkeerde-laag-fout bij uitvoering.
        private const string LayerObject     = "OBJECT";
        private const string LayerCentreLine = "CENTRE-LINE";

        /// <summary>
        /// BOUTGATEN-commando — tekent een boutgatenpatroon op basis van gebruikersinvoer.
        ///
        /// Werkwijze:
        ///   1. Gebruiker kiest het middelpunt
        ///   2. Gebruiker voert de steekcirkeldiameter in
        ///   3. Gebruiker voert het aantal gaten in
        ///   4. Gebruiker voert de gatdiameter in
        ///   5. Commando tekent het patroon en rapporteert terug
        ///
        /// Escape indrukken bij een prompt annuleert netjes — er wordt niets getekend.
        /// </summary>
        [CommandMethod("BOUTGATEN")]
        public void DrawBoltHoles()
        {
            Document doc = Application.DocumentManager.MdiActiveDocument;
            Database db  = doc.Database;
            Editor   ed  = doc.Editor;

            // ── Stap 1: middelpunt ───────────────────────────────────────────
            PromptPointOptions centerOpt = new PromptPointOptions(
                "\nKies het middelpunt van het boutgatenpatroon: ");

            PromptPointResult centerRes = ed.GetPoint(centerOpt);
            if (centerRes.Status != PromptStatus.OK) return;
            Point3d center = centerRes.Value;

            // ── Stap 2: steekcirkeldiameter ──────────────────────────────────
            PromptDistanceOptions pcdOpt = new PromptDistanceOptions(
                "\nSteekcirkeldiameter (SCD): ");
            pcdOpt.BasePoint     = center;
            pcdOpt.UseBasePoint  = true;
            pcdOpt.AllowNegative = false;
            pcdOpt.AllowZero     = false;

            PromptDoubleResult pcdRes = ed.GetDistance(pcdOpt);
            if (pcdRes.Status != PromptStatus.OK) return;

            double pcdRadius = pcdRes.Value;
            double pcd       = pcdRadius * 2;

            // ── Stap 3: aantal gaten ─────────────────────────────────────────
            PromptIntegerOptions countOpt = new PromptIntegerOptions(
                "\nAantal gaten: ");
            countOpt.AllowNegative = false;
            countOpt.AllowZero     = false;
            countOpt.LowerLimit    = 2;

            PromptIntegerResult countRes = ed.GetInteger(countOpt);
            if (countRes.Status != PromptStatus.OK) return;
            int numHoles = countRes.Value;

            // ── Stap 4: gatdiameter ──────────────────────────────────────────
            PromptDistanceOptions holeOpt = new PromptDistanceOptions(
                "\nGatdiameter: ");
            holeOpt.AllowNegative = false;
            holeOpt.AllowZero     = false;

            PromptDoubleResult holeRes = ed.GetDistance(holeOpt);
            if (holeRes.Status != PromptStatus.OK) return;
            double holeDiameter = holeRes.Value;
            double holeRadius   = holeDiameter / 2.0;

            // ── Stap 5: alles tekenen in één transactie ──────────────────────
            using (Transaction tr = db.TransactionManager.StartTransaction())
            {
                // Zorg dat de lagen bestaan voor we erop tekenen.
                EnsureLayer(tr, db, LayerObject,     colorIndex: 7, linetype: "Continuous");
                EnsureLayer(tr, db, LayerCentreLine, colorIndex: 1, linetype: "CENTER");

                BlockTableRecord modelSpace = GetModelSpace(tr, db);

                // Steekcirkel (hartlijn)
                DrawCircle(tr, modelSpace, center, pcdRadius, LayerCentreLine);

                // Kruismarkering in het midden
                DrawCentreCross(tr, modelSpace, center, pcdRadius * 0.08, LayerCentreLine);

                // Gaten gelijkmatig verdelen over de steekcirkel
                double angleStep  = (2 * Math.PI) / numHoles;
                double startAngle = Math.PI / 2.0; // start bovenaan (90°)

                for (int i = 0; i < numHoles; i++)
                {
                    double angle = startAngle + (i * angleStep);

                    // Poolcoördinaten (hoek + straal) omzetten naar cartesisch (x, y)
                    double x = center.X + pcdRadius * Math.Cos(angle);
                    double y = center.Y + pcdRadius * Math.Sin(angle);
                    Point3d holeCenter = new Point3d(x, y, center.Z);

                    DrawCircle(tr, modelSpace, holeCenter, holeRadius, LayerObject);
                    DrawCentreCross(tr, modelSpace, holeCenter, holeRadius * 0.4, LayerCentreLine);
                }

                tr.Commit(); // pas hier wordt alles opgeslagen in de tekening
            }

            ed.WriteMessage(
                $"\nBoutgatenpatroon getekend: {numHoles}x Ø{holeDiameter:F1} op SCD Ø{pcd:F1}");
        }

        // ── Hulpmethode: cirkel tekenen ──────────────────────────────────────
        private static void DrawCircle(
            Transaction tr, BlockTableRecord btr,
            Point3d center, double radius, string layer)
        {
            Circle c = new Circle();
            c.Center = center;
            c.Radius = radius;
            c.Layer  = layer;
            btr.AppendEntity(c);
            tr.AddNewlyCreatedDBObject(c, true);
        }

        // ── Hulpmethode: kruismarkering tekenen (twee korte lijnen) ──────────
        private static void DrawCentreCross(
            Transaction tr, BlockTableRecord btr,
            Point3d center, double halfSize, string layer)
        {
            Line h = new Line(
                new Point3d(center.X - halfSize, center.Y, center.Z),
                new Point3d(center.X + halfSize, center.Y, center.Z));
            h.Layer = layer;
            btr.AppendEntity(h);
            tr.AddNewlyCreatedDBObject(h, true);

            Line v = new Line(
                new Point3d(center.X, center.Y - halfSize, center.Z),
                new Point3d(center.X, center.Y + halfSize, center.Z));
            v.Layer = layer;
            btr.AppendEntity(v);
            tr.AddNewlyCreatedDBObject(v, true);
        }

        // ── Hulpmethode: laag aanmaken als die nog niet bestaat ──────────────
        private static void EnsureLayer(
            Transaction tr, Database db,
            string name, short colorIndex, string linetype)
        {
            LayerTable lt = (LayerTable)tr.GetObject(
                db.LayerTableId, OpenMode.ForRead);

            if (lt.Has(name))
                return; // laag bestaat al — niets te doen

            lt.UpgradeOpen();

            LayerTableRecord ltr = new LayerTableRecord();
            ltr.Name  = name;
            ltr.Color = Color.FromColorIndex(ColorMethod.ByAci, colorIndex);

            LinetypeTable ltt = (LinetypeTable)tr.GetObject(
                db.LinetypeTableId, OpenMode.ForRead);

            if (ltt.Has(linetype))
                ltr.LinetypeObjectId = ltt[linetype];

            lt.Add(ltr);
            tr.AddNewlyCreatedDBObject(ltr, true);
        }

        // ── Hulpmethode: modelruimte ophalen ─────────────────────────────────
        private static BlockTableRecord GetModelSpace(Transaction tr, Database db)
        {
            BlockTable bt = (BlockTable)tr.GetObject(
                db.BlockTableId, OpenMode.ForRead);
            return (BlockTableRecord)tr.GetObject(
                bt[BlockTableRecord.ModelSpace], OpenMode.ForWrite);
        }
    }
}

Code-uitleg — regel voor regel

De using-statements

using Autodesk.AutoCAD.ApplicationServices;  // Application, Document
using Autodesk.AutoCAD.Colors;               // Color (voor laagkleuren)
using Autodesk.AutoCAD.DatabaseServices;     // Database, Transaction, Circle, Line, LayerTable...
using Autodesk.AutoCAD.EditorInput;          // Editor, PromptPointOptions, PromptDistanceOptions...
using Autodesk.AutoCAD.Geometry;             // Point3d, Vector3d
using Autodesk.AutoCAD.Runtime;              // CommandMethod-attribuut

Elke using-regel importeert een namespace uit de AutoCAD .NET API. DatabaseServices bevat alle tekeningobjecten, EditorInput alles wat te maken heeft met de opdrachtregel en gebruikersinvoer, en Geometry alle wiskundetypen (punten, vectoren).

Het commando registreren

[assembly: CommandClass(typeof(KleverCAD.BoltHoleCommand))]

Deze regel vertelt AutoCAD: "zoek in BoltHoleCommand naar methoden met [CommandMethod]". Zonder deze regel vindt AutoCAD je commando niet, ook al is de DLL geladen. Hij staat buiten de namespace, bovenaan het bestand.

Laagnaamconstanten

private const string LayerObject     = "OBJECT";
private const string LayerCentreLine = "CENTRE-LINE";

Laagnamen als constanten opslaan zorgt ervoor dat een typfout door de compiler wordt opgemerkt in plaats van stilzwijgend op de verkeerde laag te tekenen. Wijzig de naam op één plek en alle verwijzingen worden automatisch bijgewerkt.

De drie objecten die je altijd nodig hebt

Document doc = Application.DocumentManager.MdiActiveDocument;
Database db  = doc.Database;
Editor   ed  = doc.Editor;

doc is het huidige open tekeningbestand. db is de database van de tekening — alle entiteiten (lijnen, cirkels, lagen) leven hier. ed is de opdrachtregel en gebruikersinvoer. Deze drie regels staan aan het begin van vrijwel elk AutoCAD-commando dat je ooit schrijft.

Vragen om een punt

PromptPointOptions centerOpt = new PromptPointOptions("\nKies het middelpunt: ");
PromptPointResult  centerRes = ed.GetPoint(centerOpt);
if (centerRes.Status != PromptStatus.OK) return;
Point3d center = centerRes.Value;

De \n aan het begin zorgt voor een nieuwe regel in het opdrachtvenster. ed.GetPoint() pauzeert het commando en wacht tot de gebruiker klikt of coördinaten intypt. Als de status niet OK is (bijv. Escape ingedrukt), keren we direct terug — er is nog niets getekend, dus niets om ongedaan te maken.

Vragen om een afstand met rubber-band lijn

pcdOpt.BasePoint    = center;
pcdOpt.UseBasePoint = true;

Door BasePoint en UseBasePoint = true in te stellen tekent AutoCAD een rubber-band lijn van het middelpunt terwijl de gebruiker de muis beweegt — dezelfde visuele terugkoppeling als bij het tekenen van een cirkel. AllowNegative en AllowZero voorkomen ongeldige invoer.

Vragen om een geheel getal met limiet

countOpt.LowerLimit = 2;

LowerLimit = 2 zorgt ervoor dat AutoCAD zelf alles onder 2 afwijst en een foutmelding toont — je hoeft die validatie niet zelf te schrijven. De API handelt het af vóór het resultaat je code bereikt.

Een transactie openen

using (Transaction tr = db.TransactionManager.StartTransaction())
{
    // ... alle tekenopdrachten hier ...
    tr.Commit();
}

Een transactie is een beschermende envelop om al je tekenbewerkingen. Niets wordt permanent naar de tekening geschreven totdat tr.Commit() wordt aangeroepen. Als er een uitzondering optreedt vóór de commit, wordt de transactie automatisch teruggedraaid en blijft de tekening onaangeroerd — net als een SQL-transactie: alles of niets.

Lagen aanmaken met EnsureLayer

EnsureLayer(tr, db, LayerObject,     colorIndex: 7, linetype: "Continuous");
EnsureLayer(tr, db, LayerCentreLine, colorIndex: 1, linetype: "CENTER");

De hulpmethode controleert eerst of de laag al bestaat. Als de gebruiker BOUTGATEN tweemaal uitvoert, zijn de lagen er al — geen fout, geen duplicaat. Kleurindex 1 = rood, 7 = wit. Het lijntype CENTER geeft de steekcirkel zijn streeplijn-uiterlijk.

De boutgaten-lus

double angleStep  = (2 * Math.PI) / numHoles;
double startAngle = Math.PI / 2.0;

for (int i = 0; i < numHoles; i++)
{
    double angle = startAngle + (i * angleStep);
    double x = center.X + pcdRadius * Math.Cos(angle);
    double y = center.Y + pcdRadius * Math.Sin(angle);
    ...
}

2 * Math.PI is een volledige cirkel in radialen (360°). Delen door het aantal gaten geeft de hoek tussen elk gat. Math.Cos en Math.Sin zetten de hoek om naar X- en Y-coördinaten — standaard poolcoördinaten-naar-cartesisch. Beginnen bij 90° (boven) is een conventie in het mechanisch tekenen.

Een entiteit toevoegen aan de tekening

Circle c = new Circle();
c.Center = center;
c.Radius = radius;
c.Layer  = layer;
btr.AppendEntity(c);
tr.AddNewlyCreatedDBObject(c, true);

Een Circle-object aanmaken in C# voegt hem nog niet toe aan de tekening. btr.AppendEntity(c) voegt hem toe aan de modelruimte. tr.AddNewlyCreatedDBObject(c, true) registreert hem bij de transactie. Beide regels zijn altijd verplicht — sla er één over en de entiteit verschijnt niet of lekt geheugen.

Hoe de wiskunde werkt

double x = center.X + pcdRadius * Math.Cos(angle);
double y = center.Y + pcdRadius * Math.Sin(angle);

Dit converteert poolcoördinaten — een afstand van het middelpunt (pcdRadius) en een hoek — naar de cartesische X/Y-coördinaten die AutoCAD nodig heeft. Voor een 6-gatenpatroon zijn de hoeken 90°, 150°, 210°, 270°, 330° en 30° — gelijkmatig op 60° afstand. De formule werkt voor elk aantal gaten.

Probeer het uit te breiden

• Vraag om een starthoek — voeg een GetAngle()-prompt toe zodat de gebruiker het patroon kan roteren
• Voeg een MText-label toe — schrijf "6x Ø8 OP SCD Ø100" als tekst-entiteit onder het patroon
• Ondersteuning voor lijntype HIDDEN — voor gaten in een verborgen-lijnaanzicht
• Lees uit een tabel — laad standaard boutmaten uit een Excel- of CSV-bestand zodat de gebruiker M6, M8, M10 kiest in plaats van een diameter in te typen

Volgende stap in deze cursus

Volgende les: werken met blokken en attributen — een titelblok invoegen, attribuutvelden (tekening­nummer, revisie, schaal) vanuit code invullen en exporteren naar een spreadsheet.

De volledige C# voor AutoCAD-cursus is beschikbaar voor Standard- en Full Access-abonnees in de E-Learning-sectie.

What we're building

Type BOLTHOLES in AutoCAD, pick a center point, enter a pitch circle diameter, number of holes and hole diameter — and the command draws the complete pattern for you: each hole on the correct position, the pitch circle as a centre line, and a cross mark at the centre. Exactly what you'd draw manually on a flange, bearing housing or base plate, done in seconds.

This is a realistic first add-in. It covers everything you'll use in 90% of AutoCAD automation work: prompting the user for input, creating layers programmatically, doing the geometry maths, and writing entities to the drawing.

Prerequisites

• Visual Studio 2019 or 2022 (Community is free)
• AutoCAD 2020 or later installed
• The CENTER linetype loaded in AutoCAD (it ships with every AutoCAD installation)
• Basic C# knowledge — classes, methods, loops

If you haven't set up your project and references yet, follow the first half of our setup guide first, then come back here.

The finished result

Before the code, here's exactly what the command produces for a 6-hole pattern, PCD 100 mm, hole diameter 8 mm:

• A circle of diameter 100 on layer CENTRE-LINE (red, CENTER linetype)
• Six circles of diameter 8, evenly spaced, on layer OBJECT (white)
• A small cross at the main centre point on layer CENTRE-LINE
• A short centre cross inside each hole

Every element lands on the right layer automatically — no manual layer switching needed.

Full code

Create a new class file in your project and paste this in:

using System;
using Autodesk.AutoCAD.ApplicationServices;
using Autodesk.AutoCAD.Colors;
using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.EditorInput;
using Autodesk.AutoCAD.Geometry;
using Autodesk.AutoCAD.Runtime;

[assembly: CommandClass(typeof(KleverCAD.BoltHoleCommand))]

namespace KleverCAD
{
    public class BoltHoleCommand
    {
        // ── Layer names ────────────────────────────────────────────────────────
        // Keeping them as constants means a typo shows up at compile time,
        // not as a silent wrong-layer bug at runtime.
        private const string LayerObject     = "OBJECT";
        private const string LayerCentreLine = "CENTRE-LINE";

        /// <summary>
        /// BOLTHOLES command — draws a bolt hole pattern from user input.
        ///
        /// Workflow:
        ///   1. User picks the centre point
        ///   2. User enters the PCD (pitch circle diameter)
        ///   3. User enters the number of holes
        ///   4. User enters the hole diameter
        ///   5. Command draws the pattern and reports back
        ///
        /// Pressing Escape at any prompt cancels cleanly — nothing is drawn.
        /// </summary>
        [CommandMethod("BOLTHOLES")]
        public void DrawBoltHoles()
        {
            Document doc = Application.DocumentManager.MdiActiveDocument;
            Database db  = doc.Database;
            Editor   ed  = doc.Editor;

            // ── Step 1: centre point ───────────────────────────────────────────
            PromptPointOptions centerOpt = new PromptPointOptions(
                "\nPick bolt pattern centre: ");

            PromptPointResult centerRes = ed.GetPoint(centerOpt);
            if (centerRes.Status != PromptStatus.OK) return; // user pressed Escape
            Point3d center = centerRes.Value;

            // ── Step 2: pitch circle diameter (PCD) ───────────────────────────
            // GetDistance asks the user to type a value or pick two points.
            // UseBasePoint + BasePoint draws a rubber-band line from the centre
            // so the user can visually pick the PCD radius directly in the drawing.
            PromptDistanceOptions pcdOpt = new PromptDistanceOptions(
                "\nPitch circle diameter (PCD): ");
            pcdOpt.BasePoint    = center;
            pcdOpt.UseBasePoint = true;
            pcdOpt.AllowNegative = false;
            pcdOpt.AllowZero     = false;

            PromptDoubleResult pcdRes = ed.GetDistance(pcdOpt);
            if (pcdRes.Status != PromptStatus.OK) return;

            // GetDistance returns the distance (= radius when picking from centre).
            // We stored PCD as diameter so the user can type "100" for a 100 mm PCD.
            // When picking visually the user picks the radius, so we double it.
            double pcdRadius = pcdRes.Value; // treat picked value as radius
            double pcd       = pcdRadius * 2;

            // ── Step 3: number of holes ────────────────────────────────────────
            PromptIntegerOptions countOpt = new PromptIntegerOptions(
                "\nNumber of holes: ");
            countOpt.AllowNegative = false;
            countOpt.AllowZero     = false;
            countOpt.LowerLimit    = 2; // a 1-hole "pattern" isn't a pattern

            PromptIntegerResult countRes = ed.GetInteger(countOpt);
            if (countRes.Status != PromptStatus.OK) return;
            int numHoles = countRes.Value;

            // ── Step 4: hole diameter ──────────────────────────────────────────
            PromptDistanceOptions holeOpt = new PromptDistanceOptions(
                "\nHole diameter: ");
            holeOpt.AllowNegative = false;
            holeOpt.AllowZero     = false;

            PromptDoubleResult holeRes = ed.GetDistance(holeOpt);
            if (holeRes.Status != PromptStatus.OK) return;
            double holeDiameter = holeRes.Value;
            double holeRadius   = holeDiameter / 2.0;

            // ── Step 5: draw everything inside a transaction ───────────────────
            using (Transaction tr = db.TransactionManager.StartTransaction())
            {
                // Ensure our layers exist before drawing on them.
                // The helper creates the layer if missing, or reuses it if it's there.
                EnsureLayer(tr, db, LayerObject,     colorIndex: 7,  linetype: "Continuous");
                EnsureLayer(tr, db, LayerCentreLine, colorIndex: 1,  linetype: "CENTER");

                // Get the current model space block so we can add entities
                BlockTableRecord modelSpace = GetModelSpace(tr, db);

                // Draw the pitch circle (the circle all hole centres sit on)
                DrawCircle(tr, modelSpace, center, pcdRadius, LayerCentreLine);

                // Draw a cross mark at the main centre
                DrawCentreCross(tr, modelSpace, center, pcdRadius * 0.08, LayerCentreLine);

                // Draw each bolt hole, equally spaced around the pitch circle
                // angleStep = full circle (2π radians) divided by number of holes
                // We start at 90° (top of circle) which is conventional for bolt patterns
                double angleStep  = (2 * Math.PI) / numHoles;
                double startAngle = Math.PI / 2.0; // 90° = top

                for (int i = 0; i < numHoles; i++)
                {
                    double angle = startAngle + (i * angleStep);

                    // Convert polar coordinates (angle + radius) to Cartesian (x, y)
                    double x = center.X + pcdRadius * Math.Cos(angle);
                    double y = center.Y + pcdRadius * Math.Sin(angle);
                    Point3d holeCenter = new Point3d(x, y, center.Z);

                    // Draw the hole circle
                    DrawCircle(tr, modelSpace, holeCenter, holeRadius, LayerObject);

                    // Draw a small centre cross inside the hole
                    DrawCentreCross(tr, modelSpace, holeCenter, holeRadius * 0.4, LayerCentreLine);
                }

                tr.Commit(); // nothing is saved to the drawing until this line
            }

            // Report back in the command line
            ed.WriteMessage(
                $"\nBolt pattern drawn: {numHoles}× Ø{holeDiameter:F1} on PCD Ø{pcd:F1}");
        }

        // ── Helper: draw a circle ──────────────────────────────────────────────

        private static void DrawCircle(
            Transaction tr, BlockTableRecord btr,
            Point3d center, double radius, string layer)
        {
            Circle c = new Circle();
            c.Center = center;
            c.Radius = radius;
            c.Layer  = layer;

            btr.AppendEntity(c);
            tr.AddNewlyCreatedDBObject(c, true);
        }

        // ── Helper: draw a + cross mark (two short lines) ─────────────────────
        // Used for the main centre mark and the hole centre marks.
        // halfSize controls how long each arm of the cross is.

        private static void DrawCentreCross(
            Transaction tr, BlockTableRecord btr,
            Point3d center, double halfSize, string layer)
        {
            // Horizontal line
            Line h = new Line(
                new Point3d(center.X - halfSize, center.Y, center.Z),
                new Point3d(center.X + halfSize, center.Y, center.Z));
            h.Layer = layer;
            btr.AppendEntity(h);
            tr.AddNewlyCreatedDBObject(h, true);

            // Vertical line
            Line v = new Line(
                new Point3d(center.X, center.Y - halfSize, center.Z),
                new Point3d(center.X, center.Y + halfSize, center.Z));
            v.Layer = layer;
            btr.AppendEntity(v);
            tr.AddNewlyCreatedDBObject(v, true);
        }

        // ── Helper: create a layer if it doesn't already exist ────────────────
        // colorIndex follows AutoCAD's index colour system (1=red, 7=white/black).
        // linetype is the AutoCAD linetype name ("Continuous", "CENTER", "HIDDEN", etc.)
        // The linetype must already be loaded in the drawing — CENTER is loaded by default.

        private static void EnsureLayer(
            Transaction tr, Database db,
            string name, short colorIndex, string linetype)
        {
            LayerTable lt = (LayerTable)tr.GetObject(
                db.LayerTableId, OpenMode.ForRead);

            if (lt.Has(name))
                return; // layer already exists — nothing to do

            // Layer doesn't exist yet — create it
            lt.UpgradeOpen(); // switch from read to write

            LayerTableRecord ltr = new LayerTableRecord();
            ltr.Name  = name;
            ltr.Color = Color.FromColorIndex(ColorMethod.ByAci, colorIndex);

            // Load and assign the linetype
            // LinetypeTable lookup returns the ID we pass to the layer
            LinetypeTable ltt = (LinetypeTable)tr.GetObject(
                db.LinetypeTableId, OpenMode.ForRead);

            if (ltt.Has(linetype))
                ltr.LinetypeObjectId = ltt[linetype];
            // If linetype isn't loaded, the layer defaults to Continuous — safe fallback

            lt.Add(ltr);
            tr.AddNewlyCreatedDBObject(ltr, true);
        }

        // ── Helper: get model space block table record ─────────────────────────

        private static BlockTableRecord GetModelSpace(Transaction tr, Database db)
        {
            BlockTable bt = (BlockTable)tr.GetObject(
                db.BlockTableId, OpenMode.ForRead);

            return (BlockTableRecord)tr.GetObject(
                bt[BlockTableRecord.ModelSpace], OpenMode.ForWrite);
        }
    }
}

Code walkthrough — line by line

The using statements

using Autodesk.AutoCAD.ApplicationServices;  // gives us: Application, Document
using Autodesk.AutoCAD.Colors;               // gives us: Color (for layer colours)
using Autodesk.AutoCAD.DatabaseServices;     // gives us: Database, Transaction, Circle, Line, LayerTable...
using Autodesk.AutoCAD.EditorInput;          // gives us: Editor, PromptPointOptions, PromptDistanceOptions...
using Autodesk.AutoCAD.Geometry;             // gives us: Point3d, Vector3d
using Autodesk.AutoCAD.Runtime;              // gives us: CommandMethod attribute

Each using line imports a namespace from the AutoCAD .NET API. Think of them as sections of the API toolbox — DatabaseServices is where all the drawing objects live, EditorInput is everything related to the command line and user prompts, and Geometry is all the maths types (points, vectors).

Registering the command

[assembly: CommandClass(typeof(KleverCAD.BoltHoleCommand))]

This line tells AutoCAD "look inside BoltHoleCommand for methods marked with [CommandMethod]". Without it, AutoCAD won't find your command even if the DLL is loaded. It goes outside the namespace, at the top of the file.

Layer name constants

private const string LayerObject     = "OBJECT";
private const string LayerCentreLine = "CENTRE-LINE";

Storing layer names as constants instead of typing the string every time means a typo will be caught by the compiler rather than silently drawing on the wrong layer. Change the name in one place and every reference updates automatically.

The three objects you always need

Document doc = Application.DocumentManager.MdiActiveDocument;
Database db  = doc.Database;
Editor   ed  = doc.Editor;

doc is the currently open drawing file. db is the drawing's database — all entities (lines, circles, layers) live here. ed is the command line and user input interface. These three lines appear at the start of almost every AutoCAD command you'll ever write.

Prompting for a point

PromptPointOptions centerOpt = new PromptPointOptions("\nPick bolt pattern centre: ");
PromptPointResult  centerRes = ed.GetPoint(centerOpt);
if (centerRes.Status != PromptStatus.OK) return;
Point3d center = centerRes.Value;

PromptPointOptions configures what the prompt looks like. The \n at the start moves it to a new line in the command window — without it, the text runs onto the previous line. ed.GetPoint() pauses the command and waits for the user to click or type coordinates. The result comes back with a Status — if it's anything other than OK (e.g. the user pressed Escape), we return immediately. Nothing has been drawn yet so there's nothing to undo.

Prompting for a distance with a rubber-band line

PromptDistanceOptions pcdOpt = new PromptDistanceOptions("\nPitch circle diameter (PCD): ");
pcdOpt.BasePoint    = center;
pcdOpt.UseBasePoint = true;
pcdOpt.AllowNegative = false;
pcdOpt.AllowZero     = false;

Setting BasePoint and UseBasePoint = true makes AutoCAD draw a rubber-band line from the centre while the user moves the mouse — the same visual feedback you get when drawing a circle. AllowNegative and AllowZero prevent nonsense inputs from crashing the command later.

Prompting for an integer with limits

PromptIntegerOptions countOpt = new PromptIntegerOptions("\nNumber of holes: ");
countOpt.LowerLimit = 2;

LowerLimit = 2 means AutoCAD itself will reject anything below 2 and show an error message — you don't have to write that validation yourself. The API handles it before the result even reaches your code.

Opening a transaction

using (Transaction tr = db.TransactionManager.StartTransaction())
{
    // ... all drawing code here ...
    tr.Commit();
}

A transaction is a protective envelope around all your drawing operations. Nothing is permanently written to the drawing until tr.Commit() is called. If an exception is thrown before that, the transaction rolls back automatically and the drawing is left untouched. The using statement ensures the transaction is always closed, even if an error occurs.

Creating layers with EnsureLayer

EnsureLayer(tr, db, LayerObject,     colorIndex: 7, linetype: "Continuous");
EnsureLayer(tr, db, LayerCentreLine, colorIndex: 1, linetype: "CENTER");

This calls our helper which first checks whether the layer already exists. If the user runs BOLTHOLES twice, the layers are already there — no error, no duplicate. Colour index 1 = red, 7 = white (or black on a white background). The CENTER linetype gives the pitch circle its dashed appearance.

Getting model space

BlockTableRecord modelSpace = GetModelSpace(tr, db);

In AutoCAD, model space is technically a special block — a container that holds all the entities in your drawing. To add anything to the drawing you need to open that block for writing. The helper does this in two steps: open the BlockTable (the list of all blocks), then open the ModelSpace entry from it.

The bolt hole loop

double angleStep  = (2 * Math.PI) / numHoles;  // full circle ÷ number of holes
double startAngle = Math.PI / 2.0;              // start at 90° (top)

for (int i = 0; i < numHoles; i++)
{
    double angle = startAngle + (i * angleStep);
    double x = center.X + pcdRadius * Math.Cos(angle);
    double y = center.Y + pcdRadius * Math.Sin(angle);
    Point3d holeCenter = new Point3d(x, y, center.Z);
    ...
}

2 * Math.PI is a full circle in radians (360°). Dividing by the number of holes gives the angle between each hole. Math.Cos and Math.Sin convert that angle into an X and Y offset from the centre — this is standard polar-to-Cartesian conversion. The Z coordinate stays the same as the centre so the pattern stays flat in the current plane.

Adding an entity to the drawing

Circle c = new Circle();
c.Center = center;
c.Radius = radius;
c.Layer  = layer;
btr.AppendEntity(c);
tr.AddNewlyCreatedDBObject(c, true);

Creating a Circle object in C# doesn't add it to the drawing — it's just a C# object in memory. btr.AppendEntity(c) adds it to model space. tr.AddNewlyCreatedDBObject(c, true) registers it with the transaction so it's properly tracked and committed. Both lines are always required — skip either one and the entity either won't appear or will leak memory.

Reporting back to the user

ed.WriteMessage($"\nBolt pattern drawn: {numHoles}× Ø{holeDiameter:F1} on PCD Ø{pcd:F1}");

This writes a confirmation message to the AutoCAD command line. :F1 formats the number to one decimal place — so 8.0 instead of 8.000000001 due to floating point. The Ø character is the diameter symbol. A small touch, but it makes the command feel professional.

How the maths works

The key line is this one inside the loop:

double x = center.X + pcdRadius * Math.Cos(angle);
double y = center.Y + pcdRadius * Math.Sin(angle);

This converts polar coordinates — a distance from the centre (pcdRadius) and an angle — into the Cartesian X/Y coordinates AutoCAD needs. For a 6-hole pattern the angles are 90°, 150°, 210°, 270°, 330° and 30° — equally spaced at 60° apart. For an 8-hole pattern they'd be 45° apart. The formula works for any number of holes.

Starting at 90° (top) rather than 0° (right) is a convention in mechanical drawing — the first hole lands at the top of the pattern, which is easier to dimension and looks cleaner on a drawing.

Why transactions matter

Everything in the code above runs inside a single using (Transaction tr = ...) block. This is not optional — it's how the AutoCAD database works. Until tr.Commit() is called, nothing is saved to the drawing. If an error occurs or the user force-quits before commit, the drawing is left exactly as it was. This is the same as a database transaction in SQL — all-or-nothing.

Try extending it

Once this is working, here are natural next steps to make it production-ready:

• Ask for a start angle — add a GetAngle() prompt so the user can rotate the pattern
• Add a MText label — write "6× Ø8 ON PCD Ø100" as a text entity below the pattern
• Support HIDDEN linetype — for hidden-line holes in a side view, add a layer HIDDEN and draw the holes there when the user picks "side view mode"
• Read from a table — load standard bolt sizes from an Excel or CSV file so the user picks M6, M8, M10 instead of typing a diameter

What's next in this course

Next lesson: working with blocks and attributes — how to insert a title block, fill in the attribute fields (drawing number, revision, scale) from code, and export the values to a spreadsheet.

The full C# for AutoCAD course is available to Standard and Full Access subscribers in the E-Learning section.