Lesson 1: The Basic Plug-in
In this lesson you will create your very first basic AutoCAD plug-in for keeping block attributes parallel to the WCS x-axis.
Video: A Demonstration of Lesson 1 Steps to Create your First Plug-in
Steps to Create Your First Plug-in
- Launch the Visual Basic Express development environment:
Open Visual Basic 2010 Express using the Windows Start menu, selecting All Programs, and then Microsoft Visual Studio 2010 Express and then Microsoft Visual Basic 2010 Express. Note: You can also use Visual Basic 2008 Express with this guide if you are working with AutoCAD 2010 or 2011, but Visual Basic 2010 Express is required if you’re working with AutoCAD 2012. Projects for both Visual Basic 2010* and 2008 are provided in the archive folder.
*If you are using AutoCAD 2013 or higher, make sure you work from the AutoCAD 2013 project versions.
- Create a class library project:
Inside Visual Basic Express, on the File menu, click New Project*. In the Installed Templates tab in the left-hand window, click Visual Basic. In the middle window, click AutoCAD 2011 plug-in (if you don’t see this in your template list, be sure to review the “Software to Install Prior to Starting” in the Overview section). Enter KeepAttributesHorizontal in the Name box. And then click OK.
* If you are using the completed sample projects rather than starting from scratch from the steps we provide here, we assume that you have installed AutoCAD to the C:\Program Files\Autodesk\AutoCAD 2012 - English folder. If your installation location for AutoCAD is different from this, then to be able to debug the completed sample projects, you must follow these steps.
- The AutoCAD.NET Wizard Configurator dialog will now be displayed. Click the ellipsis button next to the topmost empty textbox; browse in the folder selection dialog that appears to the location where you extracted the contents of the ObjectARX 20xx SDK, and select the inc subfolder. Do the same for the other textbox, and select your AutoCAD installation folder – the default location for AutoCAD 20xx English is C:\Program Files\Autodesk\AutoCAD 20xx – English. Keep the other options at their defaults and click Ok.
Visual Basic Express will create a default code project for you and display the code in the code window.
- Save the project:
On the File menu, click Save All. In the display window type C:\test (or your preferred file location) in the Location box, and then click Save.
- Close and reopen the project:
On the File menu, click Close Project; then again on the File menu, click Recent Projects and Solutions and select KeepAttributesHorizontal from the list. This is to ensure Visual Studio has correctly parsed the project files for its IntelliSense feature.
- Check references:
In the Solution Explorer window on the right-hand side of the Visual Basic Express window, double-click My Project.
- Visual Basic Express now displays your project settings in place of your code window. Click on the References tab, and check that AcDbMgd and AcMgd are displayed in the list and that their paths are correctly showing the path to your ObjectARX 20xx\inc folder.
If for some reason AcMgd and AcDbMgd are not listed, click the Add… button, select Reference…, browse to the ObjectARX\inc folder and select those files. Then select each reference in the list to view its properties in the window on the lower right of the Visual Basic Express window, and set the Copy Local property to False.
- Add the code:
Double click MyCommands.vb in the Solution Explorer window to show the code-editing window. Delete everything in this window and then type the following Visual Basic code. To get the full experience of developing with Visual Basic Express – including the use of features such as IntelliSense – we recommend you type the code from this guide rather than copying and pasting it. However, if you’re constrained for time, you can just copy and paste from this tutorial into the Visual Basic Express code window, or just download the completed project file for this lesson and open it in Visual Basic Express. This reduces the experience you gain from working with the code directly, so we don’t recommend it.
Public Class Commands
' Class variable to store the instance of our overrule
Private Shared myOverrule As KeepStraightOverrule
Public Shared Sub ImplementOverrule()
'We only want to create our overrule instance once,
' so we check if it already exists before we create it
' (i.e. this may be the 2nd time we've run the command)
If myOverrule Is Nothing Then
'Instantiate our overrule class
myOverrule = New KeepStraightOverrule
'Register the overrule
'Make sure overruling is turned on so our overrule works
Overrule.Overruling = True
'Our custom overrule class derived from TransformOverrule
Public Class KeepStraightOverrule
'We want to change how an AttributeReference responds to being
' transformed (moved, rotated, etc.), so we override its
' standard TransformBy function.
Public Overrides Sub TransformBy(ByVal entity As Entity,
ByVal transform As Matrix3d)
'Call the normal TransformBy function for the attribute
' reference we're overruling.
'We know entity must be an AttributeReference because
' that is the only entity we registered the overrule for.
Dim attRef As AttributeReference = entity
'Set rotation of attribute reference to 0 (horizontal)
attRef.Rotation = 0.0
Optionally, you can also remove the file MyPlugin.vb from the project. Right click on MyPlugin.vb in the Solution Explorer and select Delete. It doesn’t matter if you don’t delete it – the default code in there isn’t doing anything.
Don’t worry about the details of the code, you’ll be studying this in detail in Lesson 3. For now, it’s enough to know that the text in green are ‘comments’. This is isn’t the program code itself – it is text explaining what the code is doing. It’s very important to write comprehensive comments in your projects – even the best programmers forget what their code was supposed to be doing when they come back to it six months later. If you read through the comments now, you’ll probably get a good idea of what the code is doing.
- Save the file:
On the File menu, click Save All.
- Build the project:
The code you have written is in human readable form. To make the code readable by a computer, you will need to translate it or “build” it.
Inside Visual Basic Express, in the Debug menu, click Build KeepAttributesHorizontal to compile and build your plug-in. The “Build Succeeded” message shows in the status bar of the Visual Basic Express window if the code is successfully built.
That’s it! You have just written your first plug-in for AutoCAD. Let’s run it to see what it does.
Running the Plug-in
- Start AutoCAD.
- Open the BlocksWithAttributes.dwg drawing.
- Load your plug-in into AutoCAD:
Type NETLOAD on the AutoCAD command-line followed by <Enter>. In the file dialog that appears, navigate to the location of the .NET DLL you just built using Visual Studio. If you saved your project in C:\test, this will be C:\test\KeepAttributesHorizontal\KeepAttributesHorizontal\bin\Release. Select the KeepAttributesHorizontal.dll file and click Open.
- Test the plug-in:
Type KEEPSTRAIGHT at the command-line and hit <Enter> - this runs the custom command you defined in your plug-in. The behavior of every attribute in every drawing open in AutoCAD is now being modified by your plug-in. To see this changed behavior, use the ROTATE command to rotate each of the block inserts in BlockWithAttributes.dwg. As you jig the block, you’ll see its attribute(s) remain parallel to the WCS x-axis.
Note - This change to the attribute is permanent. Don’t save the drawing if you don’t want to keep the changes.
Congratulations! You’ve just written your first plug-in for AutoCAD. You will be reviewing the code in detail in Lesson 3.
Before you move on to the next lessons, let us go back to some of the things we skipped over earlier, starting with basic concepts about programming, and the benefits it can bring to your day-to-day work.
Introduction to Programming
The Visual Basic .NET code you have just executed to change the behavior of attributes in a drawing is less than 30 lines long (ignoring blank lines and comments). Here you see a small amount of code working in a similar way to any internal AutoCAD command. If someone new to AutoCAD saw your plug-in working, they would think it was a new AutoCAD feature. Software programming allows you to capture the logic of a particular functionality once and then reap the benefits over and over again - every time you want to perform this functionality.
What is Programming?
A simple answer to this question is: Computer programming is the process of creating a sequence of instructions to tell the computer to do something. You can look at your program as a sequence of instructions. In the remaining lessons in this tutorial, you will learn to interpret what the various lines of code you are writing are telling the computer to do.
If you were to explain a computer to a young child, you might say: a computer is a tool that follows instructions you provide. Programming is one way of giving instructions to the computer. Internally, a computer sees these instructions encoded as a series of numbers (also called machine code). The set of human-readable instructions you saw at the beginning of this lesson is called source code and the computer converts these instructions into machine code which it can then read and execute. A sequence of such instructions (or code), written to perform a specific task, is called a program and a collection of such programs and related data is called software. AutoCAD is one such software product.
Source code can be written in different languages, just as humans use different languages to communicate. The language you will be using in this guide is called Visual Basic .NET, often called VB.NET for short. (‘.NET’ is pronounced ‘dot net’).
Note – Visual Basic .NET is the newest version of Microsoft Visual Basic. Don’t confuse it with Visual Basic 6 or Visual Basic for Applications (VBA), which are much older and nowhere near as powerful as Visual Basic .NET.
What is an API?
API is the acronym for Application Programming Interface: the way a software programmer can communicate with a software product. For instance, the AutoCAD API is the way programmers can work with AutoCAD, and it establishes what functionality a software programmer can use within AutoCAD. For example, you can program AutoCAD to add a line to a drawing because AutoCAD exposes functionality to do that through its API.
To put this slightly differently: commercial software companies, such as Autodesk, often distribute a set of libraries which you can use in your own program to interact with a particular software product, such as AutoCAD, and extend its functionality. This set of libraries is known as the software product’s API.
The type of program you write to interact with a software product and extend its functionality will depend upon how the API has been designed and what has been exposed (through APIs) for you to work with.
What is a Plug-in?
A software plug-in is a type of program module (or file) that adds functionality to a software product, usually in the form of a command automating a task or some customization of the product’s behavior. When you talk about a plug-in for AutoCAD – you may also hear the term add- in or app used – we mean a module containing code that makes use of the AutoCAD API. AutoCAD loads such plug-ins and uses them to adjust its behavior under certain conditions, such as when a particular command is executed by the user of the plug-in.
AutoCAD is not Installed in the Default Location
The completed sample projects assume that you have installed AutoCAD to the C:\Program Files\Autodesk\AutoCAD 20xx - English folder. If your installation location for AutoCAD is different from this, then to be able to debug the completed sample projects, you must either:
Create a new project using the AutoCAD .NET Wizard template (as described in Lesson 1), and copy the code from the completed project into the new project.
Edit the completed project files by hand, as described below.
Editing the completed project files by hand
A limitation of Visual Studio Express is that some project settings are not editable through the user interface. One of these hidden settings is the location of the AutoCAD executable (acad.exe) that you load your .NET plug-in into in order to debug it. To correct the provided completed projects for your AutoCAD installation location:
Open the project folder and find the .vbproj.user file for the project. Using the MyBonusPlugin project as an example, the file you need is: MyBonusPlugin\MyBonusPlugin\MyBonusPlugin.vbproj.user.
Open that file in Notepad or any other text editor.
Search the text for the text string “C:\Program Files\Autodesk\AutoCAD 20xx - English\acad.exe”
For each occurrence of that text, replace it with the actual path to acad.exe on your computer.
Save the file. You should now be able to launch AutoCAD from your debugger, as you would for a new project you created using the AutoCAD .NET Wizard.
Here is an example of the .vbproj.user file contents showing the string you need to replace (make sure you update the file paths to match the version of AutoCAD you are working on):
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<ReferencePath>C:\ObjectARX 20xx\inc;C:\ObjectARX 20xx\inc\inc-win32</ReferencePath>
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Debug|AnyCPU'">
<StartProgram>C:\Program Files\Autodesk\AutoCAD 20xx - English\acad.exe</StartProgram>
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Release|AnyCPU'">
<StartProgram>C:\Program Files\Autodesk\AutoCAD 2012 - English\acad.exe</StartProgram>