autocad® .net basics · related) api was very limited - only allowing the creation of very simple...

20
12/3/2008 - 10:15 am - 11:45 am Room:San Polo 3404 (MSD) AutoCAD® .NET Basics Wondering what all the hype is around .NET? We'll give you the basic information you need to get up to speed on writing your own .NET applications based on the AutoCAD .NET application programming interface (API). This foundation class includes: an overview of the .NET Framework and what is means for programmers; how to write your first AutoCAD .NET add-in; simple user interaction; a discussion of the structure of the DWG™ database; how to add CAD entities to the DWG database; and how to traverse the entities already in the DWG. Make sure you also sign up for our "AutoCAD .NET: A Tour" class if you attend this. DE205-4 About the Speaker: Stephen Preston - Americas Manager, Developer Technical Services, Autodesk Stephen has been a member of the Autodesk Developer Technical Services Team since 2000, first as a support engineer and then as manager of the EMEA (Europe, Middle East, and Africa) Team. In those roles, his responsibilities included support for the AutoCAD® APIs, including ObjectARX® and AutoCAD .NET, as well as AutoCAD OEM and RealDWG™ technologies. Currently, he manages the Developer Technical Services Team in the Americas and serves as Workgroup Lead, working closely with the AutoCAD engineering team on future improvements in the AutoCAD APIs. Stephen started his career as a scientist, and has a Ph.D in Atomic and Laser Physics from the University of Oxford. Stay Connect with AU all year at www.autodeskuniversity.com r

Upload: others

Post on 07-Jan-2020

12 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

12/3/2008 - 10:15 am - 11:45 am Room:San Polo 3404 (MSD)

AutoCAD® .NET Basics

Wondering what all the hype is around .NET? We'll give you the basic information you need to get up to speed on writing your own .NET applications based on the AutoCAD .NET application programming interface (API). This foundation class includes: an overview of the .NET Framework and what is means for programmers; how to write your first AutoCAD .NET add-in; simple user interaction; a discussion of the structure of the DWG™ database; how to add CAD entities to the DWG database; and how to traverse the entities already in the DWG. Make sure you also sign up for our "AutoCAD .NET: A Tour" class if you attend this.

DE205-4

About the Speaker:

Stephen Preston - Americas Manager, Developer Technical Services, Autodesk

Stephen has been a member of the Autodesk Developer Technical Services Team since 2000, first as a support engineer and then as manager of the EMEA (Europe, Middle East, and Africa) Team. In those roles, his responsibilities included support for the AutoCAD® APIs, including ObjectARX® and AutoCAD .NET, as well as AutoCAD OEM and RealDWG™ technologies. Currently, he manages the Developer Technical Services Team in the Americas and serves as Workgroup Lead, working closely with the AutoCAD engineering team on future improvements in the AutoCAD APIs. Stephen started his career as a scientist, and has a Ph.D in Atomic and Laser Physics from the University of Oxford.

Stay Connect with AU all year at www.autodeskuniversity.comr

Page 2: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there
Page 3: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

3

AutoCAD®�.NET�Basics�

What�this�seminar�is�(and�what�it�isn’t)�AutoCAD .NET Basics is an introduction to the AutoCAD .NET API. The class is intended to

form a ‘foundation’ for the other .NET seminars being delivered by the Autodesk Developer

Network team. These are:

DE305-3 – AutoCAD® .NET: A Tour

DE315-2 – AutoCAD® .NET: Developing a User Interface

DE401-1 – AutoCAD® .NET: Using .NET with your LISP Applications

This is not a beginner’s class on programming. The seminar assumes that you have a basic

understanding of simple programming concepts (including the basics of .NET programming),

and that you are familiar with AutoCAD. It is assumed that you have never before used the

AutoCAD .NET API1.

If you’ve never programmed before, then you’re probably better signing up for a hands on class

to get you started. Or sign up for DE305-3 – AutoCAD® .NET: A Tour if you want a high-altitude

fly-past of the capabilities of the AutoCAD .NET API.

A�very�brief�history�of�the�AutoCAD.NET�API�The first version of the AutoCAD .NET API (sometimes called ‘ObjectARX .NET’ or ‘Managed

ObjectARX’) was released with AutoCAD 2005. Before then, use of the .NET Framework with

AutoCAD was restricted to automating AutoCAD from an external .NET application through

COM Interop. Using COM Interop is really just using .NET as a glorified VB6 application, and is

very different from native .NET programming.

The AutoCAD 2005 .NET API was a preview version. It did include the classes required to

access the DWG Database and all the objects in that Database, but the ‘editor’ (or non-DWG-

related) API was very limited - only allowing the creation of very simple commands.

AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there were a few

architectural changes to allow greater flexibility. The main change was the introduction of

Transactions as the primary means of modifying the DWG Database. (The 2005 API relied on

the Open/Close model favored by ObjectARX2 programmers). The 2006 API release completed

the DWG Database access functionality (adding a few classes for AutoCAD entities that were

1 A note to beginners – ‘API’ means ‘Application Programming Interface’. That’s the set of functions

AutoCAD exposes for you to use in your application to make AutoCAD do what you want.

2 The AutoCAD .NET API is a wrapper on top of the (unmanaged) C++ ObjectARX API. ObjectARX

programmers have a big advantage over VB or LISP programmers, because the AutoCAD .NET Object

Model is based on ObjectARX.

Page 4: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

4

missing from the 2005 release), and adding lots of ‘Editor’ functionality (such as

InputPointMonitors, SelectionSets, advanced command line interaction, etc.) and a

comprehensive Event model.

Since the AutoCAD 2006 release, the .NET API architecture has remained unchanged.

Changes since then have been in adding new APIs corresponding to new product features. In

fact, some AutoCAD APIs (the CUI API, for example) are only available as .NET APIs.

However, the 2007 API did take advantage of AutoCAD 2007 being a ‘binary incompatible’

release to move from .NET Framework 1.1 to .NET Framework 2. As the API now uses features

introduced in Framework 2, it is no longer possible to develop AutoCAD .NET applications using

an IDE that relies on older .NET Frameworks3.

A�Hello�World�tutorial�As you’re really keen to learn the AutoCAD .NET API, you’ll have picked up this handout when

you arrived at AU, and you’re now sitting in your hotel room with your laptop, ready to fire up

Visual Studio 20054 to get ahead of the game before the seminar. So go on then – double-click

that squirly icon and get programming. You know you want to!

If you’ve ever been subjected to a ‘learn to program’ tutorial before, you’ll know that every

beginner’s tutorial in the world starts with a ‘Hello World’ project. So who are we to break with

decades of tradition? …

Once Visual Studio has started, you need to create a new project. Go to the File menu and

select New->Project….

Unsurprisingly, this displays the New Project dialog.

We’re going to create a small VB.NET project. The steps are pretty much the same for C#; it’s

just the C# syntax around the AutoCAD API calls that differs. We’ll show a C# project in the

class.

3 . For Visual Studio, this means version 2005 or higher is needed.

4 You don’t have to buy Visual Studio to write your AutoCAD .NET add-ins. There are a number of free

development environments available. For example, you can use Visual Studio Express, but you have to

tweak it a little to get it to work – see Kean Walmsley’s blog posting for details (http://through-the-

interface.typepad.com/through_the_interface/2006/07/debugging_using.html).

Page 5: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

5

Click on the Visual Basic project type and select the Class Library Template. Then give the

project a name. You can call it anything you like, but (being a slave to tradition) I’m going to call

it ‘HelloWorld’.

When you’ve done that, click OK.

Now open the Solution Explorer window (the View->Solution Explorer menu item) if it’s not

already open; double click on My Project; and select the References tab.

Page 6: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

6

Click the Add button, select the Browse tab; navigate to C:\Program Files\AutoCAD 2009 (or

wherever your AutoCAD is installed), and search for *mgd.dll (i.e. type *mgd.dll in the File nametextbox and click OK).

This will display all the files in that folder ending with ‘mgd.dll’.

Now select acmgd.dll and acdbmgd.dll by Ctrl-clicking on them both; then click OK. These are

the two DLLs that expose the AutoCAD .NET API.

acmgd.dll exposes all the Editor functionality (SelectionSets, Commands and Keywords,

Prompts and Dialogs, etc.);

acdbmgd.dll exposes all the Database access functionality (the DWG Database itself,

Lines, Circles, MText, etc.).

Page 7: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

7

Back on the My Project screen References tab, double-click on acdbmgd.dll to display its

Properties, and set Copy Local to False. (This is to ensure your .NET add-in loads the copy of

acdbmgd.dll stored in the AutoCAD folder and doesn’t try to make and load a local copy. You

probably guessed that from the property name).

Then do the same for acmgd.dll.

Now we want to write our code. Double-click on ‘Class1.vb in the Solution Explorer window.

This is where you write your add-in code. Edit the template code as follows:

Imports Autodesk.AutoCAD.Runtime Imports Autodesk.AutoCAD.ApplicationServices Imports Autodesk.AutoCAD.DatabaseServices

Public Class Class1

<CommandMethod("HelloWorld")> _ Public Sub MyMethod()

Application.ShowAlertDialog("Hello World from VB.NET!")End Sub

End Class

The Imports statements allow you to use classes from the namespaces you import without

having to type out the full namespace. You don’t strictly need them, but the code becomes hard

to read otherwise. For example,

Application.ShowAlertDialog("Hello World from VB.NET!")

becomes

Page 8: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

8

Autodesk.AutoCAD.ApplicationServices.Application.ShowAlertDialog("HelloWorld from VB.NET!")

There are several other Autodesk.AutoCAD namespaces, but these are the three you’ll need in

just about every AutoCAD add-in you write. (In this example, DatabaseServices is not strictly

necessary).

<CommandMethod("HelloWorld")> is an attribute. This is telling AutoCAD to run the

subroutine MyMethod when the user types HELLOWORLD on the command line. The rest of

the code should be self-explanatory.

That’s all the code we need. But before we can test our first AutoCAD add-in we have to set one

more project setting. Double-click again on My Project in the Solution Explorer; select the

Debug tab; set the Start Action to Start external program; and enter the location of the AutoCAD

executable – the default location is C:\Program Files\AutoCAD 2009\acad.exe. This is telling

Visual Studio that you’re going to load your DLL into the AutoCAD process space to debug it5.

Now we’re ready to run our add-in. Hit F5 to start debugging, and AutoCAD will launch. Type

NETLOAD on the command line and hit ENTER. In the NETLOAD file select dialog, navigate to

the location of your compiled .NET assembly DLL. This should be in this location, unless you

changed your default project settings:

5 The AutoCAD .NET API can only be used from inside the AutoCAD process space. You can’t use

admgd.dll and acdbmgd.dll in a standalone executable. (But see the section on RealDWG at the end of

this document).

Page 9: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

9

The assembly DLL is called HelloWorld.dll. Double-click on it to load it.

Now type HELLOWORLD at the command line, and AutoCAD will display this dialog.

Congratulations! You’ve just created your first custom command using AutoCAD .NET.

But let’s not stop just yet. Switch back to Visual Studio and hit Shift+F5 to stop the debugging

session, open up Class1.vb by double-clicking on it in the Solution Explorer, and replace all the

code in that document with this:

Imports Autodesk.AutoCAD.Runtime Imports Autodesk.AutoCAD.ApplicationServices Imports Autodesk.AutoCAD.DatabaseServices

Public Class Class1

<CommandMethod("HelloWorld")> _ Public Sub MyMethod()

' Some variable definitions Dim activeDoc As Document Dim BTR As BlockTableRecord

' Store a reference to the currently active document (to make the next two lines of code shorter) activeDoc = Application.DocumentManager.MdiActiveDocument

' Start a transaction to edit the DWG database Using trans As Transaction =

activeDoc.TransactionManager.StartTransaction()

' Open BlockTableRecord of currently active space ready to add entity.

' (This will be ModelSpace if you've not switched to a layout, otherwise PaperSpace). BTR = trans.GetObject(activeDoc.Database.CurrentSpaceId, OpenMode.ForWrite)

' Create a new MText entity and set its text Dim txt As MText = New MText

txt.Contents = "Hello World from VB.NET!"

' Add the MText to ModelSpace BTR.AppendEntity(txt) txt.SetDatabaseDefaults()

Page 10: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

10

' Add the Mtext to the transaction trans.AddNewlyCreatedDBObject(txt, True)

' Commit transaction so changes persist in the DWG Database. trans.Commit()

End Using

End Sub

End Class

Now hit F5 again; NETLOAD the HelloWorld.dll; and invoke the HELLOWORLD command

again. ZOOM EXTENTS and you should see this:

Give yourself a big hug – you’ve just created your first drawing using VB.NET!

The�DWG�Database�format�So now we’ve worked through the ubiquitous ‘Hello World’ tutorial. We ended up waving a

magic wand to add some MText to ModelSpace. That was our first glimpse of the DWG

Database structure, which is the most important part of the AutoCAD .NET object model to

learn. You will never understand the ObjectARX or AutoCAD .NET API until you understand the

DWG Database structure. It’s as simple as that. So let’s take a look at it now.

The DWG Database is not that different to any other database (an MS Access database, for

example). If you’ve ever done any database programming, then you’re halfway there already.

Page 11: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

11

Like any database, the DWG Database consists of a number of tables in which are stored

records. For example, an MS Access database might contain a table of employees (let’s call it

the EmployeeTable), which might contain a record for each Employee (an

EmployeeTableRecord). Like this -

In the same way, most of the information in a DWG Database is stored in SymbolTables as

SymbolTableRecords. We have several types of Symbol in AutoCAD, such as Blocks,

Dimension Styles, Layers, LineTypes, UCSs, Views, Viewports, and Registered Applications

(used for storing Xdata). Each of these SymbolTables stores a different type of

SymbolTableRecord.

The most important aspect of a CAD application is to be able to draw something, so let’s

concentrate on how AutoCAD stores its graphical Entities6 (Lines, Circles, Polylines, etc) you

draw on-screen. Graphical Entities are always stored in (or are owned by) a BlockTableRecord.

Think of a BlockTableRecord as containing all the Entities that make up the definition of a Block.

But just to complicate things, ModelSpace and PaperSpace are also represented in the DWG

Database by BlockTableRecords. This makes sense if you think about it - Block definitions and

ModelSpace both just store a bunch of graphical Entities. The only difference is that you have a

window to look into the ModelSpace and PaperSpace BlockTableRecords – the drawing

document. To view other BlockTableRecords, you have to insert a BlockReference into

ModelSpace or PaperSpace.

And, of course, all the BlockTableRecords are stored in the BlockTable.

Below is a screenshot from the Inspector DWG Database viewing utility7, with the tree expanded

to show some BlockTableRecords and LinetypeTableRecords. Note the names of the

BlockTableRecords in the BlockTable shown on the left screenshot – they include Model_Spaceand Paper_Space. The right-hand screenshot expands the ModelSpace BlockTableRecord to

show the Entities it contains (two Lines, a Circle and a Polyline in this case). Don’t worry about

the AcDb prefix on the class names for now.

6 Entity has a special meaning in AutoCAD. This is the name given to anything in the DWG Database that

is represented graphically. More generally, we use the word Object (or the DBObject class) to describe

anything in the database – that includes both Entities and non-graphical objects.

7 Available as an ObjectARX sample on the ADN website.

Page 12: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

12

There’s a little more to the DWG Database than just Tables. Notice the Named Objects Dictionary and Extension Dictionary shown in the Inspector tree. These are used for storing data

in the DWG, but are outside the scope of this introductory class.

Transactions�Continuing with our database theme, it shouldn’t come as a surprise that we have a similar

mechanism for modifying the DWG Database as for modifying a relational database – we use

Transactions.

The concept of a transaction is simple. Any changes you make within a transaction are only

committed to the database when the transaction is committed. If anything goes wrong while

you’re modifying the database within a transaction, then you simply abort the transaction and

the database is returned to the state it was in before the transaction started. This is shown in the

simple flow diagram below.

Page 13: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

13

Unique�Identifiers�As for any database, it’s very important to be able to identify each object stored in the DWG

database. Without some kind of unique identifier, there would be no way to distinguish (for

example) one red circle from the other red circles in the drawing. When you add an object to the

DWG Database, it is assigned two unique identifiers – a Handle and an ObjectID.

Handles�A Handle is unique within a drawing, but is not unique across all the drawings open in a session.

This means that two objects in two different drawings can have the same Handle. (Although

combining the Handle with the drawing pathname would be unique).

Handles are saved with the drawing. When you save and reopen a drawing, each object will

have the same handle as it did last time. The only time an object’s handle will change is if you

INSERT the object into a new drawing – then the Handles have to change to avoid clashes with

the Handles in the drawing you’re INSERTing into.

The .NET DBObject class – the parent class for all objects that can be stored in the DWG

database – exposes a Handle property, which is inherited by all the classes that derive from it.

ObjectIds�Like a Handle, an ObjectId is unique within a drawing. But an ObjectId is also unique within an

AutoCAD session. No matter how many drawings you open in one session, you’ll never see the

same ObjectId.

Unlike a Handle, the ObjectId isn’t saved with the drawing, So when you close and reopen a

drawing, the objects in it will most likely have different ObjectIds. AutoCAD uses ObjectIds to

track relationships between objects in a drawing. But when AutoCAD saves these relationships

in the DWG file, it translates them to handles.

The DBObject class exposes an ObjectId property. You will mostly be using ObjectIds (rather

than handles) in your .NET applications.

The following table summarizes the similarities differences between Handles and ObjectIds.

Handle ObjectId

Unique in DWG Yes Yes

Unique in session No Yes

Saved with DWG Yes No

To find the ObjectId of an object you have the handle for, you can call the

Database.GetObjectId() function.

Page 14: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

14

To find the Handle of an object you have an ObjectId for, you can open the object using its

ObjectId and then call the DBObject.GetHandle() function.

Hello�World�again�Now we’ve covered the basics of the DWG Database structure, Transactions, and ObjectIds,

let’s walk through the code for the Hello World MText example we used earlier, starting just after

the variable declarations in the function …

First we store a reference to the active document. This is just for convenience, so we don’t have

to write Application.DocumentManager.MdiActiveDocument twice.

activeDoc = Application.DocumentManager.MdiActiveDocument

Before we can access the Database, we have to start a new transaction. We start a transaction

from the TransactionManager, which is accessed through a property of the Document.

Using trans As Transaction = activeDoc.TransactionManager.StartTransaction()

The Using keyword tells the .NET runtime to Dispose of the Transaction (trans) once the

program flow has moved beyond the End Using statement. This just helps us to clean up after

ourselves. (Otherwise, we’d have to explicitly call the Transactions Dispose function when we’d

finished with it).

To add an Entity to the currently active space (ModelSpace or PaperSpace), we ask the

transaction to open the BlockTableRecord for the current space. We access the ObjectID of the

current space using the CurrentSpaceId property of the Database, and pass it to the

GetObject() method of the Transaction. Like in any database, we have a choice of opening the

table for Write if we’re planning on adding or removing any records, or for Read if we’re only

interested in querying the contents. In this case, we’re planning to add some Mtext to the

BlockTableRecord, so we open it for Write.

BTR = trans.GetObject(activeDoc.Database.CurrentSpaceId, OpenMode.ForWrite)

There is an alternative to using the CurrentSpaceId property. We’ll mention it here for

completeness, and because it ties in with our earlier discussion of the database structure …

To add an Entity to ModelSpace, we can work down the structure of the Database. First we

need to access the Database for the currently active AutoCAD DWG document. That’s this line

of code

DB = Application.DocumentManager.MdiActiveDocument.Database

Page 15: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

15

Next we open the BlockTable. We open it inside the transaction using the

Transaction.GetObject() method. (The ObjectId for the BlockTable is returned by the

BlockTableId property).

BT = trans.GetObject(DB.BlockTableId, OpenMode.ForRead)

Then we open the ModelSpace BlockTable Record (again using the transaction)

MS = trans.GetObject(BT(BlockTableRecord.ModelSpace),OpenMode.ForWrite)

This looks a bit funny, because the BlockTable class is a collection of BlockTableRecords.

BlockTableRecord.ModelSpace is a pre-defined constant that returns the name of the

ModelSpace BlockTableRecord. If we’d wanted the BlockTableRecord defining Block_A, we’d

have called BT(“Block_A”). And notice that we’re opening the ModelSpace BlockTableRecord

for Write – that’s because we’re planning on adding some MText to ModelSpace.

Next we create a new instance of an MText Entity, set it’s contents to the text we want to

display, and add it to the current space. The commented code is pretty obvious here. The

SetDatabaseDefaults simply sets the textstyle etc. of the text to the default for this drawing.

' Create a new MText entity and set its text Dim txt As MText = New MText

txt.Contents = "Hello World from VB.NET!"

' Add the MText to ModelSpace BTR.AppendEntity(txt) txt.SetDatabaseDefaults()

The next part isn’t quite so obvious …

' Add the MText to the transaction trans.AddNewlyCreatedDBObject(txt, True)

We’ve created a new MText instance and added it to ModelSpace, so we need to let the

Transaction know about that change. That’s how we can make sure the MText is removed from

the Database if the Transaction is aborted, or permanently added if the Transaction is

committed. You have to notify the Transaction like this every time you add something new to the

DWG Database.

Finally, we commit the Transaction. If we get to this line of code, then everything worked fine

and there were no errors. Committing the Transaction makes our changes permanent and tidies

up after us (closing everything that we opened).

' Commit transaction so changes persist in the DWG Database. trans.Commit()

By the way, I’ve not put any error handling in this simple code. Error handling is a very important

part of .NET, and we will cover that briefly in the seminar.

Page 16: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

16

Navigating�the�AutoCAD�.NET�Object�Model�By now, you’ll be starting to grasp what’s needed to add stuff to your drawings. The AutoCAD

.NET API exposes a number of namespaces (some of which we touched on briefly already

when we introduced the Imports keyword). These namespaces hold the classes you need to

work with AutoCAD. Let’s take a quick look at how you can find out the classes and functions

available to you. We’ll focus here on the Autodesk.AutoCAD.DatabaseServices namespace,

because (as its name suggests) that’s the namespace that stores the .NET classes used to

access the DWG Database. What follows assumes knowledge of basic Object-Oriented

programming concepts8, particularly inheritance.

A good way to view the classes available in a namespace is to use the Visual Studio ObjectBrowser (the View->Object Browser menu item).

If you open the Object Browser for the Hello World application we created in our first handout

(or any AutoCAD .NET add-in project), then you can expand the acdbmgd assembly to see the

namespaces it contains.

Now expand the DatabaseServices namespace in the Object Browser, scroll down to the MTextclass and expand the tree below it as far as DBObject. Do the same with Line.

8 See (for example) http://en.wikipedia.org/wiki/Object-oriented_programming for an overview of this.

Page 17: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

17

Expanding the tree in this way exposes the inheritance hierarchy of that class9. We can see that

MText is derived from (or is a type of) Entity, which in turn is derived from (or is a type of)DBObject.

For a Line, we see that there’s a further layer of abstraction. A Line is a type of Curve, which is

a type of Entity, which is a type of DBObject. Arcs, Circles and Polylines (to name but a few) are

also types of Curve.

For our purposes, we can consider the base class for every object that can reside in a DWG

Database to be DBObject. This means that anything you can access inside the DWG is derived

from DBObject. There are other classes further up the hierarchy, but we don’t normally work

with those. Every DBObject in the Database that displays graphics is also an Entity10.

How do you view the properties and events exposed by these classes? Click on MText, and

you’ll see these listed to the right. Here we’ve scrolled down to show the Contents property we

used in the sample code. Clicking on a method or property displays a function signature (as

shown in the screenshot). If you now click on Entity in the expanded MText class node, you’ll

see all the methods, properties and events that MText inherits from its parent Entity class (and

that are common to every other class that is also a type of Entity).

Take some time to browse through and expand the different class nodes in the browser to see

what’s there. Here are the inheritance hierarchies for BlockTable and BlockTableRecord. You

can see that BlockTable is a type of SymbolTable, and BlockTableRecord is a type of

SymbolTableRecord – as discussed earlier. Notice that these are not graphical entities, so

they’re not a type of Entity. Look at the other Autodesk.AutoCAD namespaces as well and

notice the different class hierarchies in those.

9 Object Browser shows a child to parent inheritance hierarchy. A parent to child diagram is better for

studying which classes share common ‘ancestors’. The ObjectARX SDK includes such a diagram in the

<ObjectARX SDK>\classmap folder.

10 You could also define an Entity as anything that is owned by (or stored in) a BlockTableRecord.

Page 18: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

18

And a final note about the class names displayed by Inspector we showed earlier - The

language of AutoCAD is ObjectARX. The .NET API is a thin wrapper on top of this. The classes

in the DatabaseServices namespace are the same as those prefixed by AcDb in ObjectARX. So

when you see AcDbLine in ObjectARX, this translates to

Autodesk.AutoCAD.DatabaseServices.Line in .NET.

A�note�about�RealDWG�RealDWG is a software development kit that allows you to create, modify or read a DWG file

from your own standalone application. That means your application can work with the DWG

format even without AutoCAD installed. RealDWG is used internally by all Autodesk

applications, including AutoCAD itself. RealDWG includes a .NET API that is a subset of the full

AutoCAD .NET API. Obviously, an API that works without requiring AutoCAD doesn’t include

any AutoCAD Editor specific functionality (e.g. viewing a drawing, defining commands,

responding to mouse movements, creating SelectionSets, etc.), but it does include all of the

AutoCAD .NET API needed to directly access the DWG Database from a standalone

application. That’s the Autodesk.AutoCAD.DatabaseServices namespace (and the other

namespaces that namespace is dependent on).

Visit www.autodesk.com/realdwg for more information on RealDWG, or step into DE215-4 - There's More to .DWG Than AutoCAD®.

Further�reading�Here are a few places you can go to for more information on the AutoCAD .NET API:

� www.autodesk.com/developautocad - for a general overview of the AutoCAD APIs and

publicly available resources. This includes the excellent ‘Introduction to AutoCAD .NET

Programming’ DevTV recording by Fenton Webb.

� www.autodesk.com/apitraining - if you’re interested in attending classroom training

delivered by the Autodesk Developer Network team.

� www.autodesk.com/joinadn - to find out how becoming a member of the Autodesk

Developer Network can help your application development efforts, including our

members-only knowledgebase and unlimited technical support.

� www.objectarx.com – to download the ObjectARX SDK, which includes AutoCAD .NET

API documentation and samples.

Page 19: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there

DE205-4: AutoCAD®

.NET Basics

19

� blogs.autodesk.com/through-the-interface – Kean Walmsley’s blog focusing primarily on

AutoCAD APIs. Kean is senior manager of the global Autodesk Developer Technical

Services team (the team who support our ADN partners).

� discussion.autodesk.com/forum.jspa?forumID=152 – the Autodesk public discussion

group for the AutoCAD .NET API.

Acknowledgements�Thank you to everyone in the Autodesk Developer Technical Services team (past and present)

for their contributions to the training material and SDK samples on which I’ve based AutoCAD

.NET Basics.

And thank you to you for signing up for my class.

Page 20: AutoCAD® .NET Basics · related) API was very limited - only allowing the creation of very simple commands. AutoCAD 2006 saw the release of the first full AutoCAD .NET API, and there