One of the greatest strengths of Autodesk products is the extensive Application Programming Interface (API), which gives users the ability to customize and extend the functionality of the software. In the past, some favorite techniques included using Visual Lisp or VBA to create any needed customizations. However, technology has been changing, and with Civil 3D, we need a somewhat different approach…

Visual Lisp and VBA both share something in common: they utilize what’s called the ActiveX API to AutoCAD (often called the COM API, as well). However, this technology has been deprecated, in favor of what we typically call the .NET API.

.NET APIs have several advantages over the old-style APIs. First, they are created more in the lines of a framework, rather than a class library. In a class library, we write code, calling library routines as-necessary. By contrast, in a framework, the framework calls our code, and all we write are the parts that are “different” from other applications. A lot of our programming gets run in response to “events” that happen in the main application, which trigger our special code. This shift in focus often simplifies our development, and reduces the amount of code we have to write. And in addition, a .NET API tends to be lighter-weight than the COM API, using fewer resources, and running faster.

As a drawback, we cannot use Visual Lisp or VBA to interact with the .NET API – those environments are not “.NET enabled”. So that leaves many long-time users of Autodesk products in a quandary… Which API to use? The ActiveX API, which lets us use the old familiar Lisp and VBA? Or this new .NET API, which requires learning a new programming environment and programming language?

Well, the good and bad news is that this decision has pretty much been made for us. Microsoft has deprecated VBA, and for several years now, has been pushing developers to drop VBA in favor of .NET. As a result, VBA will not be available inside of Civil 3D after the 2011 release, so VBA is no longer a good choice. And Autodesk has decided to concentrate only on the .NET API, so for the last couple of releases, we have only gotten new API functionality in the .NET API. And as time goes on, more and more functionality will be available only in the .NET API.

Visual Lisp can still be useful in some situations, but it cannot directly access the .NET API.  So while it is still suited to a variety of macro and scripting tasks, it is not a good choice for any customization that needs to access Civil 3D entities.

This means that many programmers are looking at the prospect of learning a new development environment. This can be intimidating – .NET is very large, compared to Visual Lisp, and it initially seems like everything is very roundabout, instead of simple and direct like Lisp. However, it also gives us quite a few advantages:

• We can use the Visual Studio Express or SharpDevelop Integrated Development Environment (IDE) to write our code. These IDEs are far superior to the Visual Lisp editor, and are even an improvement over the VBA editor. And they can be downloaded for free.
• We have access to the Microsoft .NET framework, which contains tons of useful functionality. Not only does this framework give us access to all parts of Windows, it also gives us lots of utility classes, such as Lists, Dictionaries, Hash Sets, string parsing and formatting, advanced math functions, and more. Much of this stuff had to be hand-written in VBA and Visual Lisp. So the availability of the Microsoft .NET frameworks means that we often have to write a lot less custom code in order to get our custom applications working.
• We have full access to Windows Forms and Windows Presentation Framework (WPF), so we can create much more elaborate user interfaces than we could in Visual Lisp, or even in VBA.
• We have “Intellisense” in our IDEs, which makes it much easier to code. It lets us easily see what methods, properties, and events are available to any object, while we’re writing our code, and all we have to do is type the first few letters, and the rest is auto-typed for us.
• Our applications typically run faster. This may not matter for some routines, but can make a huge difference in other routines.
• A .NET application tends to be much more readable than a Lisp application, especially for large projects. And “more readable” means “more maintainable” – years later, when that original programmer is no longer around, and someone else needs to improve a routine or figure out why it stopped working, it’s much easier for the new programmer to parse a large .NET application than a large Lisp application.
• .NET applications tend to be somewhat platform-independent, so the vast majority of our code will work on 32-bit and 64-bit systems, and on any Windows OS, with no issues.
• .NET applications can use either the ActiveX or COM API, and can even use both at the same time.
• .NET gives us a choice of languages to work with. The most common are VB and C#, but there are a number of others, as well. In particular, Boo, F#, and IronPython have been gaining large followings. And as a nice side-benefit of .NET, we can interchange these languages. For example, we can create a DLL using VB.NET, but then we can use that DLL in a C#.NET project, and vice-versa.

Unfortunately, there are also some drawbacks to using .NET:

• We have to compile DLLs, rather than simply loading a code file.
• Autodesk was originally creating an ActiveX API for Civil 3D, and only later decided to switch to a .NET API. And at the moment, much functionality can only be accessed via the ActiveX API. Unfortunately, applications that use this API will only work with a specific version of Civil 3D, and the source code must be compiled into a different DLL for each version of Civil 3D.
• Civil 3D customization is currently complicated by the fact that some Civil 3D functionality is only available in the ActiveX API, and some functionality is only available in the .NET API. So for many tasks, we basically have to use both APIs at the same time. This complicates our code, and forces us to frequently convert objects between ActiveX objects and .NET objects. This is relatively easy, yet it is an additional hassle and complication. Eventually, the entire API should be .NET, and this issue should go away, but for now, it is something we have to deal with. In the code, it is usually pretty easy to identify the ActiveX objects, because they generally have class names that start with “Aecc”, such as “AeccAlignment” or “AeccPoint”.

The initial switch to .NET can be daunting, much like that initial switch to Civil 3D. But all in all, most people who make the switch are happy with it, and in particular, coding in Lisp can start to seem like living in the dark ages. There are many tasks that were difficult or impossible in Lisp or VBA and the ActiveX API, but are relatively simple when using the .NET API, and it’s much easier to create things that make people go “Wow!”. But if you’re already comfortable with Lisp or VBA, it can be painful at first. Luckily, there are lots of options for help available.

First, a lot of information is included in the program itself, and can be found in your Civil 3D installation folder. This includes a Developer’s Guide and API documentation, which are in the “Help” subdirectory.  The “Samples” subdirectory also contains a number of code examples.  This includes all of the VB.NET source code for the stock subassemblies that ship with Civil 3D, so as you progress with .NET, you will be able to customize any of the stock subassemblies, customizing and extending their behavior.  You can even create completely new subassemblies yourself.

There are also a number of free resources available from Autodesk on the web.  For all .NET programmers, Kean Walmsley’s Through the Interface blog is an invaluable resource.  Kean works at Autodesk, and in his blog, he regularly dissects new features found in the API.  With more than four years of posts currently available in his archive, there is a wealth of information and .NET sample code on this site.  In addition, there are also the various customization groups in Autodesk’s discussion groups, including one devoted specifically to Civil 3D.   Many questions can be answered in these groups.  And of course, it isn’t free, but there is always the annual Autodesk University, which typically contains a number of classes devoted to customizing Autodesk products.  Attendees of Autodesk University also gain access to all the archived classes, and can access them as-needed all year long.

There is also the .NET forum in The Swamp, where many knowledgeable and helpful denizens can be found.  The first topic in that forum contains a large number of useful links for people just starting out with .NET.  Registering at the site is free, and allows you to post your own questions.  You can also search this forum for a lot of recommendations for books that others have found useful in the transition to .NET.

And finally, you may also wish to download the Sincpac-C3D Free Edition Source Code, available from Quux Software. This source code (written in C#.NET) contains a small portion of the functionality of the Sincpac-C3D add-on for Civil 3D, so you can see a working example of a Civil 3D custom application. This source code is released under a very permissive license, so you may feel free to grab it, use it, modify it, and include it in your own applications (even in closed-source commercial applications). The download includes solutions configured for Civil 3D 2008, 2009, 2010, and 2011, and the 2011 version will run on either 32-bit or 64-bit Civil 3D. This source code shows how to do a lot of basic tasks with the API, and contains examples of how to use the ActiveX and .NET APIs in combination. Since this source code is designed to work in all versions of Civil 3D, 2008-2011, it primarily uses the ActiveX API to interact with Civil 3D entities, but it uses the core AutoCAD .NET API for many tasks, and there are many examples where entities are converted from .NET to ActiveX, or vice-versa.  In addition, Christopher Fugitt is adding a series of posts to his Civil 3D Reminders blog, which will show step-by-step how to create your own custom commands, using the Sincpac-C3D Free Edition Source Code as the starting point.

It requires some effort, but learning how to customize Civil 3D can yield huge benefits.  So good luck with your own customizations!