Professional Documents
Culture Documents
Programmer’s Guide
Copyright Copyright © 2012 Microsoft Corporation. All rights reserved.
Limitation of liability This document is provided “as-is”. Information and views expressed in this document, including URL
and other Internet Web site references, may change without notice. You bear the risk of using it.
Some examples depicted herein are provided for illustration only and are fictitious. No real
association or connection is intended or should be inferred.
Intellectual property This document does not provide you with any legal rights to any intellectual property in any Microsoft
product.
You may copy and use this document for your internal, reference purposes.
Trademarks Microsoft, Dexterity, Microsoft Dynamics, Visual Basic, Visual Studio, Windows, Windows Server, and
Windows Vista are trademarks of the Microsoft group of companies.
Warranty disclaimer Microsoft Corporation disclaims any warranty regarding the sample code contained in this
documentation, including the warranties of merchantability and fitness for a particular purpose.
License agreement Use of this product is covered by a license agreement provided with the software product. If you have
any questions, please call the Microsoft Dynamics GP Customer Assistance Department at
800-456-0025 (in the U.S. or Canada) or +1-701-281-6500.
PROGRAMMER’S GUIDE i
C O N T E N T S
ii P R O G R A M M E R ’ S G U I D E
C O N T E N T S
iv P R O G R A M M E R ’ S G U I D E
INTRODUCTION
Introduction
Welcome to Visual Studio® Tools for Microsoft Dynamics® GP. This documentation
explains how to integrate applications you create with Visual Studio into Microsoft
Dynamics GP. Before you begin creating an integration for Microsoft Dynamics GP,
take a few moments to review the information presented here.
• Part 1, Getting Started, explains how to install Visual Studio Tools for Microsoft
Dynamics GP and begin creating an integration.
Prerequisites
You must be using Microsoft Dynamics GP 2013. Since you will be working with
Microsoft Dynamics GP, knowledge of the accounting system will be helpful.
Consult the Microsoft Dynamics GP documentation resources to learn more about
the product.
You will also want to install the SDK for Microsoft Dynamics GP. The SDK is
available in the Tools folder on the Microsoft Dynamics GP installation media. It
contains useful information about Microsoft Dynamics GP, such as lists of
commonly-used procedures and functions.
To use Visual Studio Tools for Microsoft Dynamics GP, Visual Studio 2010 or later
is required. Earlier versions of Visual Studio cannot be used. It is assumed that you
are familiar with programming in a managed language such as C#. This
documentation uses both C# and Visual Basic to demonstrate how to create
integrations.
2 P R O G R A M M E R ’ S G U I D E
IN T RO D U C T IO N
Symbol Description
The light bulb symbol indicates helpful tips, shortcuts,
and suggestions.
Margin notes summarize Margin notes call attention to critical information and
important information. direct you to other areas of the documentation where
a topic is explained.
Convention Description
Part 1, Getting Started Bold type indicates a part name.
Chapter 8, “Events” Quotation marks indicate a chapter name.
Adding controls Italicized type indicates a section name.
using System.IO; This font is used to indicate script examples.
Dictionary Assembly Acronyms are spelled out the first time they’re used.
Generator (DAG)
TAB or ALT+M Small capital letters indicate a key or a key sequence.
Product support
Microsoft Dynamics GP developer technical support can be accessed online or by
telephone. Go to www.microsoft.com/dynamics and click the CustomerSource or
PartnerSource link, or call 888-477-7877 (in the US and Canada) or 701-281-0555.
PROGRAMMER’S GUIDE 3
4 P R O G R A M M E R ’ S G U I D E
PART 1: GETTING STARTED
Part 1: Getting Started
This portion of the documentation describes how to get started creating an
integration using Visual Studio Tools for Microsoft Dynamics GP. The following
topics are discussed:
• Chapter 1, “SDK Installation,” explains how to install Visual Studio Tools SDK
for Microsoft Dynamics GP.
6 P R O G R A M M E R ’ S G U I D E
Chapter 1: SDK Installation
The Visual Studio Tools for Microsoft Dynamics GP SDK contains the components
needed to create and build integrations. The following topics are discussed:
• Installation procedure
• Template registration
• What was installed
• Upgrading to a newer Visual Studio
Installation procedure
The Visual Studio Tools for Microsoft Dynamics GP SDK installer requires Visual
Studio 2010 or later to be installed first. For testing integrations, you will also want
Microsoft Dynamics GP installed.
If you have installed an earlier version of the Visual Studio Tools SDK, be sure that you
remove it from the system before you install the new version.
To install the Visual Studio Tools for Microsoft Dynamics GP SDK, complete the
following procedure:
Feature Description
Visual Studio 2010 Templates The C# and Visual Basic templates for projects and forms.
Visual Studio 2010 is required to install this feature.
Visual Studio 2012 Templates The C# and Visual Basic templates for projects and forms.
Visual Studio 2012 is required to install this feature.
Documentation The Visual Studio Tools for Microsoft Dynamics GP
Programmer’s Guide.
Samples Sample integrations that demonstrate Visual Studio
Tools.
Assemblies and Assembly The Dictionary Assembly Generator (Dag.exe) and the
Generator dictionary assemblies for the products that ship with
Microsoft Dynamics GP. Also includes the IntelliSense
XML files used by Visual Studio to display information
about the resources accessed through the application
assemblies.
During the installation, Visual Studio must be reconfigured to recognize the new
templates being installed. This process may take a few minutes to complete.
PROGRAMMER’S GUIDE 7
PA RT 1 G E TT I N G S T A R TE D
Template registration
If you are running with limited user privileges or with User Account Control (UAC)
active, the templates installed for Visual Studio Tools may not be registered in
Visual Studio. You may need to manually register the templates so they will appear
as selections when you create new projects.
Use the following command for Visual Studio 2010 to re-create its template cache:
If you are using a 64-bit version of Windows, the Visual Studio files will be located in the
Program Files (x86) folder.
On systems that are running with UAC (User Account Control), you will need to set
the properties of the devenv.exe application to be run with administrative
privileges.
8 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 S D K I N S T A L L A T I O N
Component Description
VSTDGPReadme.rtf Contains late-breaking information about
Visual Studio Tools for Microsoft Dynamics
GP.
VSTDGPProgrammersGuide.pdf Documentation for Visual Studio Tools.
Samples.zip Sample Visual Studio projects that
demonstrate Visual Studio Tools.
Microsoft.Dexterity.Bridge.dll Core Microsoft Dynamics GP components
Microsoft.Dexterity.Shell.dll used by Visual Studio Tools integrations.
Microsoft.Dynamics.Framework.UI.Navigation.dll
Microsoft.Dynamics.Framework.UI.WinForms.
Controls.dll
Dag.exe The Dictionary Assembly Generator, used to
create application assemblies for application
dictionaries and forms dictionaries.
Bidi32.dll Support files needed for Dag.exe
Ddapi.dll
Tntlib.dll
Dex.dic
Dex.ini
Application Assemblies Assemblies that contain information about
the resources in each dictionary that is
shipped with Microsoft Dynamics GP. In
addition to US English, other local versions
of application assemblies are included.
IntelliSense XML files Used by Visual Studio to display information
about the corresponding application
assembly.
If you chose to install them, the project templates for C# and Visual Basic will be in
the appropriate locations for Visual Studio.
PROGRAMMER’S GUIDE 9
PA RT 1 G E TT I N G S T A R TE D
10 P R O G R A M M E R ’ S G U I D E
Chapter 2: Integration Basics
Before you create an integration using Visual Studio Tools for Microsoft Dynamics
GP, it will be helpful to understand the basics of an integration. The following
topics are discussed:
Customized WinForms
Any WinForms included in an integrating application can use capabilities provided
by Visual Studio Tools for Microsoft Dynamics GP to match the appearance of the
core application. The appearance of the window as well as the various controls in
the window can be customized. You will learn about creating windows for your
integration in Chapter 4, “WinForms,” and Chapter 5, “Control Reference.”
Access to events
Integrating applications can be notified of events that occur in Microsoft Dynamics
GP, such as a window being opened, or the focus moving to a field. The applications
can respond to the events, performing actions like verifying field values or opening
additional windows. Chapter 8, “Events,” contains information about registering
for and responding to events.
Architecture
Visual Studio Tools for Microsoft Dynamics GP consists of runtime components
and development components.
Runtime components
The runtime components for Visual Studio Tools are installed with Microsoft
Dynamics GP, and provide the functionality used by the integrations. These consist
of the following:
PROGRAMMER’S GUIDE 11
PA RT 1 G E TT I N G S T A R TE D
Visual Studio Tools for Microsoft Dynamics GP includes the application assemblies
for all the modules that ship with Microsoft Dynamics GP. You can use the
Dictionary Assembly Generator tool (Dag.exe) to create application assemblies for
other third-party dictionaries for Microsoft Dynamics GP. You will learn more
about this tool in Chapter 6, “Dictionary Assembly Generator.”
AddIns folder The assemblies for the integrating applications created with
Visual Studio Tools for Microsoft Dynamics GP are placed in this folder. When
Microsoft Dynamics GP is launched, it automatically looks in this folder and
attempts to launch the integrating applications it finds there.
Development components
The following development components are installed in the folder where you chose
to install Visual Studio Tools for Microsoft Dynamics GP:
IntelliSense XML files The IntelliSense XML file contains the information
about the application assembly that is displayed in the IntelliSense within Visual
Studio. The name of the application XML file matches that of the application
assembly it corresponds to. For example, the Application.Dynamics.xml file
contains information about the Application.Dynamics.dll assembly.
The following components are installed into the Visual Studio installation:
Visual Basic project This is the template project for an add-in that is based in
Visual Basic.
Visual C# project This is the template project for an add-in that is based in
Visual C#.
Creating a project
Use the following procedure to create a new Visual Studio project for a Microsoft
Dynamics GP add-in.
12 P R O G R A M M E R ’ S G U I D E
C H A P T E R 2 I N T E G R A T I O N B AS I C S
If the Microsoft Dynamics GP templates are not listed, you may need to register them
manually. Refer to Template registration on page 8 for details about doing this.
PROGRAMMER’S GUIDE 13
14 P R O G R A M M E R ’ S G U I D E
Chapter 3: Upgrading an Integration
If you have created an integration with Visual Studio Tools for an earlier release of
Microsoft Dynamics GP, use the following procedures to upgrade your integration
to work with the current version of Visual Studio Tools. Be sure you have installed
the current version of Visual Studio Tools before attempting to upgrade your
integrations. The following upgrade procedures are described:
C# integration
Use the following procedure to upgrade a Visual Studio Tools integration created
with C#.
If you do not target the .NET Framework 4, you will see numerous build errors when
you build your project.
PROGRAMMER’S GUIDE 15
PA RT 1 G E TT I N G S T A R TE D
Add references to the updated Visual Studio Tools assemblies, to replace the
broken references.
Microsoft.Dexterity.Shell.UI
Microsoft.Dexterity.Shell
16 P R O G R A M M E R ’ S G U I D E
C H A P T E R 3 U P G R A D I N G A N I N TE G R A T I O N
This means that the code used for the form is using the old namespace, rather
than the new Microsoft.Dexterity.Shell namespace. You must view the code for
the form, and change all of the namespace references to remove the “UI”
portion. This will be required in several places. An example of code to be fixed
is shown highlighted in the following illustration.
You may need to expand some hidden sections of the code to find all of the references.
After making these changes to the form’s code, save the updated file. Close the
form designer if it is still open, and then re-open the form. The form should now
open and have the updated Microsoft Dynamics GP appearance.
PROGRAMMER’S GUIDE 17
PA RT 1 G E TT I N G S T A R TE D
If you do not target the .NET Framework 4, you will see numerous build errors when
you build your project.
Add references to the updated Visual Studio Tools assemblies, to replace the
broken references.
Microsoft.Dexterity.Shell.UI
Microsoft.Dexterity.Shell
18 P R O G R A M M E R ’ S G U I D E
C H A P T E R 3 U P G R A D I N G A N I N TE G R A T I O N
After making these changes to the form’s code, save the updated file. Re-open
the form. The form should appear in the form designer and have the updated
Microsoft Dynamics GP appearance.
PROGRAMMER’S GUIDE 19
PA RT 1 G E TT I N G S T A R TE D
• For a Visual Basic project, display the project properties. In the Compile
group, click Advanced Compile Options. Set the Target framework (all
configurations) field to .NET Framework 4, and then click OK. In the
message displayed, click Yes to indicate that you want to make the change.
If you do not target the .NET Framework 4, you will see numerous build errors when
you build your project.
20 P R O G R A M M E R ’ S G U I D E
C H A P T E R 3 U P G R A D I N G A N I N TE G R A T I O N
If any of the references are not valid, remove and then re-add references to the
updated Visual Studio Tools assemblies to replace the incorrect references.
PROGRAMMER’S GUIDE 21
22 P R O G R A M M E R ’ S G U I D E
PART 2: DEVELOPING INTEGRATIONS
Part 2: Developing Integrations
This portion of the documentation describes the various techniques you will use as
you develop integrations using Visual Studio Tools for Microsoft Dynamics GP.
The following topics are discussed:
• Chapter 5, “Control Reference,” provides details of the various controls that are
modified by Visual Studio Tools for Microsoft Dynamics GP.
• Chapter 8, “Events,” describes how to register for and respond to events for
Microsoft Dynamics GP.
• Chapter 10, “Building and Deploying,” explains how to build and deploy an
integration you have created.
• Chapter 12, “Modified and Alternate Forms,” describes how to access resources
on modified forms and alternate forms in Microsoft Dynamics GP.
• Chapter 14, “Using Lookups,” describes how to use existing lookups from
Microsoft Dynamics GP in your Visual Studio Tools integration.
24 P R O G R A M M E R ’ S G U I D E
Chapter 4: WinForms
Standard WinForms are the basis for the user interface for add-ins created with
Visual Studio Tools for Microsoft Dynamics GP. These WinForms and the controls
placed on them are specially modified to match the appearance of Microsoft
Dynamics GP. Information about WinForms is divided into the following sections:
Choose a Microsoft
Dynamics GP Form.
PROGRAMMER’S GUIDE 25
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
WinForm properties
WinForms that are added to a Visual Studio Tools for Microsoft Dynamics GP
project have several additional properties that control their appearance. Setting
these properties correctly helps match the appearance of Microsoft Dynamics GP.
These properties are:
• AutoSetDexColors
• ControlArea
• StatusArea
These WinForm properties are found in the “Dexterity” group in the Properties pane in
Visual Studio.
AutoSetDexColors
The AutoSetDexColors property controls whether the colors used for the WinForm
will automatically match the color scheme selected in the user preferences within
Microsoft Dynamics GP. Set this property to True to match the Microsoft Dynamics
GP appearance.
ControlArea
The ControlArea property specifies whether the band called the control area is
drawn at the top of the WinForm. In standard Microsoft Dynamics GP windows,
controls such as Save, Clear, and Delete buttons are placed in the control area. Set
this property to True to display the control area for a WinForm.
StatusArea
The StatusArea property specifies whether the band called the status area is drawn
at the bottom of the WinForm. A divider line is drawn across the bottom of the
WinForm to indicate the status area. In standard Microsoft Dynamics GP windows,
controls like browse buttons, note buttons, and help buttons are placed in the status
area. Set this property to True to display the status area for a WinForm.
26 P R O G R A M M E R ’ S G U I D E
C H A P T E R 4 W I N F O R M S
Adding controls
You can add controls to the forms for your Microsoft Dynamics GP integration the
same way you add them to standard windows forms. Simply select the control in
the Toolbox and drag it out onto the form.
When you add the controls, additional properties will be available for some of them
to match the Microsoft Dynamics GP appearance. For example, push buttons will
have additional properties. Refer to Chapter 5, “Control Reference,” for more
information about individual controls.
PROGRAMMER’S GUIDE 27
28 P R O G R A M M E R ’ S G U I D E
Chapter 5: Control Reference
You can use any of the available controls on the WinForms for your Microsoft
Dynamics GP integration. Some of the standard controls have been customized to
better match the appearance of Microsoft Dynamics GP. This portion of the
documentation describes the controls that have additional properties or updated
characteristics when used on a WinForm in a Visual Studio Tools for Microsoft
Dynamics GP project. The following controls are discussed:
• Buttons
• TextBoxes
• Labels
• ComboBoxes
• ListBoxes
Buttons
Button controls are used for each of the button types in a Microsoft Dynamics GP
form. The button controls on a WinForm for a Microsoft Dynamics GP project get
their additional characteristics from the dexButtonProvider you see on the
WinForm layout. The ButtonType property is an additional property available for
each button. It specifies how the button control is displayed and what
characteristics it will have. You can set the AutoSetDexColors property to True so
the button colors will match colors in Microsoft Dynamics GP.
The following is a list of the settings for the ButtonType property, and a description
of how each button type is used.
Standard
Standard buttons don’t have their appearance modified changed when placed on a
WinForm for a Dynamics GP project. The following illustration shows a standard
button.
Toolbar
Buttons with the ButtonType set to Toolbar are typically placed in the control area
of a Microsoft Dynamics GP form. These buttons have a flat appearance, with a
special color highlighting when the pointer is placed over them. It is also common
for these buttons to have pictures on them. The following illustration shows a
toolbar button.
A toolbar button is
typically placed in the
control area.
PROGRAMMER’S GUIDE 29
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
ToolbarWithSeparator
The buttons with the type ToolbarWithSeparator buttons are typically placed in the
control area, like buttons with the type Toolbar. However, they have an additional
separator line drawn on the right side of the button to separate it from the other
controls in the control area. The following illustration shows two buttons that have
the type ToolbarWithSeparator. Notice the separator line drawn to the right of each
button.
StatusArea
Buttons placed in the status area at the bottom of a window should have the type
StatusArea. These buttons should display only graphics, and will have a special 3-D
border drawn around them when the pointer is placed over them. These buttons
should have the Tooltip property set so they will display a description of the action
the button performs. A status area button is shown in the following illustration. It
displays a tooltip that describes the purpose of the button.
Field
Buttons that show only pictures, and are placed next to other controls in the form
should have the ButtonType property set to Field. These buttons are used for things
like lookups or expansions. Several buttons with this type are shown next to a text
control in the following illustration.
30 P R O G R A M M E R ’ S G U I D E
C H A P T E R 5 C O N T R O L R E F E R E N C E
Window_NotePresent.png Used for the note button in the window status area.
TextBoxes
TextBox controls are used for the string, integer, currency, date, and time controls in
a Microsoft Dynamics GP form. Text boxes have the AutoSetDexColors property
that can be set to True so the control colors will match colors in Microsoft Dynamics
GP.
PROGRAMMER’S GUIDE 31
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Unlike the standard controls in Microsoft Dynamics GP, the textbox controls have
no built-in support to format data such as currency values. You will need to add
additional code to your integration to match the behavior of the controls in
Microsoft Dynamics GP. For instance, the following C# code sets the value of the
textbox in the previous illustration. It uses the Format method for the String object
to format the currency value.
Labels
Label controls are used for the text labels that appear next to controls in the
Microsoft Dynamics GP form. They correspond to the static text items that appear
in standard Microsoft Dynamics GP windows.
Label controls have the LinkField property that should be set when a specific field
is being labeled. This property is set to the name of the control that the label applies
to. When specified in the Microsoft Dynamics GP User Preferences, the label will be
drawn with the single underline that is standard for prompts.
To have the underlined label draw correctly, be sure the AutoSize property for the label is
set to False.
ComboBoxes
Use the ComboBox control in cases where you would use a drop-down list or
combo box in Microsoft Dynamics GP. ComboBox controls have the
AutoSetDexColors property that can be set to True so the control colors will match
colors in Microsoft Dynamics GP.
ListBoxes
Use the ListBox control in cases where you would used a list box or multi-select list
box in Microsoft Dynamics GP.
32 P R O G R A M M E R ’ S G U I D E
Chapter 6: Dictionary Assembly Generator
The Dictionary Assembly Generator (DAG.exe) is a utility included with Visual
Studio Tools for Microsoft Dynamics GP that creates a managed code assembly that
provides access to resources in an application dictionary. Information about this
tool is divided into the following sections:
When developing integrations that use resources from these dictionaries, always
use the application assemblies that are included with the Visual Studio Tools
installation. These assemblies are digitally signed, indicating they were produced
by Microsoft. Don’t generate your own versions of application assemblies for
dictionaries shipped with the Microsoft Dynamics GP product.
• A forms dictionary exists for a product, and you want your Microsoft Dynamics
GP integration to access the modified resources in the forms dictionary.
Output files
The Dictionary Assembly Generator produces two output files that are used in your
integration: an application assembly and IntelliSense data file.
Application assembly
The most important output is the application assembly. This is the managed code
assembly that provides access to the resources in a dictionary. Each dictionary can
have one corresponding application assembly.
Application.ProductName.dll
Application.ProductName.ModifiedForms.dll
ProductName is automatically derived from product name in the launch file. Any
spaces or special characters in the product name are removed.
PROGRAMMER’S GUIDE 33
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
For example, the application assembly that provides access to resources in the
SRVCADV.dic application dictionary is named Application.FieldService.dll. The
application assembly that provides access to the resources in the forms dictionary
(FRMS949.dic) is named Application.FieldService.ModifiedForms.dll.
If you are using a 64-bit version of Windows, the files will be located in the Program Files
(x86) folder.
To view the command syntax, use the following command at the command prompt:
dag.exe /?
The Dictionary Assembly Generator uses the product ID to identify the dictionary
for which you want to build the application assembly. Look in the launch file
(typically Dynamics.set) for a list of the products installed.
34 P R O G R A M M E R ’ S G U I D E
C H A P T E R 6 D I C T I O N A R Y A S S EM B L Y G E N ER AT O R
Optionally, you can specify the launch file that the Dictionary Assembly Generator
will look in to find the list of installed products and the corresponding dictionary
locations. If you don’t supply the name of the launch file, DAG.exe will look for the
launch file named Dynamics.set in the current location.
Since you are running DAG.exe from a different location than where Microsoft Dynamics
GP is installed, you will need to supply the complete path to the launch file.
The Dictionary Assembly Generator must be able to write to the location where it is being
run from. This means the user running DAG.exe must be part of the Administrators group
or the Power Users group. On a system running with User Account Control (UAC), it
means launching DAG.exe with Administrative privileges.
• Application.SampleIntegratingApp.dll
• Application.SampleIntegratingApp.xml
To generate an assembly for a forms dictionary, use the /F parameter. For example,
the following command generates the application assembly for the forms dictionary
of the Field Service product (with dictionary ID 949).
dag.exe 949 "C:\Program Files\Microsoft Dynamics\GP\Dynamics.set" /F
• Application.FieldService.ModifiedForms.dll
• Application.FieldService.ModifiedForms.xml
Refer to Modified forms on page 71 for details about creating an application assembly for the
forms dictionary (Forms.dic) used by Microsoft Dynamics GP.
After you create and use a strong name key file, keep it in a safe location. You will need to
use it every time you build or rebuild application assemblies.
The following example shows how the application assembly for the sample
integrating application is fully signed using the Sample.snk strong name key. The
Sample.snk file was generated using the SN.exe utility.
dag.exe 3333 "C:\Program Files\Microsoft Dynamics\GP\Dynamics.set" /M
/S:Sample.snk
PROGRAMMER’S GUIDE 35
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
For example, the following command will create an application assembly for the
sample integrating application, but use the name “Develop” instead of the product
name in the launch file.
For example, if the application assembly for the main dictionary was named
Application.DynamicsGP.dll, you would use the following command to create an
application assembly for the sample integrating application. Notice that the /NM
parameter is used to specify the name of the main application assembly that is being
referenced.
• Use the best hardware you have available to generate the application assembly.
36 P R O G R A M M E R ’ S G U I D E
Chapter 7: Accessing Dictionary Resources
To create an integration for Microsoft Dynamics GP or the additional applications
that are installed with it, your code must access resources in the various application
dictionaries. This portion of the documentation describes how to do this for your
project. The following topics are discussed:
• Adding references
• Namespace
• Dictionary class
• Accessing additional resources
• Variables for dictionary resources
Adding references
To access the resources in a specific dictionary, a project must contain a reference to
the application assembly for that dictionary. When you create a new Visual Studio
Tools for Microsoft Dynamics GP project, it will automatically contain a reference to
the Application.Dynamics.dll application assembly. This provides access to
resources in the Dynamics.dic dictionary. To access resources in other dictionaries,
add references to the application assemblies for them.
For example, to access resources from the “Sample Integrating App” application
installed with Microsoft Dynamics GP, the project should contain a reference to the
Application.SampleIntegratingApp.dll application assembly. The following
illustration shows this reference for a C# project.
PROGRAMMER’S GUIDE 37
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Namespace
Resources for a dictionary are accessed through the following namespace:
Microsoft.Dexterity.Applications
Dictionary class
The resources in a dictionary are accessed through a single class that is available
after you add the reference to the dictionary’s application assembly. The class has
the same name that appears in the application assembly. For instance, the class to
access resources for the Dynamics dictionary is named Dynamics. Similarly, the
class used to access resources for the Sample Integrating Application is named
SampleIntegratingApp. This is the same name that appears in the application
assembly, Application.SampleIntegratingApp.dll.
The five primary resource types in a dictionary are accessed through properties of
the class. These resource types are:
• Forms
• Globals
• Procedures
• Functions
• Tables
To access a resource of the specific type, start by typing the dictionary class name,
and then property for the resource type. IntelliSense in Visual Studio will present a
list of the specific type of resources available in the dictionary. For example, the
following illustration shows the forms resources in the Dynamics core application.
When you’ve selected a resource of the specific type, you will see a list of the
properties, methods, and events available for that resource. The following
illustration shows some of the properties, methods, and events for the AboutBox
form in the Dynamics dictionary.
38 P R O G R A M M E R ’ S G U I D E
C H A P T E R 7 A C C E S S I N G D I C T I O N A R Y R ES O U R C E S
• Windows
• Commands
• Form-level procedures
• Form-level functions
• Form-level table buffers
Dynamics.Forms.RmCustomerMaintenance.RmCustomerMaintenance.Open();
• Fields
• Scrolling windows
For instance, the following C# statement sets the value of the Comment 1 field in the
Vendor Maintenance window.
Dynamics.Forms.PmVendorMaintenance.PmVendorMaintenance.Comment1.Value
= "A preferred vendor";
You will learn more about the details about using each resource type in Part 3, Resource
Reference.
Microsoft.Dexterity.Applications.DynamicsDictionary
To reference resources for the Sample Integrating Application, you would use this
namespace:
Microsoft.Dexterity.Applications.SampleIntegratingAppDictionary;
After creating the variable, you can assign its value and then use it in your code. For
example, the following C# code creates a variable for the Vendor Maintenance form
in Microsoft Dynamics GP. It assigns the form to the variable, and then uses it to
open the form.
PmVendorMaintenanceForm VendorMaintenanceForm;
VendorMaintenanceForm = Dynamics.Forms.PmVendorMaintenance;
VendorMaintenanceForm.Open();
PROGRAMMER’S GUIDE 39
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Using a variable can simplify your code, especially when accessing dictionary
resources that have long names. For example, the following C# code creates a
variable for the Customer Maintenance window in Microsoft Dynamics GP. Then it
sets the values of two fields in the window. Notice it take less code to set the field
when the variable for the window is used.
// Accessing window fields requires less code when using the variable
CustMaintWindow.Comment1.Value = "Comment 1";
Dynamics.Forms.RmCustomerMaintenance.RmCustomerMaintenance.Comment2.Value =
"Comment 2";
40 P R O G R A M M E R ’ S G U I D E
Chapter 8: Events
Applications that integrate with Microsoft Dynamics GP often need to be notified
when specific events occur in the system. This portion of the documentation
describes how to register to be notified when events occur in the system. It also
describes how to write event handlers that can respond to the events. Information is
divided into the following sections:
• Registering events
• Responding to events
• Unregistering events
Registering events
Your integrating application must register every event that it should be notified of
in the system. Event registrations are added to the Initialize() method, located in
the template code that is automatically added when you created your Visual Studio
Tools for Microsoft Dynamics GP project.
The resources for which you can register events, such as forms, windows, or fields,
each list the events they make available. For example, a form has the following
events available:
• OpenBeforeOriginal
• OpenAfterOriginal
• CloseBeforeOriginal
• CloseAfterOriginal
Refer to each resource type described in Part 3, Resource Reference, for the list of
events that are available for that resource.
To register an event, find the resource for which you want to register the event. Pick
the event you want, and then specify the event handler method. The event handler
is the method that contains the code that runs in response to the event.
C#
Visual Studio will assist you when you register an event in C# code. Begin by
referencing the resource for which you want to register an event. Add the +=
operator, and Visual Studio will display IntelliSense indicating it will complete the
event handler. Simply press the TAB key to add the event handler registration.
PROGRAMMER’S GUIDE 41
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
After the event handler registration is added, Visual Studio will offer to add the
event handler method for the new event. Press the TAB key again to add the event
handler method. When you’re finished, the completed event will look similar to the
following:
Visual Basic
Registering an event in a Visual Basic project requires two steps. First, in the
Initialize() method of the project, the AddHandler statement registers the event.
The AddHandler statement takes two parameters. The first specifies the resource
and event, while the second specifies the event handler method that will be run. The
following example registers the AfterOpen event for the Customer Maintenance
form in Microsoft Dynamics GP.
AddHandler Dynamics.Forms.RmCustomerMaintenance.OpenAfterOriginal, _
AddressOf RMCustMaintAfterOpen
End Sub
In the second step, the event handler method is added. The parameters for this
method must match those required by the event. The IntelliSense for the event
displays the parameters the event handler must have.
The following example shows the event handler method added for the event
created in the previous example.
MsgBox("Not Implemented")
End Sub
42 P R O G R A M M E R ’ S G U I D E
C H A P T E R 8 E V E N T S
Responding to events
The event handler method contains the code that runs in response to the event. This
code can perform whatever action is required for your integrating application. For
example, the following C# code is the event handler that runs in response to the
value of the Sales Document Number field being changed in the Sales Transaction
Entry window. If the EstimateFreight form is open, the controls on the form are set.
void SopNumber_Change(object sender, EventArgs e)
{
// If the Estimate Freight form is open, update the document number
// and clear the other controls so the new calculation can be performed.
if (EstimateFreightForm.Created == true)
{
EstimateFreightForm.textBoxDocumentNumber.Text =
SOPEntryWindow.SopNumber.Value;
EstimateFreightForm.textBoxEstimatedFreight.Clear();
EstimateFreightForm.textBoxTotalWeight.Clear();
}
}
Event arguments
The event arguments for some events provide additional information about the
event. The event arguments for procedure events and function events allow access
to the parameters for the procedure or function call. For instance, the following C#
example is the event handler for InvokeAfterOriginal event for the
GetAutoComplete function in Microsoft Dynamics GP. The event arguments
contain the parameters that were passed into the function. The event handler
examines the value of the first parameter to verify that its value is “DYNSA”. If it is,
the code sets the result of the function to false.
void GetAutoComplete_InvokeAfterOriginal(object sender,
SyUserDefaultsForm.GetAutoCompleteFunction.InvokeEventArgs e)
{
// Set the return value to always turn off auto-complete for DYNSA user
if (e.inParam1 == "DYNSA")
{
e.result = false;
}
}
The event arguments for modal dialog events allow access to the buttons and
message displayed in the modal dialog. For example, the following Visual Basic
code is the event handler for the BeforeModalDialog event of the Sales Transaction
Entry window. It shows how the event arguments are used to examine the message
text displayed by the modal dialog, and then used to respond to the dialog.
Private Sub SopEntryWindow_BeforeModalDialog(ByVal sender As Object, ByVal e
As BeforeModalDialogEventArgs)
PROGRAMMER’S GUIDE 43
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Cancelling events
Some events can be cancelled through the event handler. Typically, these are events
that occur before the event in the core application, such as the OpenBeforeOriginal
event for a form. The event argument parameter that is passed to the event handler
for these events has a special type that allows the event to be cancelled.
For example, the following Visual Basic example is the event handler for the
BeforeOpen event of the Customer Maintenance form. The event handler method
examines the current user logged into the system. If it’s the “sa” user, a message is
displayed and the window isn’t opened. Notice how the event arguments are used
to cancel the event.
End If
End Sub
Unregistering events
At some point after you have registered an event, the event may no longer be
needed. To unregister an event, use the standard syntax for either C# or Visual
Basic. You can unregister the following types of events:
• Procedure events
• Function events
• Modal dialog events
The other types of events cannot be unregistered. If you try to unregister them, an exception
will be thrown.
C#
The following C# example shows how you would unregister an AfterModalDialog
event. The method named IvItemMaintenance_AfterModalDialog had been
registered as the event handler for the modal dialog event.
ItemMaintenanceForm.IvItemMaintenance.AfterModalDialog -= new
EventHandler<AfterModalDialogEventArgs>(IvItemMaintenance_AfterModalDialog);
44 P R O G R A M M E R ’ S G U I D E
C H A P T E R 8 E V E N T S
Visual Basic
The following Visual Basic example shows how you would unregister the
InvokeAfterOriginal event for the AddSuccessfulLoginRecord procedure. The
method named AddSuccessfulLogin had been registered as the event handler for
the procedure event.
RemoveHandler Dynamics.Procedures.AddSuccessfulLoginRecord.InvokeAfterOriginal, _
AddressOf AddSuccessfulLogin
PROGRAMMER’S GUIDE 45
46 P R O G R A M M E R ’ S G U I D E
Chapter 9: Working with Tables
A Visual Studio Tools integration can interact directly with tables defined in
Microsoft Dynamics GP. Using the table integration capability is much simpler than
creating and managing external connections to the Microsoft Dynamics GP
database. Information about working with tables is divided into the following
sections:
PROGRAMMER’S GUIDE 47
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
IntelliSense
The IntelliSense available in Visual Studio will be helpful by listing what tables are
available, as well as which fields are available in those tables.
Table buffers
A table buffer provides access to one row of a specific table. The information in the
table buffer comes from either the table or a script that has run. Your code will
interact with the table buffer when you perform operations on the table. There are
two types of table buffers: global and form-level.
A global table buffer is created when a table is accessed directly through the global list
of tables. Global table buffers are accessed through the dictionary class. This class
has a Tables property that provides access to the collection of tables defined in the
dictionary. A global table buffer is not associated with any specific form. This
makes global table buffers useful in situations where a Visual Studio Tools
integration must read from or write to a Dynamics GP table, but isn’t interacting
with the user interface.
By default, a global table buffer for a table is shared with all of the other Visual
Studio Tools add-ins that are accessing that same table. If you want your integration
to create a global table buffer that is not shared, use the Clone() method when
creating the instance of the global table buffer.
48 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
Form
Dynamics GP
Window
Dynamics GP Tables
When your integrating application’s code has finished working with a global table
buffer, it must be closed using the Close() method for the table. Failing to close a
global table buffer will cause a “Background process is running: Exit Aborted” error
when the user attempts to exit Microsoft Dynamics GP.
For form-level table buffers, the table buffer will be closed when the form is closed.
Explicitly closing a form-level table buffer with the Close() method is needed rarely.
The following C# example shows how a table is accessed through a global table
buffer. The first row of the table (the RM Customer Master table) is retrieved, and
the customer number is displayed. Notice how the table buffer is closed at the end
of the example.
RmCustomerMstrTable CustomerMasterTable;
CustomerMasterTable = Dynamics.Tables.RmCustomerMstr;
PROGRAMMER’S GUIDE 49
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Keys
A key is a field or combination of fields in a table that is used to sort and locate
specific rows in the table. Typically, the value of the key field or fields is unique for
each row in a table so a specific row can be located. Keys that don’t uniquely
identify a specific row are used to refer to a range of rows in the table.
The keys for a table are identified by number, beginning with the value 1. When
you specify the key you want to use for a table, you will supply the corresponding
integer. The Table Descriptions window in Microsoft Dynamics GP lists the keys for
each table, and the key segments (fields) that each key contains.
You will use the keys for a table when you retrieve a specific row from the table.
This is described in the next section, Retrieving a row. You will also use keys when
you want to perform operations on a range of rows in the table. You will learn more
about this in Ranges on page 55.
Retrieving a row
Retrieving a row from a table is a multi-step process. First, you must decide which
key you want to use to retrieve the row. Use the Table Descriptions window in
Microsoft Dynamics GP to view the keys and each key’s components. Specify the
key to use, and then set the values of the key fields. Finally, use the Get() or
Change() method for the table to retrieve the record. Which you use depends on
whether you want to lock the record. You will learn more about locking in Row
locking on page 59.
The following C# example retrieves the row for the customer American Electrical
Contractor from the RM_Customer_MSTR table. The second key of the
RM_Customer_MSTR table is used. This key contains one component, the
Customer Name. The contact person for the retrieved customer is displayed in a
dialog.
50 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
if (err == TableError.NoError)
{
MessageBox.Show(CustomerMasterTable.ContactPerson.Value);
}
else
{
// Display the error that occurred
MessageBox.Show(err.ToString());
}
// Close the table
CustomerMasterTable.Close();
Saving a row
To save a new row in a table, set the fields in the table to the values you want to
save. Then use the Save() method to save the new row in the table. The following C#
example adds a new row to the GL_Account_Category_MSTR table. It sets the
values for the fields in the table, then saves the new row.
if(err == TableError.Duplicate)
{
MessageBox.Show("Account category already exists");
}
PROGRAMMER’S GUIDE 51
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Updating a row
To update a row in a table, first read the row with the Change() method. This
retrieves the row and locks it, allowing you to make changes. Set the values of the
fields you want to change for the row. Finally, use the Save() method to save the
changed row back to the table.
The following C# example reads the row for Adam Park Resort. The Contact Person
for this row is changed the “Steve K.” Then the row is saved back to the
RM_Customer_MSTR table.
// Attempt to read the row. The Change() method will lock the row.
err = CustomerMasterTable.Change();
if (err == TableError.NoError)
{
// The row was read successfully, so update the value
CustomerMasterTable.ContactPerson.Value = "Steve K.";
if (err != TableError.NoError)
{
MessageBox.Show("An error occurred updating the row: " +
err.ToString());
}
}
else
{
MessageBox.Show("An error occurred retrieving the row to update: " +
err.ToString());
}
52 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
Removing a row
To remove a row from a table, first read the row with the Change() method. This
retrieves the row and locks it. Then use the Remove() statement to remove the row
from the table.
The following C# example reads and locks the row for the inventory item
“WIRE100” in the IV_Item_MSTR table. If the item is successfully read, it is
removed from the table.
// Attempt to read the row. The Change() method will lock the row.
err = ItemMasterTable.Change();
if (err == TableError.NoError)
{
// Attempt to remove the row
err = ItemMasterTable.Remove();
if (err != TableError.NoError)
{
MessageBox.Show("An error occured removing the row: " +
err.ToString());
}
}
PROGRAMMER’S GUIDE 53
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Constant Description
Changed The row being saved was changed by another user.
DatabasePermissionViolation The current user does not have security privileges to access
the table.
DoubleLock A row was already locked in the table buffer.
Duplicate The row being saved already exists in the table.
EndOfTable The row cannot be retrieved because the beginning or end of
the table has been reached.
InvalidKeyNumber The table does not have a key with the number specified.
NoError No error occurred.
NoLock An operation such as Remove() was performed, but no row
had been locked.
NotFound The row was not found in the table.
NotSupported The table operation is not supported for the table. For
example, attempting to actively lock a row on a table that
doesn’t allow it.
Sharing The row is actively locked by another user.
TooManyOpenTables Too many tables are open in the application.
Unknown An unknown error occurred.
Typically, your code will do one or both of the following after each table operation:
• Check for the NoError value, indicating the table operation was successful. If
the operation was successful, the next processing step can continue.
• Check for a specific error, such as NotFound. The code must respond
appropriately, such as displaying a message for the user.
If an unexpected error occurs after performing a table operation, it’s always a good
idea to display the details of the error to the user. Include information such as the
table, the operation being performed, and the error that occurred.
When a table operation error occurs, your code won’t follow the typical code path. Be sure
that your code closes any tables it has accessed. Otherwise, the user won’t be able to exit
Microsoft Dynamics GP.
54 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
Ranges
When working with tables, it is often efficient to limit the amount of information
being accessed. You can do this by setting up a range for the table. A range is based
on a key for the table, and allows you to access a specified portion of the rows in the
table. The selected range will be treated as an entire table. For instance, calling the
GetFirst() method returns the first row in the range. Calling the GetLast() method
returns the last row in the range, and so on.
You use the RangeStart() and RangeEnd() methods to specify the range for a table.
You can specify one range per table, and the range is associated with a specific key.
The range will be used only when the table is accessed using the key the range is
associated with. To clear the range specified for a table, use the RangeClear()
method.
if (err == TableError.NoError)
{
MessageBox.Show("First customer: " +
CustomerMasterTable.CustomerName.Value);
}
else
{
MessageBox.Show("An error occured retrieving the row: " +
err.ToString());
}
PROGRAMMER’S GUIDE 55
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
if (err == TableError.NoError)
{
MessageBox.Show("Last customer: " +
CustomerMasterTable.CustomerName.Value);
}
else
{
MessageBox.Show("An error occured retrieving the row: " +
err.ToString());
}
For example, the following C# code creates a range for the IV_Item_MSTR table that
includes only items in the COMPONENTS class. The range is created using key 3
for the Item Master table. This key has two segments: Item Class Code and Item
Number.
To set the beginning of the range, the Clear() method is used to set the fields in the
IV_Item_MSTR table buffer to the minimum value. The Item Class Code field in the
table buffer is set to “COMPONENTS”. The RangeStart() method specified this is
the beginning of the range.
To set the end of the range, the Fill() method is used to set the fields in the
IV_Item_MSTR table buffer to the maximum value. The Item Class Code field in the
table buffer is set to “COMPONENTS”. The RangeEnd() method specifies this is the
end of the range.
The key values for the range are shown in the following illustration. The range will
include rows where the Item Class Code value is “COMPONENT” and the Item
Number can be any value.
56 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
err = ItemMasterTable.GetFirst();
while(err == TableError.NoError)
{
// Add the item to the list
itemList.AppendLine(ItemMasterTable.ItemNumber + " " +
ItemMasterTable.ItemDescription);
The following C# example deletes all customer information for St. Patrick’s
Hospital. A single row must be deleted from the RM_Customer_MSTR and the
RM_Customer_MSTR_SUM tables. Several rows must be deleted from the
RM_Customer_MSTR_ADDR table. A range is used to remove the rows from this
table.
PROGRAMMER’S GUIDE 57
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
RmCustomerMstrSumTable CustomerMasterSummaryTable;
CustomerMasterSummaryTable = Dynamics.Tables.RmCustomerMstrSum;
RmCustomerMstrAddrTable CustomerMasterAddressTable;
CustomerMasterAddressTable = Dynamics.Tables.RmCustomerMstrAddr;
58 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
Row locking
A row must be locked to delete it or save any changes made to it. A lock is applied
when a row is read from a table. Two types of locked can be used: passive and
active.
Passive locking
A passive lock allows other users to access the row. They can delete the row or make
changes to it. Passive locking ensures that other users accessing the row can be
made aware that the row has been deleted or that the contents of the row have
changed. A pasive lock is applied every time a row is read using the Change()
method.
The Get() method is used only to read a row. It never locks the row.
Active locking
An active lock allows other users to read the row, but not make any changes or delete
the row. Active locking ensures that the user who has the active lock is the only user
who can make changes or delete the row. If other users try to delete or change the
row, they will receive a sharing error. An ative lock is applied each time a row is
read using the Change() method and the activeLock parameter for the method is set
to true.
Not all tables in Microsoft Dynamics GP allow active locking. If you try to actively lock a
row on a table that doesn’t support it, a NotSupported error will be returned.
Releasing locks
Any of the following actions release a row lock:
• Using the Save() method or the Remove() method, regardless of whether the
method was successful.
If a row is currently locked in a table buffer, and you attempt to lock another row,
you will receive an DoubleLock error that indicates a row was already locked.
Multiuser processing
Microsoft Dynamics GP supports multiple users accessing the same table at the
same time. This is accomplished through Optimistic Concurrency Control (OCC), a
form of record locking that allows multiple users to work in the same tables and
access the same rows with minimal restrictions, while helping to ensure data
integrity.
PROGRAMMER’S GUIDE 59
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
The following table lists the various locking scenarios that can occur. The events
listed happen in order from left to right. For example, in the first row User A
passively locks a row, then User B passively locks the same row. User A deletes the
row, then User B changes the contents of the row and saves the row. The changes
User B made will be saved.
Use the error value returned from the various table operations like Save() or
Remove() to trap errors so your code can deal with the errors that occur. The
following examples show how to trap for multiuser errors when reading, saving
and removing records.
You should not check for multiuser error conditions on tables containing text fields. Text
fields are those that store text up to 32,000 characters long. Multiuser error codes are not
properly returned for tables containing text fields.
60 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
Example 1
The following C# example reads and actively locks the first row in the
RM_Sales_WORK table. It uses the value returned from the ChangeFirst() method
to handle the Sharing error resulting from the row being actively locked by another
user.
// Variable for any table operation error
TableError err;
Example 2
The following C# example reads the first row of the RM_Customer_MSTR table,
changes the Salesperson ID, and attempts to save the changed row. The return
value from the Save() method is used to handle an error resulting from the row
being changed or actively locked by another user.
// Variable for any table operation error
TableError err;
PROGRAMMER’S GUIDE 61
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
if (err != TableError.NoError)
{
MessageBox.Show("Customer could not be updated.");
}
}
else if (err == TableError.Sharing)
{
MessageBox.Show("This row is actively locked by another user. Changes will
not be saved.");
}
else if (err != TableError.NoError)
{
// Some other table error occurred
MessageBox.Show("An error occured updating the customer: " +
err.ToString());
}
Example 3
The following script reads the last row in the GL_Account_Category_MSTR table
and attempts to delete it. The error value returned from the Remove() method is
used to handle an error resulting from the row being actively locked or already
deleted by another user.
if (err == TableError.NoError)
{
// Row was read and can be removed
err = AccountCategoryMasterTable.Remove();
if (err == TableError.Sharing)
{
62 P R O G R A M M E R ’ S G U I D E
C H A P T E R 9 WO R K IN G WIT H T A B LE S
PROGRAMMER’S GUIDE 63
64 P R O G R A M M E R ’ S G U I D E
Chapter 10: Building and Deploying
This portion of the documentation describes how to build and deploy an integration
created with Visual Studio Tools for Microsoft Dynamics GP. Information is
divided into the following sections:
• Title
• Description
• Company
• Major, minor, and build numbers
C# application
For integrations written in C#, the assembly information is set in the
AssemblyInfo.cs source file for the project. The following portion of this file shows
the various name values that should be set.
The following portion of this file shows the version, build, and revision numbers
that should be set.
PROGRAMMER’S GUIDE 65
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Building an integration
To build the integration, complete the following procedure:
66 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 0 B U I LD IN G A N D D EP LO Y IN G
Deploying an integration
When deploying your integration built with Visual Studio Tools for Microsoft
Dynamics GP, be sure that you include the following:
• Any additional application assemblies you generated that are specific to your
integration.
PROGRAMMER’S GUIDE 67
68 P R O G R A M M E R ’ S G U I D E
Chapter 11: Debugging
When developing an integrating application, you may find it necessary to examine
the code with the Visual Studio debugger. Information about debugging your
Microsoft Dynamics GP integration is divided into the following sections:
• Preparing to debug
• Examining the application
• Disabling events
Preparing to debug
To prepare your integrating application for debugging, complete the following
procedure.
Click Attach to attach to the process. Control will be returned to Visual Studio.
PROGRAMMER’S GUIDE 69
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
4. Finish debugging.
When you have finished debugging your integrating application, choose Stop
Debugging from the Debug menu in Visual Studio.
Disabling events
In some cases, you may want to disable the events for the Visual Studio Tools add-
ins to confirm whether they are causing some specific behavior in the Microsoft
Dynamics GP application. To disable events, use the Customization Status window
in Microsoft Dynamics GP. To open this window, point to Customize in the Tools
menu, and then choose Customization Status. Select the Microsoft Dynamics GP
product, and then click Disable. Be sure to enable the events after you have
completed your tests.
70 P R O G R A M M E R ’ S G U I D E
Chapter 12: Modified and Alternate Forms
To access modified or alternate forms from a Visual Studio Tools for Microsoft
Dynamics GP, a special process is used. This portion of the documentation
describes the steps necessary. Information is divided into the following sections:
• Modified forms
• Alternate forms
• Guidelines
Modified forms
Modified forms contain modifications that have been made with the Modifier. To
access these modifications from your Visual Studio Tools for Microsoft Dynamics
GP project, complete the following procedure:
The /N option is necessary because the application assembly uses the name
“Dynamics”, while the product name in the launch file is “Microsoft Dynamics GP”.
DynamicsModified
PROGRAMMER’S GUIDE 71
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
The following C# code sets the value of a new field on the Credit Limit window of
the Customer Maintenance form. The new field is a local field, added with the
Modifier, and named “Test”.
DynamicsModified.Forms.RmCustomerMaintenance.RmCreditLimit.LocalTest.Value =
"Modified Field";
When accessing resources that are defined in the main dictionary for an application, access
them through the main dictionary class, rather than through the “Modified” class for the
application.
Alternate forms
Alternate forms are forms from the core Dynamics dictionary that have been
changed by a third-party developer, and are stored in a third-party dictionary. The
new and changed resources for the alternate form are accessed through the third-
party application’s application assembly. To access alternate forms from you Visual
Studio Tools for Microsoft Dynamics GP project, complete the following procedure:
SampleIntegratingApp
72 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 2 M O D IFI ED A N D AL T ER N AT E F O R M S
The following C# code sets the value of a new field on the Vendor Maintenance
window of the alternate version of the Vendor Maintenance form, which is part of
the Sample Integrating App dictionary. The new field is a local field named “Test”.
SampleIntegratingApp.Forms.PmVendorMaintenance.PmVendorMaintenance.
LocalTest.Value = "Alternate Field";
Guidelines
If you are planning to use Visual Studio Tools for Microsoft Dynamics GP to
develop an integration for general distribution, we recommend that you limit the
references to resources on modified or alternate forms. Because of security settings,
a specific user may not have access to the modified or alternate version of a form,
possibly causing errors in your integration. If you do distribute an integration
which accesses modified or alternate forms, be sure that your code properly
handles cases when these resources are not available.
For instance, when you set or retrieve the value of a field, use a try...catch block to
enclose the statements. This allows your code to catch any exceptions that are
thrown because the field cannot be accessed. The following C# example shows how
a field in window for an alternate version of the Vendor Maintenance form can be
set within a try...catch block.
PROGRAMMER’S GUIDE 73
74 P R O G R A M M E R ’ S G U I D E
Chapter 13: Implementing Macro Support
You can add macro support for the forms you create with Visual Studio Tools.
Information about doing this is contained in the following sections:
• You must add calls to the RecordMacroItem() method in the appropriate places
in your Visual Studio Tools add-in to record macro commands for your form.
• You must override the PlayMacroItem() method in the DexUIForm base class,
and add code to support playback of your macro commands.
• If your Visual Studio Tools form makes asynchronous calls to other processes
that the macro system will need to wait for, you will need to override the
IsAsynchEventPending() method.
Recording macros
In your Visual Studio Tools form, identify the places that the user can perform
actions. Actions include things like clicking buttons, adding text to text fields, or
moving the focus. In the events that run due to these user actions, you will add code
that calls the RecordMacroItem() method to record a text string and optional
comment that identify and describe the action. For example, the following C# code
records a macro command for the Energy Star check box:
The text strings passed to the RecordMacroItem() method are written to the macro
as ShellCommand macro statements.
The RecordMacroItem() method records values only when a macro is being recorded.
Macro syntax
The text string and optional comment recorded in the macro are the only
information available to your Visual Studio Tools add-in when the macro is played
back. These text strings must contain enough information for your code to
determine the action that must be performed.
There is no predefined syntax for the text strings recorded. You must define the text
strings so that they can be parsed by your add-in, and then the add-in can perform
the actions indicated. The macro support in the Environmental Details Visual Studio
Tools sample is a good starting point. The syntax of its macro statements is similar
to the standard Microsoft Dynamics GP macro language.
PROGRAMMER’S GUIDE 75
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Placement
Where you place the RecordMacroItem() calls in your code can affect how data is
written to the macro. Some experimenting may be required to find which event for a
control is most appropriate for recording a macro action. For example, when
recording the text entered into a text box control, the Validating event is the most
appropriate place for the RecordMacroItem() call. The following C# example shows
the Validating event for the YearlyEnergyCost text box in the Environmental Details
sample.
The following table lists the event where the macro recording code should be placed
for common controls.
Control Event
Text box Validating
Push Button Click
Check box Validating
Playing macros
When a ShellCommand macro statement is played back, and your Visual Studio
Tools form is active, the PlayMacroItem() method will be called. You must override
this method in your Visual Studio Tools add-in code, and process the macro
statements for your form. The following C# example shows how you override the
base method.
Event arguments
The following event arguments are passed into the PlayMacroItem() method:
Handled This is a boolean parameter that indicates whether the action for macro
statement has been performed. You should check the value of this parameter at the
beginning of your PlayMacroItem() method. If its value is true, the macro statement
has already been handled, so your code should take no action. If you determine that
your code should perform the action for the macro statement, set the Handled
parameter to true when the action is complete. This tells other code that the macro
statement has already been processed.
MacroText This string parameter contains the macro string that was written by
the RecordMacroItem() method when the macro was recorded. You will need parse
this string to determine whether your add-in must perform the macro action.
76 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 3 IM P L EM EN T IN G M A CRO S U PP O R T
MacroComment This string parameter contains the comment that was written
by the RecordMacroItem() method when the macro was recorded.
if (e.Handled == false)
{
// Process Yearly Energy Cost text box
m = Regex.Match(e.MacroText, "TypeTo YearlyEnergyCost \"(.+)\"");
if (m.Success)
{
if (m.Groups.Count >= 2)
{
textBoxYearlyEnergyCost.Focus();
textBoxYearlyEnergyCost.Text = m.Groups[1].Value;
e.Handled = true;
}
}
PROGRAMMER’S GUIDE 77
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
// Close button
if (m.Groups[1].Value == "CloseButton")
{
buttonClose.Focus();
buttonClose.PerformClick();
e.Handled = true;
}
}
}
}
// Macro command was not ours, so let the base class process it.
base.PlayMacroItem(e);
}
Override the IsAsynchEventPending() method only if your Visual Studio Tools add-in has
asynchronous processes that the macro system must wait for.
The following C# example shows how you override the method from the base class.
Typically, you will create your own flag that tracks whether your add-in is running
an asynchronous process. In the IsAsynchEventPending() method, you will return
the value of this flag. When the asynchronous process starts, you will set the flag to
true. This causes the macro system to wait for the asynchronous event. When the
asynchronous process finishes, you will set the flag to false. This will allow the
macro system to resume processing.
78 P R O G R A M M E R ’ S G U I D E
Chapter 14: Using Lookups
Lookups are special-purpose windows used to retrieve existing ID values for
objects in Microsoft Dynamics GP, such as customers, vendors, and sales
documents. You may need to retrieve ID values for your Visual Studio Tools
integration. In many cases, you can use the lookups defined in Microsoft Dynamics
GP to retrieve ID values for fields on your Visual Studio Tools form. Information
about using lookups is divided into the following sections:
The following steps describe the basic operation of a lookup for a Visual Studio
Tools integration:
1. Add code to track that your integration has opened the lookup.
Lookup forms can be opened by the core Microsoft Dynamics GP application,
and by other integrating products. Your Visual Studio Tools integration must
track that it has opened the lookup, so it will know to retrieve the value that
was selected by the user.
PROGRAMMER’S GUIDE 79
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
Available lookups
Several different patterns have been used to code the lookup forms in Microsoft
Dynamics GP. Each pattern requires a specific technique to use the lookup. To learn
what lookups are available and how to call them, refer to the document titled
“Calling Lookup Forms from Dexterity” in the Microsoft Dynamics GP SDK. The
link for this document is found in the Foundation group of the Procedures and
functions section of the Microsoft Dynamics GP SDK help file.
The Lookups sample, described in Chapter 29, “Lookups,” demonstrates how to use several
common lookup forms in a Visual Studio Tools integration.
In some cases, Visual Studio Tools cannot access all of the resources required to use
the lookup form. For example, some lookup forms are opened by calling procedures
that have reference parameters. Because Visual Studio Tools cannot call procedures
with reference parameters, these lookup forms cannot be used with Visual Studio
Tools integrations.
Lookup example
The following example shows how to use the Customers and Prospects lookup
form in Microsoft Dynamics GP to retrieve customer numbers for a Visual Studio
Tools integration.
• The flag is set that indicates the lookup was opened by the Visual Studio
Tools integration.
80 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 4 U S I N G L O O K U P S
PROGRAMMER’S GUIDE 81
PA RT 2 D E V E L O PI N G I N TE G R A T I O N S
82 P R O G R A M M E R ’ S G U I D E
PART 3: RESOURCE REFERENCE
Part 3: Resource Reference
This portion of the documentation provides detailed information about each type of
resource you can access with Visual Studio Tools for Microsoft Dynamics GP. Each
resource has the following:
84 P R O G R A M M E R ’ S G U I D E
Chapter 15: Forms
Forms are the basic resource of the Microsoft Dynamics GP application. They
provide the organization for the interface presented to the user. The following items
for forms are discussed:
• Accessing forms
• Form methods
• Form properties
• Form events
Accessing forms
Forms for an application dictionary are accessed through the dictionary class. This
class has a Forms property that provides access to the collection of forms in the
dictionary. The dictionary class for the application dictionary is located in the
following namespace:
Microsoft.Dexterity.Applications
For instance, to access the collection of forms in the Dynamics dictionary, use the
following syntax:
Microsoft.Dexterity.Applications.Dynamics.Forms
To access a specific form, such as the Sales Transaction Entry form (SopEntry), use
the following syntax:
Microsoft.Dexterity.Applications.Dynamics.Forms.SopEntry
Form methods
Forms provide the following methods:
• AddMenuHandler()
• Close()
• Dispose()
• Open()
AddMenuHandler()
The AddMenuHandler() method adds a menu item to the “Additional” menu that
appears in windows in Microsoft Dynamics GP. The menu item will be available
when the form is open. This method takes three parameters:
EventHandler – The function that will be run when the menu item is chosen in
Microsoft Dynamics GP.
MenuItemName – A string containing the text that will be displayed for the menu
item.
PROGRAMMER’S GUIDE 85
PA RT 3 R E S O U R C E R E F E R E N C E
The following C# example shows how a menu handler for the “Estimate Freight”
menu item is added to the SopEntry form in Microsoft Dynamics GP:
Dynamics.Forms.SOPEntry.AddMenuHandler(OpenEstimateFreight,
"Estimate Freight", "F");
This code is the event handler for the menu item. Notice that it takes two arguments
like standard event handlers.
The following Visual Basic example shows how the same menu handler for the
“Estimate Freight” menu item is added to the SopEntry form in Microsoft Dynamics
GP.
This code is the event handler for the menu item. Notice that it also takes two
arguments like standard event handlers.
86 P R O G R A M M E R ’ S G U I D E
C H A PT E R 1 5 F O R M S
Close()
The Close() method closes the form.
Dispose()
The Dispose() method releases the memory used for the form after it is no longer
needed.
Open()
The Open() method attempts to open the form.
Form properties
Forms provide the following properties:
• Commands
• Functions
• IsOpen
• IsChanged
• Procedures
Commands
The Commands property provides access to the list of commands that are defined
by the form. Refer to Chapter 21, “Commands,” to learn more about using
commands in your application.
Functions
The Functions property provides access to the list of form-level functions that are
defined by the form. Refer to Chapter 24, “Functions,” for more information about
functions.
IsChanged
The IsChanged property has the value true if the change flag for the form is set, and
false if it is not. The change flag is automatically set to true when any field value for
the form has changed.
IsOpen
The IsOpen property has the value true if the form is open, and false if it is not.
Procedures
The Procedures property provides access to the list for form-level procedures that
are defined by the form. Refer to Chapter 23, “Procedures,” to learn more about
using procedures.
Tables
The Tables property provides access to the list of tables that are attached to the
form. Refer to Chapter 9, “Working with Tables,” and Chapter 19, “Tables,” for more
information about using the tables attached to forms.
PROGRAMMER’S GUIDE 87
PA RT 3 R E S O U R C E R E F E R E N C E
Form events
Forms provide the following events:
• OpenBeforeOriginal
• OpenAfterOriginal
• CloseBeforeOriginal
• CloseAfterOriginal
OpenBeforeOriginal
This event occurs when the form is opened, but before the form’s open event is run.
This event can be canceled.
OpenAfterOriginal
This event occurs when the form is opened, but after the form’s open event is run.
CloseBeforeOriginal
This event occurs when the form is closed, before the form’s close event is run. This
event can be canceled.
CloseAfterOriginal
This event occurs when the form is closed, after the form’s close event is run.
88 P R O G R A M M E R ’ S G U I D E
Chapter 16: Windows
Windows are a part of form in Microsoft Dynamics GP. They display the user
interface for the application. The following items are discussed:
• Accessing windows
• Window methods
• Window properties
• Window events
Accessing windows
Windows for an application dictionary are accessed as properties of the form that
they are contained in. For example, the Sales Transaction Entry window (SopEntry)
is part of the SopEntry form. To access it, you would use the following syntax:
Dynamics.Forms.SopEntry.SopEntry
The IntelliSense in Visual Studio will tell you what form and window in Microsoft
Dynamics GP are being referred to by the expression.
Window methods
Windows provide the following methods:
• Close()
• Open()
• PullFocus()
Close()
The Close() method closes the window.
Open()
The Open() method attempts to open the window.
PullFocus()
The PullFocus() method will remove the focus from the current window. No item
in the window will be focused. Any pending “validate” or “leave” events for the
currently-focused field will be run. Use this method in situations where you want
all of the pending actions to be run before your integrating application performs its
processing.
Window properties
Windows provide the following properties:
• IsChanged
• IsOpen
IsChanged
The IsChanged property has the value true if the change flag for the form is set, and
false if it is not. The change flag is automatically set to true when any field value for
the window has changed.
IsOpen
The IsOpen property has the value true if the window is open, and false if it is not.
PROGRAMMER’S GUIDE 89
PA RT 3 R E S O U R C E R E F E R E N C E
Window events
Windows provide the following events:
• OpenBeforeOriginal
• OpenAfterOriginal
• ActivateBeforeOriginal
• ActivateAfterOriginal
• CloseBeforeOriginal
• CloseAfterOriginal
• PrintBeforeOriginal
• PrintAfterOriginal
• BeforeModalDialog
• AfterModalDialog
OpenBeforeOriginal
This event occurs when the window is opened, but before the window’s open event
is run. This event can be canceled.
OpenAfterOriginal
This event occurs when the window is opened, but after the window’s open event is
run.
ActivateBeforeOriginal
This event occurs each time the window becomes active, before the window’s
activate event is run. The activate event occurs every time the window is opened or
brought to the front by the user. It occurs after the Open event.
The Activate event must be used cautiously. It shouldn’t perform any actions that can cause
dialogs to appear because the application can become suspended in an endless loop.
ActivateAfterOriginal
This event occurs each time the window becomes active, after the window’s activate
event is run.
CloseBeforeOriginal
This event occurs when the window is closed, but before the window’s close event
is run. This event can be canceled.
CloseAfterOriginal
This event occurs when the window is closed, but after the window’s close event is
run.
PrintBeforeOriginal
This event occurs when the print action for the window is chosen, but before the
window’s print event is run. The print action for a window occurs when the user
chooses the Print menu item from the File menu, or clicks the Print button on the
window. This event can be canceled.
PrintAfterOriginal
This event occurs when the print action for the window is chosen, but after the
window’s print event is run.
90 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 6 W I N D O W S
BeforeModalDialog
This event occurs when the a modal dialog is displayed by a window, but before the
dialog is actually shown to the user. The event arguments allow access the
properties of the modal dialog:
DialogType Indicates the type of modal dialog that is being displayed. The
DialogType enumeration defines the following available types:
Type Description
Ask A modal dialog generated by the error, warning, or ask()
script commands.
GetString A modal dialog generated by the getstring() command.
Message Contains the text that is displayed in the modal dialog. Setting the value
of this property in the BeforeModalDialog event allows you to change the text
displayed in the modal dialog. Typically, the value of this parameter is examined to
find out what message is going to be displayed to the user.
Button1Text Contains the text that is displayed in button 1 of the modal dialog.
Setting the value of this property in the BeforeModalDialog event allows you to
change the text displayed in the button.
Button2Text Contains the text that is displayed in button 2 of the modal dialog.
Setting the value of this property in the BeforeModalDialog event allows you to
change the text displayed in the button.
Button3Text Contains the text that is displayed in button 3 of the modal dialog.
For getstring() dialogs, this is the editable string in the dialog. Setting the value of
this property in the BeforeModalDialog event allows you to change the text
displayed in the button or the editable field.
Setting this property in the BeforeModalDialog event allows your code to respond
to the dialog, and prevents the dialog from being displayed to the user. Setting the
response to None will allow the dialog to be displayed.
The following Visual Basic example creates references to the Sales Transction Entry
form and window, and then registers a BeforeModalDialog event for the Sales
Transaction Entry window.
PROGRAMMER’S GUIDE 91
PA RT 3 R E S O U R C E R E F E R E N C E
End Sub
The following example is the BeforeModalDialog event handler for the event
registered inthe previous example. When a modal dialog is to be displayed, the
code examines the text of the message to determine whether it is the message that
asks the user whether they want to add a new customer or a new prospect. If it is,
the Response parameter of the event arguments is set to Button1, indicating that a
new customer should be created. This prevents the modal dialog from being
displayed.
End Sub
AfterModalDialog
This event occurs when the user has acted on a modal dialog displayed by a
window. This event allows you to retrieve the choice that the user made in the
modal dialog. Typically, you will examine the DialogType and Message properties
in the event arguments to find out what dialog is being displayed. Then you can
examine the Response property in the event arguments to learn how the user
responded to the dialog.
The following C# example creates references to the Item Maintenance form and the
Item Maintenance window, and then registers for the AfterModalDialog event for
the Item Maintenance window.
92 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 6 W I N D O W S
The following C# example is the AfterModalDialog event handler for the event
registered inthe previous example. When a modal dialog is to be displayed, the
code examines the text of the message to determine whether it is the message that
asks the user whether they want to delete the current item. The Response property
of the event arguments is examined to find out whether the user clicked Delete in
the modal dialog. If the user did, the additional information stored for the item is
also deleted.
PROGRAMMER’S GUIDE 93
94 P R O G R A M M E R ’ S G U I D E
Chapter 17: Scrolling Windows
Scrolling windows are a special type of window in Microsoft Dynamics GP that are
used to display or access data directly from a database table. The following items
are discussed:
Dynamics.Forms.SopEntry.SopEntry.LineScroll
The IntelliSense in Visual Studio will tell you what scrolling window in Microsoft
Dynamics GP is being referred to by the expression.
• LineFillBeforeOriginal
• LineFillAfterOriginal
• LineEnterBeforeOriginal
• LineEnterAfterOriginal
• LineChangeBeforeOriginal
• LineChangeAfterOriginal
• LineLeaveBeforeOriginal
• LineLeaveAfterOriginal
• LineInsertBeforeOriginal
• LineInsertAfterOriginal
• LineDeleteBeforeOriginal
• LineDeleteAfterOriginal
LineFillBeforeOriginal
This event occurs before the line fill event for the scrolling window. The line fill
event occurs each time a new line is added to the scrolling window from the linked
table, such as when the user scrolls to a new line. When the scrolling window first
fills, the line fill event occurs repeatedly until the scrolling window is full. The line
fill event also occurs each time the user moves the focus to an existing line in the
scrolling window. The line fill event occurs before the line enter event.
PROGRAMMER’S GUIDE 95
PA RT 3 R E S O U R C E R E F E R E N C E
To find out what data will be added to the current row of the scrolling window,
examine the current row of the form-level table buffer for the table linked to the
scrolling window.
When using this event, you cannot examine the window fields for the scrolling window to
determine what row is being added. The values of the window fields will not have been set
yet.
For example, the following C# code registers the LineFillBeforeOriginal event for
the scrolling window in the Customers and Prospects window in Microsoft
Dynamics GP.
The following is the C# code that runs in response to this event. It allows only
customers in the “TERRITORY 2” sales territory to be displayed. The
RmCustomerMstr table is linked to the scrolling window, so the values for the
scrolling window come from this table. Notice how the code is accessing the current
row of the form-level table buffer for the RmCustomerMstr table to find out what
row is being added to scrolling window. The SalesTerritory field in the current row
of the table is examined. If it is not “TERRITORY 2”, the event is cancelled. This
prevents the row from being displayed in the scrolling window.
LineFillAfterOriginal
This event occurs after the line fill event for the scrolling window.
LineEnterBeforeOriginal
This event occurs when the focus moves to a line in the scrolling window, but
before the scrolling window’s line enter event is run. This event can be canceled.
LineEnterAfterOriginal
This event occurs when the focus moves to a line in the scrolling window, but after
the scrolling window’s line enter event is run.
96 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 7 S C R O L L I N G W I N D O W S
LineChangeBeforeOriginal
This event occurs when the focus leaves a line in the scrolling window, and the
contents of the line has been modified. The event runs before the scrolling
window’s line change event is run. This event can be canceled.
LineChangeAfterOriginal
This event occurs when the focus leaves a line in the scrolling window, and the
contents of the line has been modified. The event runs after the scrolling window’s
line change event is run.
LineLeaveBeforeOriginal
This event occurs when the focus leaves a line in the scrolling window, but before
the scrolling window’s line leave event is run. This event can be canceled.
LineLeaveAfterOriginal
This event occurs when the focus leaves a line in the scrolling window, but after the
scrolling window’s line leave event is run.
LineInsertBeforeOriginal
This event occurs when a new line is added to the scrolling window, but before the
scrolling window’s line insert event is run. This event can be canceled.
LineInsertAfterOriginal
This event occurs when a new line is added to the scrolling window, but after the
scrolling window’s line insert event is run.
LineDeleteBeforeOriginal
This event occurs when a line is removed from the scrolling window, but before the
scrolling window’s line delete event is run. This event can be canceled.
LineDeleteAfterOriginal
This event occurs when a line is removed from the scrolling window, but after the
scrolling window’s line delete event is run.
PROGRAMMER’S GUIDE 97
98 P R O G R A M M E R ’ S G U I D E
Chapter 18: Window Fields
Window fields display individual data items on a window. The following items are
discussed:
Dynamics.Forms.SopEntry.SopEntry.SopNumber
Dynamics.Forms.SopEntry.SopEntry.LineScroll.QtyToBackOrder
The IntelliSense in Visual Studio will tell you what field in Microsoft Dynamics GP is being
referred to by the expression.
Some fields in windows are called local fields, because they are used only within a
specific form. For instance, the Sales Transaction Entry window (SopEntry) contains
a local field named (L) BillTo Address 1. The (L) in the name is the standard way
local fields are identified in Microsoft Dynamics GP. In a Visual Studio Tools for
Microsoft Dynamics GP project, the names of these fields are prefixed with the
“Local” to indicate they are local fields. For example, to access the BillTo Address 1
local field, you would use the following syntax:
Dynamics.Forms.SopEntry.SopEntry.LocalBillToAddress1
• Clear()
• Disable()
• Enable()
• Fill()
• Focus()
• ForceValidate()
• Hide()
• Lock()
• RunValidate()
• Show()
• Unlock()
PROGRAMMER’S GUIDE 99
PA RT 3 R E S O U R C E R E F E R E N C E
Clear()
The Clear() method sets the field to its cleared value. The following table lists the
cleared value for standard datatypes:
Disable()
The Disable() method makes the field appear in a disabled state, and prevents the
user from making changes to the field.
Enable()
The Enable() method allows a previously disabled field to receive user input.
Fill()
The Fill() method sets the field to its filled value. The following table lists the filled
value for standard datatypes:
Focus()
The Focus() method moves the focus to the field.
ForceValidate()
The ForceValidate() method controls whether the validate event will occur when
the focus leaves the field. If the validate event occurs, any validation code for the
field will be run. This method takes one boolean parameter. Supplying the value
true forces the validate event to occur. Supplying the value false clears any previous
call to force the validate event to occur.
Hide()
The Hide() method causes the field to become invisible and inaccessible to the user.
Lock()
The Lock() method causes a field to become inaccessible to the user. The field’s
appearance will not change.
100 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 8 W I N D O W F I E L D S
RunValidate()
The RunValidate() method causes any validation code for the window field to be
run.
Show()
The Show() method causes a previously hidden field to become visible and
accessible to the user.
Unlock()
The Unlock() method causes a previously locked field to become accessible to the
user.
• IsEmpty
• IsFilled
• Value
IsEmpty
The IsEmpty property returns the value true when the value of the field is empty
for the specific field type. The following table lists the empty value for standard
datatypes:
IsFilled
The IsFilled property returns the value true when the value of the field is set to the
maximum value for the specific field type. The following table lists the filled value
for standard datatypes:
Value
The Value property is used to set or retrieve the value of the field. The IntelliSense
in Visual Studio will tell you what type of value is used for the field.
• Change
• EnterBeforeOriginal
• EnterAfterOriginal
• LeaveBeforeOriginal
• LeaveAfterOriginal
• ValidateBeforeOriginal
• ValidateAfterOriginal
Change
This event occurs when the value of the field changes, such as being set by the user
or changed by other code in Microsoft Dynamics GP.
ClickAfterOriginal
This event occurs when the user clicks a button, but after the button’s click event is
run.
ClickBeforeOriginal
This event occurs when the user clicks a button, but before the button’s click event
is run. This event can be canceled.
EnterBeforeOriginal
This event occurs when the focus moves to the field, but before the field’s enter
event is run. This event can be canceled.
EnterAfterOriginal
This event occurs when the focus moves to the field, but after the field’s enter event
is run.
LeaveBeforeOriginal
This event occurs when the focus moves from the field, but before the field’s leave
event is run. This event can be canceled.
LeaveAfterOriginal
This event occurs when the focus moves from the field, but after the field’s leave
event is run.
ValidateBeforeOriginal
This event occurs when the focus is to move from the field, and the field has been
set to be validated. A field will be validated when its value has been changed, or the
validation has been forced, such as with the ForceValidate() method. This event
occurs before the field’s validate event. It can be canceled.
ValidateAfterOriginal
This event occurs when the focus is to move from the field, and the field has been
set to be validated. This event occurs after the field’s validate event.
102 P R O G R A M M E R ’ S G U I D E
Chapter 19: Tables
Tables are the basic resource of the Microsoft Dynamics GP application that
provides access to the database. Methods provided for each table allow creating,
retrieving, updating, or deleting rows from the table in the database. The following
items for tables are discussed:
• Accessing tables
• Table methods
• Table properties
Accessing tables
A table buffer provides access to one row of a specific table. Your code will interact
with the table buffer when you perform operations on the table. There are two types
of table buffers: global and form-level.
Microsoft.Dexterity.Applications
For instance, to access the collection of tables in the Dynamics dictionary, use the
following syntax:
Microsoft.Dexterity.Applications.Dynamics.Tables
Dynamics.Tables.RmCustomerMstr
The IntelliSense in Visual Studio will tell you what table in Microsoft Dynamics GP is
being referred to by the expression.
By default, a global table buffer for a table is shared with all of the other Visual
Studio Tools add-ins that are accessing that same table. If you want your integration
to create a global table buffer that is not shared, use the Clone() method when
creating the instance of the global table buffer.
Dynamics.Forms.SopEntry.Tables
The IntelliSense in Visual Studio will tell you what form-level table in Microsoft Dynamics
GP is being referred to by the expression.
Table methods
Tables provide the following methods:
• Change()
• ChangeFirst()
• ChangeLast()
• ChangePrevious()
• Clear()
• Clone()
• Close()
• Fill()
• Get()
• GetFirst()
• GetLast()
• GetNext()
• GetPrevious()
• RangeClear()
• RangeEnd()
• RangeRemove()
• RangeStart()
• Release()
• Remove()
• Save()
Change()
The Change() method retrieves a row from the table and passively or actively locks
the row, allowing changes to be made to it. The row retrieved is determined by the
key specified for the table and the values that were specified for the key segments.
The Change() method has one parameter:
ActiveLock – A optional boolean. The value true specifies that an active lock will be
applied to the row. The value false (the default value) specifies that a passive lock
will be applied.
ChangeFirst()
The ChangeFirst() method retrieves the first row from the table and passively or
actively locks the row, allowing changes to be made to it. The row retrieved is
determined by the key specified for the table. The ChangeFirst() method has one
parameter:
ActiveLock – A optional boolean. The value true specifies that an active lock will be
applied to the row. The value false (the default value) specifies that a passive lock
will be applied.
104 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 9 T A B LE S
ChangeLast()
The ChangeLast() method retrieves the last row from the table and passively or
actively locks the row, allowing changes to be made to it. The row retrieved is
determined by the key specified for the table. The ChangeLast() method has one
parameter:
ActiveLock – A optional boolean. The value true specifies that an active lock will be
applied to the row. The value false (the default value) specifies that a passive lock
will be applied.
ChangeNext()
The ChangeNext() method retrieves the next row from the table and passively or
actively locks the row, allowing changes to be made to it. The row retrieved is
determined by the key specified for the table and the values of the key fields for the
row currently in the table buffer. The ChangeNext() method has one parameter:
ActiveLock – A optional boolean. The value true specifies that an active lock will be
applied to the row. The value false (the default value) specifies that a passive lock
will be applied.
ChangePrevious()
The ChangePrevious() method retrieves the previous row from the table and
passively or actively locks the row, allowing changes to be made to it. The row
retrieved is determined by the key specified for the table and the values of the key
fields for the row currently in the table buffer. The ChangePrevious() method has
one parameter:
ActiveLock – A optional boolean. The value true specifies that an active lock will be
applied to the row. The value false (the default value) specifies that a passive lock
will be applied.
Clear()
The Clear() method sets all of the fields in the table buffer to their cleared values.
The following table lists the cleared value for standard datatypes:
Clone()
The Clone() method creates a new instance of a global table buffer for a table. This
new table buffer instance is not shared, so it is not accessible by other Visual Studio
Tools add-ins. The Clone() method has no effect when when with form-level table
buffers.
Close()
The Close() method closes the table buffer.
Fill()
The Fill() method sets all of the fields in the table buffer to their maximum values.
The following table lists the filled value for standard datatypes:
Get()
The Get() method retrieves a row from the table. No lock is applied to the row. The
row retrieved is determined by the key specified for the table and the values that
were specified for the key segments.
GetFirst()
The GetFirst() method retrieves the first row from the table. No lock is applied to
the row. The row retrieved is determined by the key specified for the table.
GetLast()
The GetLast() method retrieves the last row from the table. No lock is applied to the
row. The row retrieved is determined by the key specified for the table.
GetNext()
The GetNext() method retrieves the next row from the table. No lock is applied to
the row. The row retrieved is determined by the key specified for the table and the
values of the key fields for the row currently in the table buffer.
GetPrevious()
The GetPrevious() method retrieves the previous row from the table. No lock is
applied to the row. The row retrieved is determined by the key specified for the
table and the values of the key fields for the row currently in the table buffer.
RangeClear()
The RangeClear() method removes the range that was specified for the table.
RangeEnd()
The RangeEnd() method specifies the current values of the key segments in the
table buffer as the end of the range of rows in the table. The Key property specifies
which key will be used for the range.
RangeRemove()
The RangeRemove() method attempts to delete all of the rows in the current range
from the table.
RangeStart()
The RangeStart() method specifies the current values of the key segments in the
table buffer as the beginning of the range of rows in the table. The Key property
specifies which key will be used for the range.
106 P R O G R A M M E R ’ S G U I D E
C H A P T E R 1 9 T A B LE S
Release()
The Release() method releases any passive or active lock for a row in the table
buffer. The row values remain in the table buffer.
Remove()
The Remove() method deletes the current row in the table buffer from the table. The
row must be passivly or actively locked before it can be deleted.
Save()
The Save() method saves the values currently in the table buffer to the table. If the
row is locked in the table buffer, it will be updated. If no row in the table is locked, a
new row will be added.
Table properties
Tables have the following property:
• Key
Key
The Key property is used to set or retrieve the key currently being used by the table
buffer to access the table. The keys for a table are identified by number, beginning
with the value 1. When you specify the key you want to use for a table, you will
supply the corresponding integer. The Table Descriptions window in Microsoft
Dynamics GP lists the keys for each table, and the key segments (fields) that each
key contains.
Dynamics.Tables.IvItemMstr.ItemNumber
The IntelliSense in Visual Studio will tell you what field in Microsoft Dynamics GP is being
referred to by the expression.
• Clear()
• Fill()
Clear()
The Clear() method sets the field to its cleared value. The following table lists the
cleared value for standard datatypes:
Fill()
The Fill() method sets the field to its filled value. The following table lists the filled
value for standard datatypes:
• IsEmpty
• IsFilled
• Value
IsEmpty
The IsEmpty property returns the value true when the value of the field is empty
for the specific field type. The following table lists the empty value for standard
datatypes:
IsFilled
The IsFilled property returns the value true when the value of the field is set to the
maximum value for the specific field type. The following table lists the filled value
for standard datatypes:
Value
The Value property is used to set or retrieve the value of the field. The IntelliSense
in Visual Studio will tell you what type of value is used for the field.
110 P R O G R A M M E R ’ S G U I D E
Chapter 21: Commands
In Microsoft Dynamics GP, commands are used to encapsulate a small piece of
functionality for the application. They are typically used for navigation. Commands
can appear in menus and also in toolbars in Microsoft Dynamics GP. The following
items are discussed:
• Command types
• Accessing commands
• Command methods
Command types
A command can be one of the following types:
Script A script command runs the script code that is defined for it.
Accessing commands
Commands for an application dictionary are accessed using the Commands
property of the form that they are contained in. Most commands in Microsoft
Dynamics GP are contained in forms that are used specifically for commands. The
names of these forms begin with “Command” and include the module for which
the commands are used. For example, to access the command used to open the
SmartList window in Microsoft Dynamics GP, you would use the following syntax:
Dynamics.Forms.CommandSystem.Commands.SmartList
The IntelliSense in Visual Studio will tell you what command in Microsoft Dynamics GP is
being referred to by the expression.
Command methods
Commands provide the following methods:
• Check()
• Disable()
• Enable()
• Hide()
• Run()
• Show()
• Uncheck()
Check()
The Check() method causes the command to appear checked if it is displayed in a
menu or on a toolbar.
Disable()
The Disable() method causes the command to appear disabled if it is displayed in a
menu or on a toolbar. Once disabled, the command cannot be run.
Enable()
The Enable() method causes a previously disabled command to become enabled. It
will appear enabled if it is displayed in a menu or on a toolbar.
Hide()
The Hide() method causes a command to be hidden in any menu or toolbar in
which it appears. The command can still be run.
Run()
The Run() method performs the action of the command. For form commands, it
opens the corresponding form. For script commands, it executes the script code that
is attached to the command.
Show()
The Show() method causes a previously hidden command to be displayed in any
menu or toolbar in which it appears.
Uncheck()
The Uncheck() method causes the command to appear unchecked if it is displayed
in a menu or on a toolbar.
112 P R O G R A M M E R ’ S G U I D E
Chapter 22: Globals
Globals are used to hold values accessible to the entire Microsoft Dynamics GP
application. The following items are discussed:
• Accessing globals
• Global properties
Accessing globals
Globals for an application dictionary are accessed through the dictionary class. This
class has a Globals property that provides access to the collection of globals in the
dictionary. The dictionary class for the application dictionary is located in the
following namespace:
Microsoft.Dexterity.Applications
For instance, to access the collection of globals in the Dynamics dictionary, use the
following syntax:
Microsoft.Dexterity.Applications.Dynamics.Globals
To access a specific global value, such as the current user’s ID (UserId), use the
following syntax:
Microsoft.Dexterity.Applications.Dynamics.Globals.UserId
Global properties
Globals have the following properties available:
• IsEmpty
• IsFilled
• Value
IsEmpty
The IsEmpty property returns the value true when the value of the field is empty
for the specific field type. The following table lists the empty value for standard
datatypes:
IsFilled
The IsFilled property returns the value true when the value of the field is set to the
maximum value for the specific field type. The following table lists the filled value
for standard datatypes:
Value
The Value property is used to retrieve the value of the global. The IntelliSense in
Visual Studio will tell you what type of value is used for the field. Global values
cannot be set from a Visual Studio Tools for Microsoft Dynamics GP project.
114 P R O G R A M M E R ’ S G U I D E
Chapter 23: Procedures
There are two types of procedures in a Dynamics GP application dictionary. Global
procedures are blocks of code that are accessed from various places throughout the
application. Parameters are used to send values to a procedure and also to return
values from it. Form-level procedures are like global procedures, with the exception
that they are defined as part of a specific form. Typically, they perform some action
specific to the form they are defined for. The following items are discussed:
Microsoft.Dexterity.Applications
Microsoft.Dexterity.Applications.Dynamics.Procedures
Dynamics.Procedures.GetNextFormNoteToOpen
The IntelliSense in Visual Studio will tell you what global procedure in Microsoft Dynamics
GP is being referred to by the expression.
Dynamics.Forms.SopEntry.Procedures
The IntelliSense in Visual Studio will tell you what form-level procedure in Microsoft
Dynamics GP is being referred to by the expression.
Procedure methods
Procedures provide the following method:
• Invoke()
Invoke()
The Invoke() method is used to run the specified procedure. The parameters for this
method will depend on the procedure that is being run. The following table lists the
types of parameters for procedures:
Type Description
in Parameters of type “in” are used only to pass values into the procedure.
out Parameters of type “out” are used only to pass values out of the
procedure.
inout Parameters of type “inout” are used to pass values into the procedure,
and to pass values out of the procedure.
The IntelliSense in Visual Studio will tell you the type of each parameter for a procedure. It
will also tell you the datatype of each parameter, such as decimal or string.
For example, the following C# code calls the CheckNoteIdString global procedure.
This procedure has one “in” parameter and two “out” parameters. Notice that the
out keyword is required for the parameters to which values are returned.
You can refer to the Microsoft Dynamics GP SDK for details about the procedures
available to invoke. Some procedures in Microsoft Dynamics GP have optional
parameters defined. Visual Studio Tools does not support optional parameters. You
must supply all parameters for a procedure when you invoke it from Visual Studio
Tools.
Procedure events
Procedures provide the following events:
• InvokeBeforeOriginal
• InvokeAfterOriginal
InvokeBeforeOriginal
This event occurs when the procedure is invoked, but before the original procedure
is run. The event arguments allow access the parameters of the procedure. Refer to
Parameters for procedures on page 117 to learn more about working with parameters
in procedure events.
InvokeAfterOriginal
This event occurs when the procedure is invoked, but after the original procedure is
run.The event arguments allow access the parameters of the procedure. Refer to
Parameters for procedures on page 117 to learn more about working with parameters
in procedure events.
116 P R O G R A M M E R ’ S G U I D E
C H A PT E R 2 3 P R O C ED U R E S
The following C# example is the event handler for the event registered in the
previous example. The event handler for the AddSuccessfulLoginRecord procedure
is typically used to perform setup operations, because the user has successfully
logged into a company.
• When invoking a procedure, the IntelliSense lists the parameters and their data
types.
• The event arguments passed to the event handler for procedure events will list
the available parameters and their data types.
Invokable procedures
With this release of Visual Studio Tools for Microsoft Dynamics GP, not all
procedures can be invoked. Procedures with the following characteristics cannot be
invoked:
If a procedure cannot be run by this version of Visual Studio Tools, it will not be
included in the procedure lists displayed by the IntelliSense in Visual Studio.
118 P R O G R A M M E R ’ S G U I D E
Chapter 24: Functions
There are two types of functions in a Dynamics GP application dictionary. Global
functions are blocks of code that are accessed from various places throughout the
application. Parameters are used to send values to a function and also to return
values from it. In addition, functions always return a value. Form-level functions are
like global functions, with the exception that they are defined as part of a specific
form. Typically, they perform some action specific to the form they are defined for.
The following items are discussed:
Microsoft.Dexterity.Applications
For instance, to access the collection of global functions in the Dynamics dictionary,
use the following syntax:
Microsoft.Dexterity.Applications.Dynamics.Functions
Dynamics.Functions.GetCurrentDirectory
The IntelliSense in Visual Studio will tell you what global function in Microsoft Dynamics
GP is being referred to by the expression.
Dynamics.Forms.SopEntry.Functions
The IntelliSense in Visual Studio will tell you what form-level function in Microsoft
Dynamics GP is being referred to by the expression.
Function methods
Functions provide the following method:
• Invoke()
Invoke()
The Invoke() method is used to run the specified function. The parameters for this
method will depend on the procedure that is being run. The following table lists the
types of parameters for functions:
Type Description
in Parameters of type “in” are used only to pass values into the function.
out Parameters of type “out” are used only to pass values out of the
function.
inout Parameters of type “inout” are used to pass values into the function,
and to pass values out of the function.
The Invoke() method will have a return value to which the return value of the
function will be returned.
The IntelliSense in Visual Studio will tell you the type of each parameter and the return
value for a function. It will also tell you the datatype of each parameter and the return value,
such as decimal or string.
For example, the following C# code calls the GetCurrentDirectory global function.
This procedure has no parameters and returns a string value.
string currentDirectory;
currentDirectory = Dynamics.Functions.GetCurrentDirectory.Invoke();
You can refer to the Microsoft Dynamics GP SDK for details about the functions
available to invoke. Some functions in Microsoft Dynamics GP have optional
parameters defined. Visual Studio Tools does not support optional parameters. You
must supply all parameters for a function when you invoke it from Visual Studio
Tools.
Function events
Functions provide the following events:
• InvokeBeforeOriginal
• InvokeAfterOriginal
InvokeBeforeOriginal
This event occurs when the function is invoked, but before the original function is
run. The event arguments allow access the parameters and return value of the
function. Refer to Parameters for functions on page 121 to learn more about working
with parameters and return value in function events.
InvokeAfterOriginal
This event occurs when the function is invoked, but after the original function is
run.The event arguments allow access the parameters and return value of the
function. Refer to Parameters for functions on page 121 to learn more about working
with parameters and return value in function events.
120 P R O G R A M M E R ’ S G U I D E
C H A P T E R 2 4 F U N C T I O N S
UserDefaultsForm.Functions.GetAutoComplete.InvokeAfterOriginal +=
new SyUserDefaultsForm.GetAutoCompleteFunction.InvokeEventHandler(
GetAutoComplete_InvokeAfterOriginal);
The following C# example is the event handler for the event registered in the
previous example. The event handler uses the event arguments to examine the first
parameter passed into the function. If the parameter value is “DYNSA”, the return
value of the function is set to false. This will turn off the auto-complete functionality
for the DYNSA user.
• When invoking a function, the IntelliSense lists the parameters and return
value, along with their data types.
• The event arguments passed to the event handler for function events will list
the available parameters and return value, along with their data types.
We recommend that you avoid changing parameter and return values in Microsoft
Dynamics GP functions. Changing the parameter and return values can signficantly alter
the operation of Microsoft Dynamics GP.
Invokable functions
With this release of Visual Studio Tools for Microsoft Dynamics GP, not all
functions can be invoked. Functions with the following characteristics cannot be
invoked:
• The function uses “reference” parameters. These parameter types contain a link
to a specific resource in the application dictionary.
If a function cannot be run by this version of Visual Studio Tools, it will not be
included in the function lists displayed by the IntelliSense in Visual Studio.
122 P R O G R A M M E R ’ S G U I D E
Chapter 25: Composites
In Microsoft Dynamics GP, a composite is a group of fields and their associated data
types which form a single data type. Each part of the composite is called a
component. In Microsoft Dynamics GP, composites are used to store data that
consists of several parts, such as the account number. Composites are also used to
group together the parameters that are passed to procedures and functions. The
following items are discussed:
• Composite types
• Accessing composites
• Composite field methods
• Composite field properties
• Composite field events
Composite types
When you access composite resources from a dictionary, each composite will have
several types defined for it. Each type is used in specific situations in Microsoft
Dynamics GP. The following table describes the composite types.
In most cases, the IntelliSense will tell you what composite type is required for a specific
situation.
Accessing composites
Composites can be displayed as fields on windows, and are accessed as properties
of the window or scrolling window they are contained in. Composites can also be
used to create variables that are passed as parameters for procedures and functions.
Window fields
Composite fields are accessed as properties of the window or scrolling window
they are contained in. For example, to access the Account Number CS field in the
Account Maintenance window of Microsoft Dynamics GP, you would use the
following syntax:
Dynamics.Forms.GlAccountMaintenance.GlAccountMaintenance.AccountNumberCs
Variables
In some cases, you may want to retrieve the value of a composite and use it as a
variable in your Visual Studio Tools integration. You can create an instance of the
composite, and then set the value of the composite variable.
Parameters
You can create composite variables and pass them as parameters for procedures
and functions. A variable based on the “read-only” composite type must be used as
the parameter. To create a “read-only” composite variable, you must first create a
variable based on the “data” composite type.
// Create the read-only composite that is used for the function call
Microsoft.Dexterity.Applications.DynamicsDictionary.AccountNumberComposite
ReadOnly accountNumber = new AccountNumberCompositeReadOnly
(accountNumberData);
124 P R O G R A M M E R ’ S G U I D E
C H A P T E R 2 5 C O M P O S IT E S
Components
To access the individual components for most composites, you can use the
properties of the composite. The composite will have a property for each
component of the composite.
• Clear()
• Disable()
• Enable()
• Fill()
• Focus()
• ForceValidate()
• Hide()
• Lock()
• RunValidate()
• Show()
• Unlock()
Clear()
The Clear() method sets each component of the composite to its cleared value. The
following table lists the cleared value for standard datatypes:
Disable()
The Disable() method makes the composite field appear in a disabled state, and
prevents the user from making changes to the field.
Enable()
The Enable() method allows a previously disabled composite field to receive user
input.
Fill()
The Fill() method sets each component of the composite to its filled value. The
following table lists the filled value for standard datatypes:
Focus()
The Focus() method moves the focus to the composite field.
ForceValidate()
The ForceValidate() method controls whether the validate event will occur when
the focus leaves the composite field. If the validate event occurs, any validation
code for the composite field will be run. This method takes one boolean parameter.
Supplying the value true forces the validate event to occur. Supplying the value
false clears any previous call to force the validate event to occur.
Hide()
The Hide() method causes the composite field to become invisible and inaccessible
to the user.
Lock()
The Lock() method causes a composite field to become inaccessible to the user. The
field’s appearance will not change.
RunValidate()
The RunValidate() method causes any validation code for the composite field to be
run.
Show()
The Show() method causes a previously hidden composite field to become visible
and accessible to the user.
Unlock()
The Unlock() method causes a previously locked composite field to become
accessible to the user.
126 P R O G R A M M E R ’ S G U I D E
C H A P T E R 2 5 C O M P O S IT E S
• IsEmpty
• IsFilled
• Length
• Value
IsEmpty
The IsEmpty property returns the value true when the value of the composite field
is empty for the specific field type. The following table lists the empty value for
standard datatypes:
IsFilled
The IsFilled property returns the value true when the value of the composite field is
set to the maximum value for the specific field type. The following table lists the
filled value for standard datatypes:
Length
The Length property is used to retrieve the number of components in the composite
field.
Value
The Value property is used to set or retrieve the value of the composite field. The
IntelliSense in Visual Studio will tell you what type of value is used for the field.
• Change
• EnterBeforeOriginal
• EnterAfterOriginal
• LeaveBeforeOriginal
• LeaveAfterOriginal
• ValidateBeforeOriginal
• ValidateAfterOriginal
Composites of the type “with events” supply these events for the composite as a
single field. Composites of the type “with full events” supply these events for the
composite as a single field, and also for each of the components of the composite.
Change
This event occurs when the value of the composite or component changes, such as
being set by the user or changed by other code in Microsoft Dynamics GP.
EnterBeforeOriginal
This event occurs when the focus moves to the composite field or component, but
before the field or component enter event is run. This event can be canceled.
EnterAfterOriginal
This event occurs when the focus moves to the composite field or component, but
after the field or component enter event is run.
LeaveBeforeOriginal
This event occurs when the focus moves from the composite field or component,
but before the field’s leave event is run. This event can be canceled.
LeaveAfterOriginal
This event occurs when the focus moves from the composite field or component,
but after the field’s leave event is run.
ValidateBeforeOriginal
This event occurs when the focus is to move from the composite field or component,
and the composite field or component has been set to be validated. A field or
component will be validated when its value has been changed, or the validation has
been forced, such as with the ForceValidate() method. This event occurs before the
composite field or component validate event. It can be canceled.
ValidateAfterOriginal
This event occurs when the focus is to move from the composite field or component,
and the composite field or component has been set to be validated. This event
occurs after the composite field or component validate event.
128 P R O G R A M M E R ’ S G U I D E
PART 4: INTEGRATION EXAMPLES
Part 4: Integration Examples
This portion of the documentation describes integration examples that show how to
use Visual Studio Tools for Microsoft Dynamics GP. The following examples are
discussed:
• Chapter 26, “Field Defaulter,” describes an example that uses events to default
field values in Microsoft Dynamics GP.
• Chapter 29, “Lookups,” describes an example the shows how six common
lookups are implemented for a Visual Studio Tools integration.
The following table indicates which features of Visual Studio Tools for Microsoft
Dynamics GP features are implemented in each sample.
130 P R O G R A M M E R ’ S G U I D E
Chapter 26: Field Defaulter
This sample application demonstrates how events in Microsoft Dynamics GP can be
used to default field values. The sample defaults the City and State fields when a
user enters a value for the ZIP code field in the Customer Maintenance window.
The following topics are discussed:
• Overview
• Running the sample application
• How Visual Studio Tools was used
Overview
This sample application integrates with the Customer Maintenance window in
Microsoft Dynamics GP. It automatically defaults values for the City and State
fields when the user supplies a known ZIP Code.
This sample uses a fixed set of ZIP Codes and correspond City and State values. An
actual application would use a more extensive set.
• Application.Dynamics
• Microsoft.Dexterity.Bridge
If any of these references for the project are not valid, re-add them to the project.
02109 58104
53151 58474
55111 60605
56560 85012
58078 95014
58102 98052
58103
Resources accessed
The Field Defaulter sample uses the following resources in the Dynamics
dictionary:
Forms
• RmCustomerMaintenance
Windows
• RmCustomerMaintenance
Events
The Field Defaulter sample registers the following event in Microsoft Dynamics GP:
• A change event for the ZipCode field in the Customer Maintenance window,
used to look up the value entered. If the city and state can be found for the ZIP
code value entered, their value are automatically set in the window.
132 P R O G R A M M E R ’ S G U I D E
Chapter 27: Estimate Freight
This sample application demonstrates several techniques useful when creating
Microsoft Dynamics GP integrations. The sample integrates with the Sales
Transaction Entry window. The following topics are discussed:
• Overview
• Running the sample application
• How Visual Studio Tools was used
Overview
This sample application integrates with the Sales Transaction Entry window in
Microsoft Dynamics GP. It retrieves shipping weight information about the items in
the current sales document, calculates an estimated shipping weight for all of the
items, and then estimates the freight cost. The estimated freight value is placed into
the Freight field of the Sales Transaction Entry window.
This sample uses a fixed set of shipping methods and shipping rates. An actual
application would use a more extensive rate table, and possibly a web service to
access freight rates.
The Estimate Freight sample uses the table access capabilities of Visual Studio Tools
to access data in Microsoft Dynamics GP.
• Application.Dynamics
• Microsoft.Dexterity.Bridge
• Microsoft.Dexterity.Shell
If any of these references for the project are not valid, re-add them to the project.
User interface
The special WinForm available for Dynamics GP add-ins was used when creating
the Estimate Freight window. The customized buttons and images were also used.
The sample illustrates technique that can be used to implement window-level notes
and the online help link.
134 P R O G R A M M E R ’ S G U I D E
C H A P T E R 2 7 E S T IM AT E FR EI G HT
Resources accessed
The Estimate Freight sample uses many resources in the Dynamics dictionary:
Forms
• SOPEntry
• FormNote1
• FormNote2
• FormNote3
• FormNote4
• FormNote5
Windows
• SOPEntry
Global procedures
• CheckForNote
• CheckNoteIdString
• GetNextFormNoteToOpen
Tables
Data from the following tables is accessed to compute the estimated freight for the
current sales document:
Events
The Estimate Freight sample registers the following events in Microsoft Dynamics
GP:
• A menu handler event for the Sales Transaction Entry form, used to open the
Estimate Freight window.
• A form close event on the Sales Transaction Entry form, used to indicate when
the Sales Transaction Entry window has been closed.
• A watch event for the SOP Number field in the Sales Transaction Entry
window, used to keep the Estimate Freight window updated with the current
sales document.
• An enter event for the Freight field in the Sales Transaction Entry window, used
to ask the user whether they want to estimate the freight amount if a value
hasn’t been supplied.
• Several form close events for the various “Note” forms in Microsoft Dynamics
GP, used to keep the Note button on the Estimate Freight window updated.
• Overview
• Running the sample application
• How Visual Studio Tools was used
Overview
This sample application integrates with the Item Maintenance window in Microsoft
Dynamics GP. It stores environmental information about the item. The additional
data is stored in the DUOS (Dynamics User Object Store) table for the current
company.
This sample also implements support for the macro system, allowing macros to be
recorded and played back for this window.
• Application.Dynamics
• Microsoft.Dexterity.Bridge
• Microsoft.Dexterity.Shell
If any of these references for the project are not valid, re-add them to the project.
9. Display an item.
You can display an existing item or create a new item.
User interface
The special WinForm available for Dynamics GP add-ins was used when creating
the Environmental Details window.
Resources accessed
The Estimate Freight sample uses many resources in the Dynamics dictionary:
Forms
• IvItemMaintenanceForm
Windows
• IvItemMaintenanceWindow
Tables
Data for the integration is stored in the following table:
• SyUserObjectStoreTable (DUOS)
138 P R O G R A M M E R ’ S G U I D E
C H A P T E R 2 8 E N V IR O N M EN T A L D E T AIL S
This is the same table used by VBA to store data. The DUOSHelper class of the
Environmental Details sample contains methods that are used to write, retrieve,
and delete rows from the DUOS table.
Events
The Environmental Details sample registers the following events in Microsoft
Dynamics GP:
• A menu handler event for the Item Maintenance form, used to display the
Environmental Details form.
• A form open event on the Item Maintenance form, used to create an instance of
the Environmental Details form.
• A form close event on the Item Maintenance form, used to indicate when the
Item Maintenance window has been closed. This event closes the
Environmental Details form and removes it from memory.
• A change event for the Item Number field in the Item Maintenance window,
used to keep the Environmental Details window updated with the current item
being displayed.
• A change event for the Item Description field in the Item Maintenance window,
used to keep the Environmental Details window updated with the current item
being displayed.
• A change event for the Save Record field in the Item Maintenance window,
used to save the environmental details when the user saves the item.
• An after modal dialog event for the Item Maintenance window, used to retrieve
the response when the user confirms whether to delete the current item. If the
user chooses to delete the current item, the corresponding environmental
details information is also deleted.
Macro support
Calls to the RecordMacroItem() method have been added to the controls in the
Environmental Details form to support recording macro statements. The
PlayMacroItem() method from the DexUIForm base class has been overridden to
support playback of the macro statements that have been recorded.
• Overview
• Running the sample application
• How Visual Studio Tools was used
Overview
This sample application demonstrates how to implement common lookup forms in
a Visual Studio Tools integration. Refer to Chapter 14, “Using Lookups,” for details
about how to implement lookups.
• Customer Number
• Vendor ID
• Item Number
• GL Account Number
• SOP Document Number
• POP Document Number
.
Running the sample application
To run this sample application, perform the following steps:
• Application.Dynamics
• Application.SmartList
• Microsoft.Dexterity.Bridge
• Microsoft.Dexterity.Shell
If any of these references for the project are not valid, re-add them to the project.
User interface
The special WinForm available for Dynamics GP add-ins was used when creating
the Lookups window.
Resources accessed
The Lookups sample uses the following resources in the Dynamics and SmartList
dictionaries:
Forms
• AboutBox
• CustomerLookupForm
• VendorLookupForm
• IvItemNumberLookupForm
• AccountLookupForm
• SopDocumentLookupForm
• PopDocumentLookupForm
Composites
• AccountNumberCompositeData
Form-level functions
• ConvertAcctToStr of the GlAcct form
142 P R O G R A M M E R ’ S G U I D E
C H A P T E R 2 9 L O O K U P S
Events
The Lookups sample registers the following events in Microsoft Dynamics GP:
• A menu handler event for the AboutBox form, used to open the Lookups
window.
• A click event for the SelectButton field in each of the lookup windows, to notify
the Lookups sample that the user clicked the Select button.
Forms dictionary
The dictionary in a Microsoft Dynamics GP
installation that contains the modified forms
for an application. Each application
dictionary can have a forms dictionary.
Global fields
A type of field that can be used in any form
or any table in Microsoft Dynamics GP.
148 P R O G R A M M E R ’ S G U I D E
I N D E X
product support, for Visual Studio Tools sample integrations (continued) tables (continued)
for Microsoft Dynamics GP 3 Estimate Freight 133 in Microsoft Dynamics GP 47
projects Field Defaulter 131 keys for 50
adding a Dynamics GP form to 25 installing 7 learning about 47
creating for Visual Studio Tools 12 Lookups 141 methods for 104
PullFocus(), window method 89 Save(), table method 107 multiuser processing 59
saving, rows in tables 51 opening 49
R scrolling windows properties for 107
RangeClear(), table method 106 accessing current row 96 ranges 55
RangeEnd(), table method 106 accessing through code 95 removing rows 53
RangeRemove(), table method 106 chapter 95-97 resource reference 103
ranges described 95 retrieving rows 50
example 55, 56, 57 events for 95 saving rows 51
for table access 55 preventing rows from displaying 96 updating rows 52
multi-segment key 56 resource reference 95 working with 47
removing rows in a range 57 SDK, for Microsoft Dynamics GP 2, 80 technical support, for Visual Studio Tools
simple key 55 segments for Microsoft Dynamics GP 3
RangeStart(), table method 106 defined 145 templates
recording macro statements 75 for keys 50 for Visual Studio 2010 7
RecordMacroItem() method, described 75 sharing global table buffers 48 for Visual Studio 2012 7
references, to application assemblies 37, Show() manually registering 8
71, 72 command method 112 text box controls 31
registering events 41 composite field method 126 third-party applications, application
registering Visual Studio templates 8 window field method 101 assemblies for 33
regular expressions, for parsing macro signing, application assemblies 35 toolbar, button type 29
statements 77 SN.exe, described 35 toolbar with separator, button type 30
Release, solution configuration 66 solution configuration, for a Visual Studio try...catch, using with modified and
Release(), table method 107 project 66 alternate forms 73
releasing locks on table rows 59 standard buttons 29
Remove(), table method 107 status area U
removing rows buttons 30 Uncheck(), command method 112
from tables 53 defined 145 Unlock()
multiuser considerations 62 described 26 composite field method 126
Resource Descriptions tool, described 47 StatusArea, WinForms property 26 window field method 101
Resource Reference, part 84-122 strong name key file, described 35 unregistering events 44
resources, see dictionary resources strong names, for application assemblies updating rows
responding to events 43 35 in tables 52
retrieving rows support, for Visual Studio Tools for multiuser considerations 61
from tables 50 Microsoft Dynamics GP 3 Upgrading an Integration, chapter 15-21
multiuser considerations 61 symbols in documentation 3 upgrading integrations
row locking C# integrations 15
active locking 59 T described 15
described 59 table buffers from Release 10 or later 20
passive locking 59 defined 145 from Release 9 15
releasing locks 59 described 48, 103 Visual Basic integrations 17
rows form-level 48 user interface, for Visual Studio Tools
locking 59 global 48 projects 25
removing from tables 53 sharing access 48 Using Lookups, chapter 79-82
retrieving from tables 50 table fields
saving in tables 51 accessing through code 109 V
updating in tables 52 chapter 109-110 ValidateAfterOriginal
Run(), command method 112 methods for 109 composite field event 128
runtime components, for Visual Studio properties for 110 window field event 102
Tools 11 resource reference 109 ValidateBeforeOriginal
RunValidate() table ranges, example 55, 56, 57 composite field event 128
composite field method 126 Tables, form property 87 window field event 102
window field method 101 tables Value
accessing through code 48, 103 composite field property 127
S chapter 103-107 global property 114
sample integrations closing 49 table field property 110
Environmental Details 137 errors from table operations 54 window field property 101
150 P R O G R A M M E R ’ S G U I D E
I N D E X
W
warning symbol 3
window fields
accessing through code 99
chapter 99-102
events for 102
methods for 99
properties for 101
resource reference 99
windows
accessing through code 89
chapter 89-93
events for 90
local fields 99
methods for 89
properties for 89
resource reference 89
WinForms
adding controls to 27
adding to a project 25
chapter 25-27
properties for 26
Working with Tables, chapter 47-63
X
XML files, for IntelliSense 12