Difference between revisions of "Writing Plugins"

Latest revision as of 19:06, 5 December 2016

INTRODUCTION

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

The examples can be found in c:\users\public\documents\WireCAD\WireCAD9\WireCAD SDK\

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.IPluginCore 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] in WireCAD

Take some time to read through the code. The WireCAD.IPluginCore interface is very simple,
yet you can access most of the WireCAD object model through the WireCAD.Workspace Object - 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:

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:

public void Load(IWorkspace ws)
{
  MessageBox.Show("Pausing plugin load so you can attach the debugger");
  ....... Your code here
}

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

WireCAD 8 APIs

WireCAD8.exe API. This is the API for the main WireCAD executable
WireCAD8.exe API

WireCAD 8 Project Database Data Access Layer (DAL)
Project DAL

WireCAD 8 Global Database Data Access Layer (DAL)
Global Database DAL

WireCAD 9 APIs

WireCAD9.exe API. This is the API for the main WireCAD executable
WireCAD9.exe API

WireCAD 9 Project Database Data Access Layer (DAL)
Project DAL

WireCAD 9 Global Database Data Access Layer (DAL)
Global Database DAL