Using a .NET Assembly from a Dexterity-Based Application
Patrick Roth
Microsoft Business Solutions–Great Plains Developer Support
May 2005
Applies to:
Microsoft Business Solutions–Great Plains
Microsoft Business Solutions Dexterity 8.00m76
Microsoft Visual Studio .NET 2003
Summary: This article demonstrates the creation of a class written in C# in such a way that it is callable by means of COM in an application. In addition, sample Dexterity code is included, demonstrating this ability. (7 printed pages)
Contents
Introduction
Getting Started
Generating the C# Files
Creating the Dexterity Application
Testing
Conclusion
Introduction
The following are steps to creating a C# class that can be called by means of COM from any application. After the assembly is created, a Dexterity script is created that calls and tests the assembly.
The C# class created for this example is a simple example; however, more complex projects can be created and used successfully. This document assumes that the reader will have some experience in Microsoft Business Solutions–Great Plains, Microsoft Business Solutions Dexterity, and Microsoft Visual Studio .NET.
Getting Started
The first step is to create the C# assembly that will be used from Dexterity.
Launch Microsoft Visual Studio .NET
From the Start menu choose Microsoft Visual Studio .NET 2003, then click Microsoft Visual Studio .NET 2003. After the application is started, choose Create a new project. The project will be of type Visual C# projects using the Class Library template. For this example, set the Name of the project to SimpleProperties.
Change the Default File Name for this Class
In the Solution Explorer window, rename the default file Class1.cs to SimpleProperties.cs.
Script: SimpleProperties.cs
The following C# code was entered for the SimpleProperties class and replaces the default generated code.
using System;
using System.Runtime.InteropServices;
namespace SimpleProperties
{
public class SimpleProperties
{
[ClassInterface(ClassInterfaceType.AutoDual)]
public class ConvertDollars
{
private short cnts;
private int dlrs;
private int amnt;
public ConvertDollars()
{ //initialize this object to $10.25
dlrs = 10;
cnts = 25;
}
public ConvertDollars(int x)
{ // 2nd constructor. Not available to COM
amnt = x;
}
public int amount
{
get {return amnt;}
set {amnt = value;}
}
public short cents
{
get {return cnts;}
set {cnts = value;}
}
public int dollars
{
get {return dlrs;}
set {dlrs = value;}
}
public string sAmount
{
get {return "$" +
dollars.ToString() + "." +
cents.ToString();}
}
public string SetArray(string s,ref string[] myarray)
{ //The example is passing a 5 element array.
//C# uses a zero based array
//and Dexterity uses a one based array.
//Note that Dexterity will crash
//if this array is resized because Dexterity
//is unable to dynamically resize an array
try
{
myarray[0] = "one";
myarray[1] = "two";
myarray[2] = "three";
myarray[3] = "four";
myarray[4] = "five";
return s; //pass back in the string sent
}
catch(Exception e)
{
return "exception caught:" + e.Message;
}
finally
{
}
}
}
}
}
Generating the C# Files
Creating the C# Assembly
From the File menu, choose Save All to save your work. From the Build menu, select Build Solution item or press CTRL-Shift-B to generate the assembly. At this point, Visual Studio should have generated a debug build of the SimpleProperties.dll file. This file is created in the \bin\debug directory to where the Visual Studio .NET project file was created. At this point, copy SimpleProperties.dll from that folder into the C:\Dexterity folder.
Creating the C# Type Library and Registry File
Once the assembly is built, a COM type library must be built that describes the assembly so it can be accessed from COM. A registry file also must be created to allow access to the assembly from COM. To do this, use the Regasm utility loaded with Visual Studio .NET.
The Regasm utility normally is located at:
C:\WINDOWS\Microsoft.NET\Framework\v1.0.3705\Regasm.exe
The Regasm utility is used by command line execution to create these objects. The examples below assume that this path is set in the PATH environment variable. If not, then the location must be fully qualified.
Open a command prompt window. From the Start menu, choose Run, then enter cmd and click OK. A command prompt window will open. On the command line enter cd c:\dexterity to switch to the location of our SimpleProperties assembly.
Use the Regasm utility to register all of the public classes in the assembly. For example, enter the following command and press RETURN to register the SimpleProperties assembly:
regasm SimpleProperties.dll
Next, using the Regasm utility, create a registry file that describes the assembly. This file must be merged into the registry on your system. Enter the following command and press RETURN to create the .reg file for the SimpleProperties assembly:
regasm SimpleProperties.dll /regfile:SimpleProperties.reg
Lastly, a type library is created that contains the information for the exposed objects to COM. Using the Regasm utility, create a .tlb file that contains the definitions of the public types in the assembly. Enter the following command and press RETURN to create the .tlb file for the SimpleProperties assembly:
regasm SimpleProperties.dll /tlb:SimpleProperties.tlb
This is the type library you will reference from within Dexterity to access the capabilities made available through COM. When your application accesses the assembly you created with C#, the assembly and type library should be located in the same directory as Dexterity (Dex.exe) or the Runtime Engine (Dynamics.exe or Runtime.exe).
The SimpleProperties.reg file is now created, but the information in that file needs to be entered into the registry. To do this, enter the following command at the command line, and press RETURN:
SimpleProperties.reg
Alternatively, you can double-click the SimpleProperties.reg file to include it into the registry. In the dialog box that appears, click Yes to merge the registry information.
To close the Command Prompt window, enter exit and press RETURN.
Creating the Dexterity Application
Launch Dexterity
To test this assembly, a standalone Dexterity application will be built. Double-click Dex.exe to launch Dexterity, or from the Start menu choose Great Plains Dexterity, then click Dexterity. When prompted, select Create a new dictionary with Main Menu form. For this article, the path will be assumed to be C:\dexterity\app.dic. Click OK.
Adding Resources to the Application Dictionary
After the Dexterity Resource Explorer opens, expand the Base node in the tree view and select Libraries. Click the New button to open the COM Type Library Definition window.
In this window, click the Folder lookup button and choose the SimpleProperties.tlb file that was created in the previous section. Click OK to save this definition.
Next, in the Resource Explorer, select the Forms node in the tree view. In the right-hand pane there should be a form named Main Menu. Double-click the Main Menu item to open the Main Menu form in the Form Definition window. Click New to create a new window on the Main Menu form. The Layout window will open.
In the Layout window, create a new local button by selecting the Button item from the Toolbox and clicking on the Layout window. Double-click the new button to open the Script Editor window.
In the Script Editor, paste the following Dexterity code. Note that curly brackets are beginning and ending comment markers for the Dexterity scripting language and will be ignored by the compiler.
Script: Button Change Script
local SimpleProperties.ConvertDollars obj;
local text tText;
local string ReturnValue;
local integer x;
local string myarray[5]; {5 element string array}
obj = new SimpleProperties.ConvertDollars();
{obj initializes with dollars = 10 and cents = 25}
tText = tText + "Object initialized to: " + str(obj.dollars) _
+ "." + str(obj.cents) + char(13);
{switch the dollars to 15}
obj.dollars = 15;
{switch cents to 40}
obj.cents = 40;
tText = tText + "Dollars and cents switched to: " + str(obj.dollars) _
+ "."+ str(obj.cents) + char(13);
{Return a string property}
tText = tText + "Getting a string property returned: " _
+ str(obj.sAmount) + char(13);
{pass in a string and string array}
ReturnValue = obj.SetArray("Test Array",myarray);
{append to the output field the contents of the string array}
for x = 1 to 5 do
tText = tText + "Array Element " + str(x) + ": " _
+ myarray[x] + char(13);
end for;
{destroy the object}
clear obj;
{Display the results}
warning tText;
Click Compile to compile the Dexterity code and close the Script Editor. Close the Layout window and click Yes to save the changes. Lastly, click OK to close the Form Definition window.
Testing
To test this application, from the Debug menu, choose Test Mode, or press CTRL-T. Dexterity will switch to Test Mode and automatically open the Main Menu form. Press the button that was added in the previous section. The button script will be executed, invoking the ConvertDollars class created in the C# SimpleProperties assembly, and displaying a dialog box with the following results:
Object initialized to: 10.25
Dollars and cents switched to: 15.40
Getting a string property returned: $15.40
Array Element 1: one
Array Element 2: two
Array Element 3: three
Array Element 4: four
Array Element 5: five
Conclusion
By exposing managed .NET code to COM, a Microsoft Business Solutions Dexterity application can be extended to take advantage of the functionality and benefits of a .NET application.