Writing Plugins

INTRODUCTION

The examples can be found at:

C:\users\public\documents\WireCAD\WireCAD9\WireCAD SDK\Examples

Welcome to the WireCAD SDK examples. These examples show you how to

interact, via your own code, with WireCAD. These examples assume that

you understand the basics of C# programming syntax and structure

(the examples are in C# but you may use any .NET programming language

that you are comfortable with).

If you do not understand it don't let that deter you. It is really

very easy to understand. Microsoft has tons of examples. Just get on

the web.

If you have WireCAD SDK specific questions email support@wirecad.com

along with as much code as you can and an explanation of what you are

trying to do. We will try to help. If you need more help or if you are

developing a commercial plugin for WireCAD you may want to consider

purchasing custom programming services from us.

Please call the office for more information.

Getting Started

You will want to download a .net ready integrated development environment(IDE)

like Visual Studio for c# or SharpDevelop. Visual Studio has free versions.

SharpDevelop is open source.

We recommend the Visual Studio for the ability to attach a debugger to your

running process. Also use the WireCADv9TemplateInstaller.vsix to install several

starter projects in Visual Studio that you can use from the File>New Project wizard.

The first place to go with any programming effort is the ubiquitous

"Hello World" example in the Basic folder.

NOTE: there are two types of WireCAD plugin.

1. The automatically discovered (AD) plugin that loads silently

and may or may not interact with the user.

2. Plugins that require a WireCAD .wpi manifest file that describes

where the plugin can be found, how to call it, what icon to display and on

which toolbar or menu, etc. Both plugins implement the WireCAD.IPlugin interface.

AD plugins are named YourPluginName.Plugin.Dll and are placed in the

C:\users\public\documents\WireCAD\WireCAD9\\bin folder.

Standard WireCAD plugins have no naming requirements

but must be accompanied by a .wpi file in the

C:\users\public\documents\WireCAD\WireCAD9\Plugins\Active Plugins folder.

To create a wpi file you can use the utility in Plugins>Plugin Manager [New PI Info]

Take some time to read through the code. The interface is very simple,

yet you can access most of the WireCAD object model including drawing,

data access, grids, GUI, reports, etc.

You can also create your own forms and functions to interact with the

WireCAD objects.

THIRD PARTY LIBRARIES

WIRECAD USES THIRD PARTY LIBRARIES THAT MAY REQUIRE YOU TO PURCHASE DEVELOPER

COPIES. PLEASE DO NOT IGNORE THIS STATEMENT. THESE ARE GREAT LIBRARIES AND

IF YOU ARE PLANNING TO DEVELOP A COMMERCIAL PLUGIN FOR WIRECAD YOU WILL WANT

TO HAVE THEM. If you are developing a small project or line of business function

for your own use you may not need to purchase licenses. Here is an example:

If you want your plugin to have the same look and feel, or create a custom form

with the same gridview or treeview as WireCAD you will need

to purchase the Developer Express library. If you are developing a custom form

that needs to show its own drawing engine you will need to purchase the

VectorDraw developer framework. If, on the other hand, you are able to use

the WireCAD baseforms object, are happy with the WinForms controls and can

develop using the WireCAD drawing engine then you can get started without

spending a dime.

BUILDING YOUR FIRST PLUGIN

STEPS:

1. Open your IDE

2. Click File>Open Project or Solution and browse to the basic hello world.csproj

project file in the examples\basic\hello world folder

3. Click Build>Build Solution (Ctrl+Shft+B) to build the project.

4. Check that the file C:\Users\Public\Documents\WireCAD\WireCAD9\bin\helloworld.plugin.dll

exists. If it does not then you need to check the project build path in the project properties

section and point it to the WireCAD bin folder above.

If you get any reference errors check Project>Hello World Properties... [Reference Paths] section

points to C:\Users\Public\Documents\WireCAD\WireCAD9\bin\. If it does not then modify

it and make sure that your reference errors disappear.

5. You now need to force WireCAD to load the shiny new plugin.

Either relaunch WireCAD (tedious) or click Plugins>Plugin Manager ... then

click the [Rescan and Reload All Plugins] button. Make sure that the helloworld.plugin

appears in the Auto Discovered Plugins list.

6. Now enter hw in the commandline and click [Enter]. This will launch the command that

the plugin registered in its Load() method.

7. Make some changes and click Build>Build Solution (Ctrl+Shft+B) to build the project again.

if your changes are outside the load() method you will not need to force a reload.

just call the command again by typing hw in the commandline and click [Enter].

There you have it. You have just built your first WireCAD plugin. Now go forth and do more!

DEBUGGING YOUR PLUGIN

Invariably you will need to stop the execution of your plugin and examine the variables

and logic structure to figure out why it is not working as you expect.

The following instructions assume you are using the Visual Studio IDE for C#. Further, that

you have built your project and made sure it is loading in the WireCAD plugin framework by

looking at the loaded plugins list in Plugins>Plugin Manager...

NOTE: The following will work for anything other than the initial Load() method. To debug that

read on.

Steps:

1. Open your project in the Visual Studio IDE.

2. Run WireCAD.

3. In VS click Debug>Attach to Process...

4. Select WireCAD9.exe.

5. Place a breakpoint in the code where you want to stop execution. Do this by clicking in the

gutter of the text editor(very left hand edge. A red dot will appear).

6. Execute your command. The debugger will pause at the line and highlight the paused line.

In the interface you will find two very helpful tool windows - Locals and Autos. These windows

list the variables in play at the time of the breakpoint.

7. On the IDE Debug menu you will find commands to continue execution:

1. Continue - runs from the break point until it hits the next breakpoint if any.

2. Step Into - continues execution of the next line. If the next line calls another function

you will be stepped into that function.

3. Step Over - continues execution of the next line. If the next line calls another function

that function will execute in it entirety and you will step to the next line in the current

code block.

While you cannot edit and continue you will be able to understand the changes you need to make

to fix the issue you are having.

8. Stop the debugger. Fix your code. Lather, rinse, repeat.

DEBUGGING THE LOAD() METHOD OF THE IPLUGINCORE INTERFACE

The load method or the HasPermissionToRun methods of the IPluginCore interface require some

special consideration if we are to debug them. The reason for this is that the WireCAD loading

process will call these methods before we have a chance to attach the debugger to the process.

This section will outline two approaches:

1 - PAUSE EXECUTION USING MESSAGEBOX

Place a MessageBox.Show("Pause"); command in the Load or the HasPermissionToRun method.

This modal dialog will pause execution for you to attach the debugger as shown above.

like this:

/// <summary>

/// This is called when the plugin is loaded at application start

/// </summary>

/// <param name="ws">Singleton WireCAD Workspace object</param>

public void Load(IWorkspace ws)

{

MessageBox.Show("Pausing plugin load so you can attach the debugger");

....... Your code here

}

2 - START WIRECAD IN THE DEBUGGER PROCESS

The other approach is to start WireCAD in the debugger from your project. While this seams like a

good approach it suffers from a major drawback. When you want to fix your code you must stop the

debugging session. Since WireCAD is running in the same process it will stop as well. Thus requiring

you to start WireCAD every time you want to make a fix.

Steps:

1. Open your project in the IDE.

2. Close WireCAD.

3. Open the Project Properties window - Project>YourProjectName Properties...

4. Select the Debug section.

5. Select the Start External Program radio button.

6. Browse to the WireCAD9.exe at: C:\Users\Public\Documents\WireCAD\WireCAD9\bin\WireCAD9.exe

7. Place your breakpoint.

8. Click Debug>Start Debugging (F5).

This will start the debugging session by launching WireCAD first. As WireCAD loads it will eventually

come to your Load() method and hit your breakpoint.

When you are finished with your examination close WireCAD and let it shutdown. Ending the debugging

session with the Debug>Stop Debugging (Shift+F5) acts like Kill Process and will not allow WireCAD

to store session state.

ADDITIONAL RESOURCES

C# is the language of choice for developing in WireCAD. There are tons of resources

online to learn this language.

For WireCAD specific issues:

www.wirecad.com/wiki

support@wirecad.com

Please don't submit support tickets for SDK issues. Use the support email.

Developer Express is the library we use for many of the UI elements. They have

a brilliant web site with documentation and support. If you are going to go

deep on WireCAD development you will probably want to purchase a license.

www.developerexpress.com

VectorDraw is the drawing engine we use. While their site is minimal they do offer

registered developers lots of sample code.

www.vdraw.com

for a full api listing visit:

for the main WireCAD9.exe:

https://www.wirecad.com/api/90/exe/index.html

for the global data access layer:

http://www.wirecad.com/api/90/globaldal/index.html

for the project data access layer:

http://www.wirecad.com/api/90/projectdal/index.html