Getting started with VST: "Hello World!" project

Adventures of a Microsoft Dexterity Developer


Okay, so we did not get this far to bring up a "Hello World" message, but I figured that's a pretty standard thing to do in the software development world to introduce a tool or language to software developers, so I am not going to pass upon the chance!

Creating our first Visual Studio Tools project... with a twist!

For this project, we want to be able to register two events that will allow us to display the messages "Getting ready to say Hello World!" and "Hello World" messages after login is successful and before and after the Toolbar form is loaded. Usually, this method of trigger registration is used by Dexterity developers to run code after log in, so I figured I would replicate something we are most familiar with.

Topics being covered

• Creating a VST project
• Events registration
• Running your code before and after login
• Building and Deploying VST project

Let's get started!

1) Open Visual Studio. Go to File > New > Project to create a new Visual Studio project.

2) Find the Dynamics GP in the Project Types pane, then choose Microsoft Dynamics GP Add-In from the installed templates pane.

3) Enter a name for the project. We will be naming our project GPHelloWorld.

4) Click OK to continue.



NOTE: As indicated, I will be using C# as my development language, however, the steps to initiate the project for VB.NET should be the same.

5) Upon clicking OK, Visual Studio will proceed to initialize our project for us. The first thing you will see is the Initialize() method in the GPAddIn class. The GPAddIn is an implementation of the IDexterityAddIn interface. Sufficient to say, the Initialize() method is equivalent to the global Startup script in a Dexterity integrating application, serving as entry point to the add-in project.

GPAddIn.cs

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Dexterity.Bridge;
using Microsoft.Dexterity.Applications;

namespace GPHelloWorld
{
    public class GPAddIn : IDexterityAddIn
    {
        // IDexterityAddIn interface
        public void Initialize()
        {

        }
    }
}

NOTE the Solution Explorer window will show the references to the primary assembly responsible for exposing Dynamics GP resources: the Microsoft.Dexterity.Bridge assembly. As well, you can find all picture resources that will make our VST controls look awefully similar to the standard controls available to integrating Dexterity applications.



6) Now, we will proceed to register the event on the Toolbar form. We will display a message "Getting ready to say Hello World!" before the toolbar form is loaded and one that says "Hello World!" after the toolbar is loaded. You can then decide what event works best for your individual needs.

GPAddIn.cs

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;
using Microsoft.Dexterity.Bridge;
using Microsoft.Dexterity.Applications;
using Microsoft.Dexterity.Applications.DynamicsDictionary;


namespace GPHelloWorld
{
    public class GPAddIn : IDexterityAddIn
    {
        // IDexterityAddIn interface
        public void Initialize()
        {
            ToolbarForm toolbar;
            toolbar = Dynamics.Forms.Toolbar;

            // add registration before the form open event
            toolbar.OpenBeforeOriginal += new System.ComponentModel.CancelEventHandler(toolbar_OpenBeforeOriginal);

            // add registration after the form open event
            toolbar.OpenAfterOriginal += new EventHandler(toolbar_OpenAfterOriginal);
        }

        void toolbar_OpenBeforeOriginal(object sender, System.ComponentModel.CancelEventArgs e)
        {
            MessageBox.Show("Getting ready to say Hello World!");
        }

        void toolbar_OpenAfterOriginal(object sender, EventArgs e)
        {
            MessageBox.Show("Hello World!");

        }
    }
}

A couple things to highlight in the code:

a) Like references in Dexterity, VST allows you to create variables that point to specific dictionary resources. The definitions for the various dictionary resources are found in an additional namespace available in the application assembly, Microsoft.Dexterity.Applications.DynamicsDictionary.

using Microsoft.Dexterity.Applications.DynamicsDictionary;

Once the namespace is added, you can then proceed to declare a variable that will represent the Toolbar form.

public void Initialize()
{
    ToolbarForm toolbar;
    toolbar = Dynamics.Forms.Toolbar;
    .
    .
}

b) An event registration is the Visual Studio equivalent of a Dexterity trigger. As such, they must be included in the Initialize() method, added automatically when the project was created. The Initialize() method is the equivalent of the Startup() script in a Dexterity integrating application. To register the events that will be executed before and after the Toolbar form is loaded, the following code was added,

// add registration before the form open event
toolbar.OpenBeforeOriginal += new System.ComponentModel.CancelEventHandler(toolbar_OpenBeforeOriginal);

// add registration after the form open event
toolbar.OpenAfterOriginal += new EventHandler(toolbar_OpenAfterOriginal);

If you noticed when you typed the += character sequence, you were prompted to press the TAB key twice! Intellisense automatically completed the code and added the overload methods for each event handler. Now, that's a time saver! Imagine if we had this type of capability when adding the trigger registration scripts in Dexterity!

c) The rest was just cosmetics.. I added the MessageBox.Show() function to display our two messages in each overload method. The MessageBox is part of the System.Windows.Forms namespace which must be added to the using section of the application.

void toolbar_OpenBeforeOriginal(object sender, System.ComponentModel.CancelEventArgs e)

{
   MessageBox.Show("Getting ready to say Hello World!");
}

void toolbar_OpenAfterOriginal(object sender, EventArgs e)
{
   MessageBox.Show("Hello World!");
}

Simple enough!

7) Building the solution is done via the Build menu, but before, we can set our final assembly name by right-clicking on the GPHelloWorld project in the Solution Explorer window and selecting the Properties option.



8) Build the solution. You should be able to find your new assembly in the Bin\Debug folder of the solution directory, typically under C:\Users\yourUser\Documents\Visual Studio 2008\Projects\GPHelloWorld\GPHelloWorld\bin\Debug.

Copy the resulting project assembly to the AddIns folder under your Microsoft Dynamics GP installation directory.

Testing the solution

Open Microsoft Dynamics GP to see the results. Before the Toolbar form is loaded, we will receive the first message:



Once the Toolbar form is loaded, our next message will be displayed, as follows:


I guess this is not bad for a first try, is it?

While integrating solutions tend to be a lot more complex than our Hello World application, the principles will be the same. For our next installment, I will be contructing a WinForm and showing common ways to store and retrieve data in a VST solution.

Downloads

HelloWorld Solution C# - Click here
HelloWorld Solution VB.NET - Click here

Until next post!

MG.-
Mariano Gomez, MVP
Maximum Global Business, LLC
http://www.maximumglobalbusiness.com/