Gordon McComb
Automation

Introducing: How to Use WordPerfect
with Visual Basic .NET

Greatly enhance WordPerfect Automation with VB.NET

Visual Basic .NET lets you to build your own Windows programs that are capable of just about anything you can imagine. But you probably knew that already.

What you may not know is that with Visual Basic .NET (VB.NET) you can greatly enhance WordPerfect's automation features, extending your trusty word processor into new areas of your business. And you don't have to buy any new software!

For example, you can combine the flexibility of WordPerfect and the power of VB.NET to:

  • Readily connect to a SQL database, of any size, for adding, storing, and using client information in your WordPerfect documents;
  • Enhance the look, feel, and interactivity of your WordPerfect macro dialog boxes;
  • Build your own document assembly system that work exactly the way you want it to (no more settling for what someone else designed);
  • Create a fully automated e-mail merge system for personalized newsletters and mass e-mail correspondence with customers or clients;
  • Streamline your workflow by seamlessly connecting to the Windows functionality already on your PC;
  • ... and much more.

What Visual Basic .NET Gives You

Adding the power of VB.NET extends WordPerfect's own built-in macro language, and allows you to use the latest technologies available on Windows.

VB.NET is a collection of interfaces that are designed to insulate programmers from low-level Windows functions. What this means is you can create robust Windows applications without having to learn arcane programming. Your applications rely on a tested framework that does most of the work for you. They're easier and quicker to write, and less prone to serious bugs.

So what can you do with Visual Basic .NET? As an example, the screen below is from a "video documenting" program I created that helps law enforcement and attorneys accurately document video clips - down to individual frames, when necessary. (The scene shows an old videotape of my son, then two years old, apparently trying to steal a boat at a kiddy karnival!)

The program is written in Visual Basic .NET, using all the features available to the platform- integration of full motion video, editable graphics, sophisticated data grids, interactive forms and dialog boxes, and much more.

Specific frames can be annotated, both graphically and textually. Once information has been collected about a video clip, it's stored in a database. That database is then used to prepare various reports directly in WordPerfect.

Simply put, WordPerfect's own macro language is no where near powerful enough to accommodate all the features of the video documenting software. Yet the VB.NET program greatly enhances the functionality of WordPerfect, and turns it into a tool that might have otherwise cost tens of thousands of dollars.

Example multi-faceted VB.NET application that interfaces directly with WordPerfect for document automation.

The .NET platform supports multiple languages, the two most widely used are C# (similar to C), and Visual Basic. For these tutorials we'll restrict ourselves to the Visual Basic variety, as that's the easier programming language to use, and the one most office productivity users are most comfortable with.

The full .NET Visual Studio package is quite expensive and complex. Fortunately, Microsoft provides FREE "Express" versions, available at their Web site. These versions are well suited for development of WordPerfect automation solutions, and do everything we need them to do.

You can download the latest version of Visual Basic Express from here:

www.visualstudio.com/en-US/products/visual-studio-express-vs

Interoperating with Other Applications

VB.NET provides several means to interoperate (share data, remotely control) with other Windows applications.

One of the most commonly used methods is COM -- which stands for Component Object Model. Don't worry about what it really is. Just know it's been around for years, and is used by the many Windows programs, in one fashion or another.

Programs like WordPerfect use COM as a means to allow other applications to remotely automate it. And this is precisely what we're most interested in.

(And of course the tables can be turned: WordPerfect can be used to control another application. For the next few tutorials, though, we'll concentrate on WordPerfect being the controlled application, and Visual Basic .NET doing the controlling.)

The nature of VB.NET requires a type of bridge between it and any programs that are automated via COM. This bridge insulates most of the nasty parts of Windows functions and memory management from you, the programmer. The bridge is generally referred to as an interop assembly or interop library. ("Interop" is short for interoperating, a method of exchanging data from one program to another.)

In many cases, interop libraries are provided by the publisher of the software. Or they can be created from a type library that is provided with the software. Type libraries are like Rosetta Stones; they are designed to allow one program to know how to communicate and control another program. These files typically have a .tlb extension; for instance, the type library for WordPerfect X3 is wpwin13.tlb, and is found in the application's Program folder.

Creating an Interop Library

So we know that programs like WordPerfect come with a type library file that contains basic instructions for how other applications can communicate with it.

When loading the type library file into your VB.NET program, the .NET programming environment automatically generates an interop library -- the "bridge" -- for you. With this library you are then able to craft programs that integrate with WordPerfect.

Those familiar with automating WordPerfect using PerfectScript or VBA macros will recognize the command structure available through the interop library: it is remarkably similar to the same commands you use to produce a WordPerfect macro. That's good news: If you're already familiar with PerfectScript or WordPerfect VBA programming, it's a fairly straight-forward process to create automation solutions in VB.NET.

To create a library for communicating with WordPerfect:

  • In VB.NET, choose Project, Add Reference.
  • Click the COM tab.
  • Locate the WordPerfect type library. Look under Corel - WordPerfect *. (If you see a type library for PerfectScript don't add a reference to it. It's not the right library) You can have multiple versions of WordPerfect on your machine. Select the type library for the version you wish to use.
  • Click OK. This creates the interop library.


With some versions of WordPerfect, VB.NET may fail to generate the interop library, and an error could result. If this occurs, you can use one of the precompiled library files listed at the end of this tutorial.

Be sure to download the correct one for your version of WordPerfect.

Official Primary Interop Libraries

In most cases the process of automatically creating an interop library from a type library goes without a hitch. The resulting library may be used as-is. But the more sophisticated the type library, the more chances the resulting interop will contain errors, obfuscated command names, and other issues that prevent easy use.

Typically, the company that produces the application -- Corel, in the case of WordPerfect - will craft a special hand-tweaked version of the library for use by .NET programmers. This official version is referred to as primary interop assembly, and is meant to take precedence over any other version created automatically.

So far, Corel has not produced a primary interop library for use with any version of WordPerfect, even the latest version, which as of this writing is WordPerfect X5. So, if you want to develop an automation solution using VB.NET, you must either:

  • Rely on the automatic creation of an interop library from the *.tlb type library files provided with WordPerfect;
  • Or, obtain pre-made interop libraries from a third-party source, such as this Web site. See the bottom of this tutorial for a list of interop libraries we've created for you.

Using the Generated WordPerfect Library

VB.NET will produce a different library for each version of WordPerfect ( versions 9 and above supported). When developing against WordPerfect X3, for example, it's important to add the wpwin13.tlb type library to the VB.NET project. This will ensure compatibility with WPWin X3.

See Creating an Interop Library, above, for the the to create the interop file. The library may then be referenced in your code. In Visual Basic, this is done by inserting the following statement:

Imports WordPerfect

It looks like this in the VB.NET code editor window:

In the WordPerfect interop library are a number of classes - for now, forget worrying about what a class is. The class of main interest to us goes by the name "PerfectScript." In your program, you create a new PerfectScript object, using the WordPerfect.PerfectScript class, to use in the automation. This is how it's done:

Dim wpwin As WordPerfect.PerfectScript = New WordPerfect.PerfectScript

You can think of the wpwin object as WordPerfect itself. With it, you may add whatever commands you wish to use to control the program. For instance, to start WordPerfect, display the About WordPerfect box, then exit, you'd add:

wpwin.AppMaximize()
wpwin.WPActivate()
wpwin.AboutDlg()
wpwin.ExitWordPerfect()
System.Runtime.InteropServices.Marshal.ReleaseComObject(wpwin)
wpwin = Nothing

That's pretty much all there is to it. We'll leave more robust examples to a later installment, so for now let's move on to actually building and using a working WordPerfect VB.NET automation example.

Example Code You Can Try Out

For your convenience, you can download the complete WordPerfect VB.NET integration project from the link at the bottom of this article. You'll need Visual Basic .NET 2008 or later. See the sidebar on how to get a free copy of VB.NET

Try the following short exercise to get the feel for automating WordPerfect with VB.NET.


  • Open the VB.NET editor. Create a new solution if a blank one is not already displayed.
  • Locate the Form1 form, and add a push button (from the Toolbox) anywhere on it. Name the button btnTest, and change its text to Test.
  • Add another push button. Name this button btnCancel, and change its text to Cancel.
  • Double-click the Test button to show the code window.
  • Change the code to that shown below. The important things are these: Place the Imports statement at the top, and put the rest of the code between the Public Class ... and End Class lines, as shown.
Imports WordPerfect

Public Class Form1

  Private Sub btnTest_Click(ByVal sender As System.Object, _ 
      ByVal e As System.EventArgs) Handles btnTest.Click
    Dim wpwin As WordPerfect.PerfectScript = New WordPerfect.PerfectScript
    wpwin.AppMaximize()      'Displays the program window
    wpwin.WPActivate()       'Activate program window
    wpwin.AboutDlg()         'Displays the About box
    wpwin.ExitWordPerfect()  'Quits WordPerfect
    System.Runtime.InteropServices.Marshal.ReleaseComObject(wpwin)
        'Special kind of cleanup
    wpwin = Nothing          'Marks the wpwin object for removal
  End Sub

  Private Sub btnClose_Click( ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles btnCancel.Click
    Me.Close()
  End Sub

End Class

The code window should look like this when you've added the program code.

When you Run this program it should open WordPerfect, and display its About box. Click the OK button in the About box, and WordPerfect will then close.

To exit your VB.NET application simply click the Close button in the main form.

Issues with the Generated WordPerfect Library

For the most part, the library generated by .NET performs well. But, it does suffer from a few deficiencies that make it harder to use than it ought to be:

  • It generates several duplicate classes, creating unnecessary bulk. For this reason WordPerfect interop files tend to be over 650K. Ignore these other classes as they are of little or no use to you.
  • It exposes a Script object that appears to be non-functional (or causes execution errors if used). The Script object contains the PerfectScript programming commands: If, While, MessageBox, and so on. These are not strictly necessary for VB.NET applications, in any case.
  • Enumerated values -- the funny names that appear with exclamation marks in a PerfectScript macro -- are obfuscated to avoid duplication. For example, in PerfectScript to turn reveal codes on or off you'd use On! or Off!. In a VB.NET program you'd use:
_RevealCodes_State_enum.On_RevealCodes_State

(If it's really important to you, you can redefine these enumerations to provide more concise names; this will be discussed another time).

  • Some commands are renamed to prevent collision with reserved VB.NET keywords. The two most notable are KeyType for the WordPerfect Type statement, and the absence of the Print command (use PrintAction instead).
  • WordPerfect system variables -- which appear as ?VariableName (question mark, and name) in a PerfectScript macro -- are converted to envVariableName ("env," and the name of the variable).
  • Incorrect data types and "data marshaling" can sometimes occur. This is a more advanced topic than the scope of this article allows, but suffice it to say, the automatically generated library may contain incorrect assignments for some commands, resulting in improper execution. This is most commonly encountered with commands, such as the deprecated GetData statement, that return a value as one of the parameters.

Other Methods to Automate WordPerfect

Interop libraries are not strictly required to automate WordPerfect from another application. Using a method called late-binding, it is possible for a program to connect to the WordPerfect COM interface, and issue a series of commands to perform some action. In this scenario, there is no need to reference a type library, and no interop is created.

However, late binding suffers from a couple of limitations, and should only be used only when needed. First and foremost is that late binding is a little slower. Programs that interact heavily with WordPerfect may exhibit somewhat slower response.

Second, VB.NET cannot provide type checking or syntax help when using late-binding. When you use an interop library, VB.NET gives you a feature known as Intellisense (shown on the right), where you can scroll through the available list of commands and values to find the one you want. This makes it much easier to develop and test your programs. Intellisense not only gives you a list of available commands, but provides reminders about any parameters they accept.

Going Forward

Feel free to download the entire project for this tutorial, and try it out yourself. See the link below. Be sure to create or add the proper interop library, as noted above. The example project won't work until you do.

In future tutorials I'll discuss many other practical automation techniques, including building WordPerfect merge files from VB.NET, sharing variables between a VB.NET application and WordPerfect, revising older VB5 and VB6 programs to Visual Basic .NET, and much more.

Download the WPExperiments file by right-clicking, then saving to your computer. Unzip the files to your usual VB.NET projects directory.

Text and project Copyright © 2010, Gordon McComb. Released under Creative Commons Attribution-Share Alike license. You may use, reproduce, modify, and distribute this code, as long as the above copyright and attribution is retained.