visual studio tools for microsoft dynamics gp 2010 programmer’s guide€¦ · · 2011-09-09the...

Visual Studio® Tools for Microsoft Dynamics® GP 2010

Programmer’s Guide

Copyright Copyright © 2010 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.

All other trademarks are property of their respective owners.

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.

Publication date March 2010

P R O G R A M M E R ’ S G U I D E i

Contents

Introduction .................................................................................................................................................2What’s in this manual...................................................................................................................................2

What’s new in this release of Visual Studio Tools....................................................................................2

Prerequisites...................................................................................................................................................3

Symbols and conventions ............................................................................................................................3

Product support ............................................................................................................................................4

Chapter 1: SDK Installation ........................................................................................................ 5Installation procedure ..................................................................................................................................5

Template registration....................................................................................................................................6

What was installed........................................................................................................................................7

Upgrading to Visual Studio 2008................................................................................................................7

Part 1: Getting Started ............................................................................................................. 10

Chapter 2: Integration Basics..................................................................................................11What Visual Studio Tools provides .......................................................................................................... 11

Architecture ................................................................................................................................................. 11

Creating a project ........................................................................................................................................12

Chapter 3: Upgrading an Integration .............................................................................. 15Upgrading from Release 9 .........................................................................................................................15

Upgrading from Release 10 .......................................................................................................................19

Part 2: Developing Integrations ...................................................................................22

Chapter 4: WinForms ...................................................................................................................... 23Adding a Dynamics GP form to a project ...............................................................................................23

WinForm properties....................................................................................................................................24

Adding controls...........................................................................................................................................25

Chapter 5: Control Reference ................................................................................................ 27Buttons..........................................................................................................................................................27

TextBoxes......................................................................................................................................................29

Labels ............................................................................................................................................................30

ComboBoxes ................................................................................................................................................30

ListBoxes ......................................................................................................................................................30

Chapter 6: Dictionary Assembly Generator .............................................................. 31Creating application assemblies ...............................................................................................................31

Output files ..................................................................................................................................................31

Using the Dictionary Assembly Generator .............................................................................................32

Optimizing the assembly generating process.........................................................................................34

Chapter 7: Accessing Dictionary Resources ............................................................ 35Adding references.......................................................................................................................................35

Namespace...................................................................................................................................................36

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

Dictionary class ...........................................................................................................................................36

Accessing additional resources.................................................................................................................37

Variables for dictionary resources ............................................................................................................37

Chapter 8: Events .............................................................................................................................. 39Registering events.......................................................................................................................................39

Responding to events .................................................................................................................................41

Unregistering events...................................................................................................................................42

Chapter 9: Working with Tables........................................................................................... 45Tables in Microsoft Dynamics GP.............................................................................................................45

Table buffers.................................................................................................................................................46

Opening and closing tables .......................................................................................................................47

Keys...............................................................................................................................................................48

Retrieving a row..........................................................................................................................................48

Saving a row ................................................................................................................................................49

Updating a row ...........................................................................................................................................50

Removing a row ..........................................................................................................................................51

Table operation errors ................................................................................................................................52

Ranges...........................................................................................................................................................53

Row locking .................................................................................................................................................57

Multiuser processing ..................................................................................................................................57

Chapter 10: Building and Deploying ................................................................................ 63Setting assembly information....................................................................................................................63

Building an integration ..............................................................................................................................64

Deploying an integration...........................................................................................................................65

Chapter 11: Debugging................................................................................................................. 67Preparing to debug .....................................................................................................................................67

Examining the application.........................................................................................................................68

Disabling events ..........................................................................................................................................68

Chapter 12: Modified and Alternate Forms............................................................... 69Modified forms............................................................................................................................................69

Alternate forms ...........................................................................................................................................70

Guidelines ....................................................................................................................................................71

Chapter 13: Implementing Macro Support ................................................................ 73Overview of macro support ......................................................................................................................73

Recording macros .......................................................................................................................................73

Playing macros ............................................................................................................................................74

Handling asynchronous processes during playback.............................................................................76

Chapter 14: Using Lookups ...................................................................................................... 77How lookups work .....................................................................................................................................77

Available lookups........................................................................................................................................78

Lookup example..........................................................................................................................................78

P R O G R A M M E R ’ S G U I D E iii

C O N T E N T S

Part 3: Resource Reference ................................................................................................82

Chapter 15: Forms............................................................................................................................. 83Accessing forms ..........................................................................................................................................83

Form methods .............................................................................................................................................83

Form properties...........................................................................................................................................85

Form events .................................................................................................................................................86

Chapter 16: Windows ..................................................................................................................... 87Accessing windows ....................................................................................................................................87

Window methods........................................................................................................................................87

Window properties .....................................................................................................................................87

Window events............................................................................................................................................88

Chapter 17: Scrolling Windows ............................................................................................ 93Accessing scrolling windows ....................................................................................................................93

Scrolling window methods........................................................................................................................93

Scrolling window properties.....................................................................................................................93

Scrolling window events............................................................................................................................93

Chapter 18: Window Fields ....................................................................................................... 97Accessing window fields ...........................................................................................................................97

Window field methods...............................................................................................................................97

Window field properties ............................................................................................................................99

Window field events.................................................................................................................................100

Chapter 19: Tables ......................................................................................................................... 101Accessing tables ........................................................................................................................................101

Table methods............................................................................................................................................102

Table properties .........................................................................................................................................105

Chapter 20: Table Fields ........................................................................................................... 107Accessing table fields ...............................................................................................................................107

Table field methods...................................................................................................................................107

Table field properties ................................................................................................................................108

Chapter 21: Commands ............................................................................................................ 109Command types ........................................................................................................................................109

Accessing commands ...............................................................................................................................109

Command methods ..................................................................................................................................109

Chapter 22: Globals....................................................................................................................... 111Accessing globals ...................................................................................................................................... 111

Global properties....................................................................................................................................... 111

Chapter 23: Procedures ............................................................................................................ 113Accessing global procedures ................................................................................................................... 113

Accessing form-level procedures............................................................................................................ 113

Procedure methods................................................................................................................................... 113

Procedure events....................................................................................................................................... 114

Parameters for procedures....................................................................................................................... 115

iv P R O G R A M M E R ’ S G U I D E

C O N T E N T S

Invokable procedures ............................................................................................................................... 116

Chapter 24: Functions .................................................................................................................117Accessing global functions ...................................................................................................................... 117

Accessing form-level functions............................................................................................................... 117

Function methods ..................................................................................................................................... 118

Function events ......................................................................................................................................... 118

Parameters for functions.......................................................................................................................... 119

Invokable functions ..................................................................................................................................120

Chapter 25: Composites........................................................................................................... 121Composite types........................................................................................................................................121

Accessing composites...............................................................................................................................121

Composite field methods.........................................................................................................................123

Composite field properties ......................................................................................................................125

Composite field events.............................................................................................................................126

Part 4: Integration Examples ........................................................................................ 128

Chapter 26: Field Defaulter ................................................................................................... 129Overview....................................................................................................................................................129

Running the sample application.............................................................................................................129

How Visual Studio Tools was used ........................................................................................................130

Chapter 27: Estimate Freight............................................................................................... 131Overview....................................................................................................................................................131



Chapter 28: Environmental Details ................................................................................ 135Overview....................................................................................................................................................135



Chapter 29: Lookups ................................................................................................................... 139Overview....................................................................................................................................................139



Glossary ..................................................................................................................................................... 143

Index ............................................................................................................................................................... 145

INT

RO

DU

CT

ION

2 P R O G R A M M E R ’ S G U I D E

IntroductionWelcome to Visual Studio® Tools for Microsoft Dynamics® GP. This documentationexplains how to integrate applications you create with Visual Studio into MicrosoftDynamics GP. Before you begin creating an integration for Microsoft Dynamics GP,take a few moments to review the information presented here.

What’s in this manual

The Visual Studio Tools for Microsoft Dynamics GP Programmer’s Guide isdesigned to give you an in-depth understanding of how to use these tools to createan application that integrates with Microsoft Dynamics GP. Even if you are familiarwith using Visual Studio to develop applications, you will find it helpful to browsethe material presented here.

Information is divided into the following parts:

• Part 1, Getting Started, explains how to install Visual Studio Tools for MicrosoftDynamics GP and begin creating an integration.

• Part 2, Developing Integrations, provides detailed information about creatingWinForms that match the Microsoft Dynamics GP appearance. Interacting withMicrosoft Dynamics GP through events is discussed. Building, deploying, anddebugging integrations are also addressed.

• Part 3, Resource Reference, provides detailed information about interactingwith the various types of resources in Microsoft Dynamics GP.

• Part 4, Integration Examples, describes example integrations that use VisualStudio Tools for Microsoft Dynamics GP.

What’s new in this release of Visual Studio Tools

Refer to the following list for more information about the new features added forthis release of Visual Studio Tools for Microsoft Dynamics GP.

1. Modal dialog eventsEvents for modal dialogs have been added. These events allow you to modifyand respond to the modal dialog windows in Microsoft Dynamics GP. Refer toBeforeModalDialog and AfterModalDialog in Chapter 16, “Windows,” fordetails about using these new events.

2. Procedure eventsEvents for procedures have been added. Refer to Procedure events on page 114for more information.

3. Function eventsEvents for functions have been added. Refer to Function events on page 118 formore information.

4. Events can be unregisteredSome events in Visual Studio Tools can now be unregistered. See Unregisteringevents on page 42 for more information.

P R O G R A M M E R ’ S G U I D E 3

I N T R O D U C T I O N

5. Table buffers as parametersYou can now access procedures and functions that have table buffers asparameters.

6. Macro supportYou can add code to forms you create with Visual Studio Tools so that the formscan be accessed by the macro system in Microsoft Dynamics GP. Refer toChapter 13, “Implementing Macro Support,” for more information.

Prerequisites

You must be using Microsoft Dynamics GP 2010. Since you will be working withMicrosoft Dynamics GP, knowledge of the accounting system will be helpful.Consult the Microsoft Dynamics GP documentation resources to learn more aboutthe product.

You will also want to install the SDK for Microsoft Dynamics GP. The SDK isavailable in the Tools folder on the Microsoft Dynamics GP installation media. Itcontains useful information about Microsoft Dynamics GP, such as lists ofcommonly-used procedures and functions.

To use Visual Studio Tools for Microsoft Dynamics GP, Visual Studio 2005 withService Pack 1 or Visual Studio 2008 is required. Earlier versions of Visual Studiocannot be used. It is assumed that you are familiar with programming in a managedlanguage such as C#. This documentation uses both C# and Visual Basic todemonstrate how to create integrations.

Symbols and conventions

To help you use this documentation more effectively, we’ve used the followingsymbols and conventions within the text to make specific types of informationstand out.

Symbol Description

The light bulb symbol indicates helpful tips, shortcuts, and suggestions.

Warnings indicate situations you should be aware of when completing tasks.

Margin notes summarize important information.

Margin notes call attention to critical information and 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 5, “Web Methods” 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 Generator (DAG)

Acronyms are spelled out the first time they’re used.

TAB or ALT+M Small capital letters indicate a key or a key sequence.

I N T R O D U C T I O N


Product supportMicrosoft Dynamics GP developer technical support can be accessed online or bytelephone. Go to www.microsoft.com/dynamics and click the CustomerSource orPartnerSource link, or call 888-477-7877 (in the US and Canada) or 701-281-0555.

http://www.microsoft.com/dynamics


Chapter 1: SDK InstallationThe Visual Studio Tools for Microsoft Dynamics GP SDK contains the componentsneeded to create and build integrations. The following topics are discussed:

• Installation procedure• Template registration• What was installed• Upgrading to Visual Studio 2008

Installation procedure

The Visual Studio Tools for Microsoft Dynamics GP SDK installer requires VisualStudio 2005 or Visual Studio 2008 to be installed first. For testing integrations, youwill also want Microsoft Dynamics GP installed.

If you have installed an earlier version of the Visual Studio Tools SDK, be sure that youremove it from the system before you install the new version.

To install the Visual Studio Tools for Microsoft Dynamics GP SDK, complete thefollowing procedure:

1. Start the Visual Studio Tools SDK installer.Start the installer by running the VSToolsSDK.exe.

2. View the welcome screen.Click Next to continue.

3. Acknowledge the license agreement.Read and acknowledge the license agreement. Click Next to continue.

4. Specify the features to install.Choose the features that will be installed:

5. Specify the installation location.Use the default location, or choose another location. Click next to continue.

Feature Description

Visual Studio 2005 Templates The C# and Visual Basic templates for projects and forms. Visual Studio 2005 is required to install this feature.

Visual Studio 2008 Templates The C# and Visual Basic templates for projects and forms. Visual Studio 2008 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 Generator

The Dictionary Assembly Generator (Dag.exe) and the 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.

P A R T 1 G E T T I N G S T A R T E D


6. Begin the installation.Click Install to begin installing the SDK components.

During the installation, Visual Studio must be reconfigured to recognize the newtemplates being installed. This process may take a few minutes to complete.

7. Finish the installation.Click Finish to complete the installation.

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 inVisual Studio. You may need to manually register the templates so they will appearas selections when you create new projects.

To register the templates, perform the following command to have Visual Studio2005 re-create its template cache:

C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\devenv.exe /setup

Use the following command for Visual Studio 2008 to re-create its template cache:

C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe /setup

On systems that are running with UAC (User Account Control), you will need to setthe properties of the devenv.exe application to be run with administrativeprivileges.

On systems with UAC,choose to run devenv.exe

as an administrator.


C H A P T E R 1 S D K I N S T A L L A T I O N

What was installed

The following items are installed for Visual Studio Tools for Microsoft Dynamics GPin the location you specified:

If you chose to install them, the project templates for C# and Visual Basic will be inthe appropriate locations for Visual Studio.

Upgrading to Visual Studio 2008

If you have previously installed the Visual Studio Tools for Microsoft Dynamics GP2010 SDK and want to upgrade from Visual Studio 2005 to Visual Studio 2008,complete the following procedure:

1. Install Visual Studio 2008.

2. Start the Visual Studio Tools SDK installer.Start the installer by running the VSToolsSDK.exe. The updated components forVisual Studio Tools will be installed.

3. Close the installer.When the installer has finished updating components, click Finish.

4. Change the Visual Studio Tools installation.In Add or Remove Programs (Windows XP or Windows Server 2003) orPrograms and Features (Windows Vista, Windows 7, or Windows Server 2008)choose Visual Studio Tools for Microsoft Dynamics GP 2010 SDK. Click Change.

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.dllMicrosoft.Dexterity.Shell.dllMicrosoft.Dynamics.Framework.UI.Navigation.dllMicrosoft.Dynamics.Framework.UI.WinForms.Controls.dll

Core Microsoft Dynamics GP components used by Visual Studio Tools integrations.

Dag.exe The Dictionary Assembly Generator, used to create application assemblies for application dictionaries and forms dictionaries.

Bidi32.dllDdapi.dllTntlib.dllDex.dicDex.ini

Support files needed for Dag.exe

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.



5. Add a new feature.Click Add/Remove Features to add a new feature to the Visual Studio Toolsinstallation.

6. Install the Visual Studio 2008 templates.Mark the option to install the Visual Studio 2008 templates, and then click Next.Click Install to begin the installation process.

7. Finish the installation.Click Finish to complete the installation.

PA

RT

1: G

ET

TIN

G S

TA

RT

ED


Part 1: Getting StartedThis portion of the documentation describes how to get started creating anintegration using Visual Studio Tools for Microsoft Dynamics GP. The followingtopics are discussed:

• Chapter 1, “SDK Installation,” explains how to install Visual Studio Tools SDKfor Microsoft Dynamics GP.

• Chapter 2, “Integration Basics,” describes the architecture of a Visual StudioTools for Microsoft Dynamics GP integration. It also explains how to create aproject for a new integration.

• Chapter 3, “Upgrading an Integration,” explains how to upgrade an existingintegration to work with the current version of Visual Studio Tools for MicrosoftDynamics GP.


Chapter 2: Integration BasicsBefore you create an integration using Visual Studio Tools for Microsoft DynamicsGP, it will be helpful to understand the basics of an integration. The following topicsare discussed:

• What Visual Studio Tools provides• Architecture• Creating a project

What Visual Studio Tools provides

Visual Studio Tools for Microsoft Dynamics GP provides three main capabilities foran integrating application:

Customized WinFormsAny WinForms included in an integrating application can use capabilities providedby Visual Studio Tools for Microsoft Dynamics GP to match the appearance of thecore application. The appearance of the window as well as the various controls inthe window can be customized. You will learn about creating windows for yourintegration in Chapter 4, “WinForms,” and Chapter 5, “Control Reference.”

Access to dictionary resourcesIntegrating applications have access to the numerous resources available in theapplication dictionaries used for Microsoft Dynamics GP. An integratingapplication can access the forms, windows, window fields, tables, and table fields ineach dictionary. They can also access global variables, commands, procedures, andfunctions defined in each dictionary. You will learn about accessing dictionaryresources in Chapter 7, “Accessing Dictionary Resources.”

Access to eventsIntegrating applications can be notified of events that occur in Microsoft DynamicsGP, such as a window being opened, or the focus moving to a field. The applicationscan respond to the events, performing actions like verifying field values or openingadditional windows. Chapter 8, “Events,” contains information about registeringfor and responding to events.

Architecture

Visual Studio Tools for Microsoft Dynamics GP consists of runtime components anddevelopment components.

Runtime componentsThe runtime components for Visual Studio Tools are installed with MicrosoftDynamics GP, and provide the functionality used by the integrations. These consistof the following:

Dexterity Shell This assembly (Microsoft.Dexterity.Shell.dll) provides thedrawing capabilities that allow an integrating application to match the appearanceof Microsoft Dynamics GP.

Dexterity Bridge This assembly (Microsoft.Dexterity.Bridge.dll) provides theaccess to events in Microsoft Dynamics GP, as well as the resources in theapplication dictionaries.



Application assemblies Each dictionary that will be accessed by a VisualStudio Tools for Microsoft Dynamics GP integration will have an applicationassembly. Each application assembly provides access to the resources in itscorresponding dictionary. For example, the Application.Dynamics.dll assemblyprovides access to the resources in the Dynamics.dic dictionary.

Visual Studio Tools for Microsoft Dynamics GP includes the application assembliesfor all the modules that ship with Microsoft Dynamics GP. You can use theDictionary Assembly Generator tool (Dag.exe) to create application assemblies forother third-party dictionaries for Microsoft Dynamics GP. You will learn more aboutthis tool in Chapter 6, “Dictionary Assembly Generator.”

AddIns folder The assemblies for the integrating applications created withVisual Studio Tools for Microsoft Dynamics GP are placed in this folder. WhenMicrosoft Dynamics GP is launched, it automatically looks in this folder andattempts to launch the integrating applications it finds there.

Development componentsThe following development components are installed in the folder where you choseto install Visual Studio Tools for Microsoft Dynamics GP:

DAG.exe This is the Dictionary Assembly Generator tool, used to createapplication assemblies for dictionaries. You will use this to create applicationassemblies for third-party dictionaries that do not have them. You will also use it tocreate application assemblies for forms dictionaries in cases where your integrationmust interact with modified forms in Microsoft Dynamics GP.

IntelliSense XML files The IntelliSense XML file contains the informationabout the application assembly that is displayed in the IntelliSense within VisualStudio. The name of the application XML file matches that of the applicationassembly it corresponds to. For example, the Application.Dynamics.xml filecontains 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 inVisual Basic.

Visual C# project This is the template project for an add-in that is based inVisual C#.

Creating a project

Use the following procedure to create a new Visual Studio project for a MicrosoftDynamics GP add-in.

1. Start Visual Studio.If it isn’t already running, start Visual Studio.

2. Create a new project.In the File menu, point to New and choose Project.

3. Select the project type.Choose either a Visual Basic project or a Visual C# project. Under the type youhave selected, choose Dynamics GP.


C H A P T E R 2 I N T E G R A T I O N B A S I C S

4. Choose the Microsoft Dynamics GP Add-in template.In the list of available templates, choose the Microsoft Dynamics GP Add-inproject template.

If the Microsoft Dynamics GP templates are not listed, you may need to register themmanually. Refer to Template registration on page 6 for details about doing this.

5. Specify the name and location of the project.Click OK to create the project.


Chapter 3: Upgrading an IntegrationIf you have created an integration with Visual Studio Tools for an earlier release ofMicrosoft Dynamics GP, use the following procedures to upgrade your integrationto work with the current version of Visual Studio Tools. Be sure you have installedthe current version of Visual Studio Tools before attempting to upgrade yourintegrations. The following upgrade procedures are described:

• Upgrading from Release 9• Upgrading from Release 10

Upgrading from Release 9

If your integration was created with Release 9 of Visual Studio Tools, use thefollowing procedures to upgrade your integration to work with Visual Studio Toolsfor Microsoft Dynamics GP 2010. Separate procedures are included for C# andVisual Basic.

C# integrationUse the following procedure to upgrade a Visual Studio Tools integration createdwith C#.

1. Open the solution for your integration.Using Visual Studio, open the solution file for the integration you want toupgrade.

2. Rebuild application assemblies.If you had built any application assemblies for your integration, you will needto re-build them so they are up-to-date with the latest version of MicrosoftDynamics GP.

3. Update the assembly references.The assembly references for the project will be incorrect, because they won’trefer to the new versions of the Visual Studio Tools components and applicationassemblies.

Add references to the updated Visual Studio Tools assemblies, to replace thebroken references.

The reference to the Microsoft.Dexterity.Shell.UI assembly is a special situation. Thiscomponent was merged into the Microsoft.Dexterity.Shell assembly. Create a referenceto the Microsoft.Dexterity.Shell assembly, and delete the reference to theMicrosoft.Dexterity.Shell.UI assembly.

The assembly referencesare incorrect and need to

be updated.



4. Update the namespaces used in integration code.The namespace for the shell (user interface) components of the Visual StudioTools integration has changed. The namespace reference must be changed from:

Microsoft.Dexterity.Shell.UI

To the updated value:

Microsoft.Dexterity.Shell

5. Update the namespace references used for any forms.The same namespace change must be made for any forms you created for yourintegration. When you attempt to open a form in the Visual Studio designer,you will see an error similar to the following:

This means that the code used for the form is using the old namespace, ratherthan the new Microsoft.Dexterity.Shell namespace. You must view the code forthe 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 fixedis 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 theform designer if it is still open, and then re-open the form. The form should nowopen and have the updated Microsoft Dynamics GP appearance.

6. Build the solution.Choose to build the updated solution in Visual Studio. You may encounterbuild errors if your integration references resources in Microsoft Dynamics GPthat have been deleted, moved, or renamed. You will need to fix these issuesand rebuild the integration.


C H A P T E R 3 U P G R A D I N G A N I N T E G R A T I O N

Visual Basic integrationUse the following procedure to upgrade a Visual Studio Tools integration createdwith Visual Basic.




Add references to the updated Visual Studio Tools assemblies, to replace thebroken references.

The reference to the Microsoft.Dexterity.Shell.UI assembly is a special situation. Thiscomponent was merged into the Microsoft.Dexterity.Shell assembly. Create a referenceto the Microsoft.Dexterity.Shell assembly, and delete the reference to theMicrosoft.Dexterity.Shell.UI assembly.

4. Update the namespaces used in integration code.The namespace for the shell (user interface) components of the Visual StudioTools integration has changed. Any namespace reference must be changedfrom:

Microsoft.Dexterity.Shell.UI

To the updated value:

Microsoft.Dexterity.Shell

The assembly referencesare incorrect and need to

be updated.



5. Update the namespace references used for any forms.The same namespace change must be made for any forms you created for yourintegration. When you attempt to open a form in the Visual Studio designer, thecode for the form will be displayed:

6. Update the form designer code.Open the “Designer” source file for the form to fix the references so they use thenew Microsoft.Dexterity.Shell namespace. Change all of the namespacereferences to remove the “UI” portion. This will be required in several places.An example of code to be fixed is shown in the following illustration.

After making these changes to the form’s code, save the updated file. Re-openthe form. The form should appear in the form designer and have the updatedMicrosoft Dynamics GP appearance.


Fix the namespacereferences for the form.

Fix all of the referencesto use the new

Microsoft.Dexterity.Shellnamespace.


C H A P T E R 3 U P G R A D I N G A N I N T E G R A T I O N

Upgrading from Release 10

If your integration was created with Release 10 of Visual Studio Tools, use thefollowing procedures to upgrade your integration to work with Visual Studio Toolsfor Microsoft Dynamics GP 2010. The upgrade procedure is relatively simple. Thesame procedure can be used for both C# and Visual Basic.




Add references to the updated Visual Studio Tools assemblies, to replace theincorrect references.


PA

RT

2: D

EV

ELO

PIN

G IN

TE

GR

AT

ION

S


Part 2: Developing IntegrationsThis portion of the documentation describes the various techniques you will use asyou develop integrations using Visual Studio Tools for Microsoft Dynamics GP. Thefollowing topics are discussed:

• Chapter 4, “WinForms,” describes how to create WinForms that have theappearance of windows in Microsoft Dynamics GP.

• Chapter 5, “Control Reference,” provides details of the various controls that aremodified by Visual Studio Tools for Microsoft Dynamics GP.

• Chapter 6, “Dictionary Assembly Generator,” describes the tool used to create.NET assemblies that provide access to dictionary resources.

• Chapter 7, “Accessing Dictionary Resources,” explains how to access resourcesin dictionaries from your integrating application.

• Chapter 8, “Events,” describes how to register for and respond to events forMicrosoft Dynamics GP.

• Chapter 9, “Working with Tables,” describes how to directly access MicrosoftDynamics GP tables from an integration.

• Chapter 10, “Building and Deploying,” explains how to build and deploy anintegration you have created.

• Chapter 11, “Debugging,” explains how to debug an integration created withVisual Studio Tools for Microsoft Dynamics GP.

• Chapter 12, “Modified and Alternate Forms,” describes how to access resourceson modified forms and alternate forms in Microsoft Dynamics GP.

• Chapter 13, “Implementing Macro Support,” explains how to make formscreated with Visual Studio Tools accessible by the macro system in MicrosoftDynamics GP.

• Chapter 14, “Using Lookups,” describes how to use existing lookups fromMicrosoft Dynamics GP in your Visual Studio Tools integration.


Chapter 4: WinFormsStandard WinForms are the basis for the user interface for add-ins created withVisual Studio Tools for Microsoft Dynamics GP. These WinForms and the controlsplaced on them are specially modified to match the appearance of MicrosoftDynamics GP. Information about WinForms is divided into the following sections:

• Adding a Dynamics GP form to a project• WinForm properties• Adding controls

Adding a Dynamics GP form to a project

To add a new Dynamics GP form to an add-in project, complete the followingprocedure:

1. Add a new component.In Visual Studio, choose Add Component from the Project menu.

2. Select a Microsoft Dynamics GP Form.In the list of templates, choose a Microsoft Dynamics GP form.

3. Name the new form.Give the form a name that is appropriate for how it will be used.

4. Add the new form.Click Add to add the new WinForm to the project.

5. Specify the form properties.Set the necessary properties for the new form.

Choose a MicrosoftDynamics GP Form.

P A R T 2 D E V E L O P I N G I N T E G R A T I O N S


WinForm properties

WinForms that are added to a Visual Studio Tools for Microsoft Dynamics GPproject have several additional properties that control their appearance. Settingthese 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 inVisual Studio.

AutoSetDexColorsThe AutoSetDexColors property controls whether the colors used for the WinFormwill automatically match the color scheme selected in the user preferences withinMicrosoft Dynamics GP. Set this property to True to match the Microsoft DynamicsGP appearance.

ControlAreaThe ControlArea property specifies whether the band called the control area isdrawn 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. Setthis property to True to display the control area for a WinForm.

StatusAreaThe StatusArea property specifies whether the band called the status area is drawnat the bottom of the WinForm. A divider line is drawn across the bottom of theWinForm to indicate the status area. In standard Microsoft Dynamics GP windows,controls like browse buttons, note buttons, and help buttons are placed in the statusarea. Set this property to True to display the status area for a WinForm.

This is the control area.

This is the status area.


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 thesame way you add them to standard windows forms. Simply select the control inthe Toolbox and drag it out onto the form.

When you add the controls, additional properties will be available for some of themto match the Microsoft Dynamics GP appearance. For example, push buttons willhave additional properties. Refer to Chapter 5, “Control Reference,” for moreinformation about individual controls.

To add a control, justselect it in the Toolbox

and drag it onto the form.


Chapter 5: Control ReferenceYou can use any of the available controls on the WinForms for your MicrosoftDynamics GP integration. Some of the standard controls have been customized tobetter match the appearance of Microsoft Dynamics GP. This portion of thedocumentation describes the controls that have additional properties or updatedcharacteristics when used on a WinForm in a Visual Studio Tools for MicrosoftDynamics 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 GPform. The button controls on a WinForm for a Microsoft Dynamics GP project gettheir additional characteristics from the dexButtonProvider you see on theWinForm layout. The ButtonType property is an additional property available foreach button. It specifies how the button control is displayed and whatcharacteristics it will have. You can set the AutoSetDexColors property to True sothe button colors will match colors in Microsoft Dynamics GP.

The following is a list of the settings for the ButtonType property, and a descriptionof how each button type is used.

StandardStandard buttons don’t have their appearance modified changed when placed on aWinForm for a Dynamics GP project. The following illustration shows a standardbutton.

ToolbarButtons with the ButtonType set to Toolbar are typically placed in the control area ofa Microsoft Dynamics GP form. These buttons have a flat appearance, with a specialcolor highlighting when the pointer is placed over them. It is also common for thesebuttons to have pictures on them. The following illustration shows a toolbar button.

This is a standard button

A toolbar button istypically placed in the

control area.



ToolbarWithSeparatorThe buttons with the type ToolbarWithSeparator buttons are typically placed in thecontrol area, like buttons with the type Toolbar. However, they have an additionalseparator line drawn on the right side of the button to separate it from the othercontrols in the control area. The following illustration shows two buttons that havethe type ToolbarWithSeparator. Notice the separator line drawn to the right of eachbutton.

StatusAreaButtons placed in the status area at the bottom of a window should have the typeStatusArea. These buttons should display only graphics, and will have a special 3-Dborder drawn around them when the pointer is placed over them. These buttonsshould have the Tooltip property set so they will display a description of the actionthe button performs. A status area button is shown in the following illustration. Itdisplays a tooltip that describes the purpose of the button.

FieldButtons that show only pictures, and are placed next to other controls in the formshould have the ButtonType property set to Field. These buttons are used for thingslike lookups or expansions. Several buttons with this type are shown next to a textcontrol in the following illustration.

Pictures for buttonsEach Visual Studio for Microsoft Dynamics GP project includes several standardimages that are used for buttons in Microsoft Dynamics GP. These images (in PNGformat) should be used with the buttons you create for your integrations. Thefollowing table lists the images and describes how they are used.

These are toolbar buttonswith separators.

Buttons in the status areatypically have only pictures.

These are field buttons.

Image Name Description

Field_Delete.png Used for delete buttons in the window area placed next to fields.

Field_Edit.png Used for edit buttons in the window area placed next to fields.

Field_Expansion.png Used for expansion buttons in the window area placed next to fields.

Field_Lookup.png Used for lookup buttons in the window area placed next to fields.

Field_MapPoint.png Used for MapPoint buttons in the window area placed next to fields.


C H A P T E R 5 C O N T R O L R E F E R E N C E

TextBoxes

TextBox controls are used for the string, integer, currency, date, and time controls ina Microsoft Dynamics GP form. Text boxes have the AutoSetDexColors propertythat can be set to True so the control colors will match colors in Microsoft DynamicsGP.

Field_NoteAbsent.png Used for note buttons in the window area placed next to fields.

Field_NotePresent.png Used for note buttons in the window area placed next to fields.

HelpImage.png Used for the Help button placed in the status area of the window.

Toolbar_Cancel.png Used for the Cancel button placed in the window control area.

Toolbar_Clear.png Used for the Clear button placed in the window control area.

Toolbar_Copy.png Used for the Copy button placed in the window control area.

Toolbar_Delete.png Used for the Delete button placed in the window control area.

Toolbar_DeleteAll.png Used for the Delete All button placed in the window control area.

Toolbar_New.png Used for the New button placed in the window control area.

Toolbar_Open.png Used for the Open button placed in the window control area.

Toolbar_Post.png Used for the Post button placed in the window control area.

Toolbar_Print.png Used for the Print button placed in the window control area.

Toolbar_Redisplay.png Used for the Redisplay button placed in the window control area.

Toolbar_Save.png Used for the Save button placed in the window control area.

Toolbar_Void.png Used for the Void button placed in the window control area.

VCR_First.png Used for the First browse control in the window status area.

VCR_Last.png Used for the Last browse control in the window status area.

VCR_Next.png Used for the Next browse control in the window status area.

VCR_Previous.png Used for the Previous browse control in the window status area.

Window_NoteAbsent.png Used for the note button in the window status area.

Window_NotePresent.png Used for the note button in the window status area.

Image Name Description

A TextBox control is usedfor standard fields like

currency values.



Unlike the standard controls in Microsoft Dynamics GP, the textbox controls haveno built-in support to format data such as currency values. You will need to addadditional code to your integration to match the behavior of the controls inMicrosoft Dynamics GP. For instance, the following C# code sets the value of thetextbox in the previous illustration. It uses the Format method for the String objectto format the currency value.

// Display the value, formatting it as a currency amount

textBoxEstimatedFreight.Text = String.Format("{0:C}",EstimatedFreight);

Labels

Label controls are used for the text labels that appear next to controls in theMicrosoft Dynamics GP form. They correspond to the static text items that appearin standard Microsoft Dynamics GP windows.

Label controls have the LinkField property that should be set when a specific fieldis being labeled. This property is set to the name of the control that the label appliesto. When specified in the Microsoft Dynamics GP User Preferences, the label will bedrawn 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 setto False.

ComboBoxes

Use the ComboBox control in cases where you would use a drop-down list orcombo box in Microsoft Dynamics GP. ComboBox controls have theAutoSetDexColors property that can be set to True so the control colors will matchcolors in Microsoft Dynamics GP.

The following illustration shows a ComboBox control being used as a drop-downlist in a Microsoft Dynamics GP form.

ListBoxes

Use the ListBox control in cases where you would used a list box or multi-select listbox in Microsoft Dynamics GP.

A label control displaysthe text label that appears

next to another control.


Chapter 6: Dictionary Assembly GeneratorThe Dictionary Assembly Generator (DAG.exe) is a utility included with VisualStudio Tools for Microsoft Dynamics GP that creates a managed code assembly thatprovides access to resources in an application dictionary. Information about this toolis divided into the following sections:

• Creating application assemblies• Output files• Using the Dictionary Assembly Generator• Optimizing the assembly generating process

Creating application assemblies

Several application assemblies are included with the Visual Studio Tools forMicrosoft Dynamics GP. These are the assemblies for the core application(Dynamics.dic) and the other applications that are delivered with MicrosoftDynamics GP.

When developing integrations that use resources from these dictionaries, alwaysuse the application assemblies that are included with the Visual Studio Toolsinstallation. These assemblies are digitally signed, indicating they were producedby Microsoft. Don’t generate your own versions of application assemblies fordictionaries shipped with the Microsoft Dynamics GP product.

You will create application assemblies for the following cases:

• A forms dictionary exists for a product, and you want your Microsoft DynamicsGP integration to access the modified resources in the forms dictionary.

• You have installed a third-party dictionary for which no application assemblyexists, and you want to access resources in this dictionary from your MicrosoftDynamics GP integration. The third-party dictionary could contain new formsand other resources. It could contain alternate forms from the Dynamics.dicdictionary.

Output files

The Dictionary Assembly Generator produces two output files that are used in yourintegration: an application assembly and IntelliSense data file.

Application assemblyThe most important output is the application assembly. This is the managed codeassembly that provides access to the resources in a dictionary. Each dictionary canhave one corresponding application assembly.

The following naming convention is used for application dictionaries:

Application.ProductName.dll

The following naming convention is used for forms dictionaries:

Application.ProductName.ModifiedForms.dll



ProductName is automatically derived from product name in the launch file. Anyspaces or special characters in the product name are removed.

For example, the application assembly that provides access to resources in theSRVCADV.dic application dictionary is named Application.FieldService.dll. Theapplication assembly that provides access to the resources in the forms dictionary(FRMS949..dic) is named Application.FieldService.ModifiedForms.dll.

IntelliSense data fileThe second type of output from the Dictionary Assembly Generator is theIntelliSense data file that will be used by Visual Studio. This file has the same nameas its corresponding application assembly, but has the .xml extension. As you writecode, Visual Studio will use the information from this file to display details aboutthe resources that can be accessed through the application assembly. An example ofthe IntelliSense for a dictionary resource is shown in the following illustration.

Using the Dictionary Assembly Generator

The Dictionary Assembly Generator (DAG.exe) is installed in the location whereyou installed Visual Studio Tools. Typically this will be the following location:

C:\Program Files\Microsoft Dynamics\GP2010 VS Tools SDK

The Dictionary Assembly Generator is a command-line tool, and should be runfrom a command prompt. Open a command prompt and set the current location tothe folder where DAG.exe is located.

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 dictionaryfor which you want to build the application assembly. Look in the launch file(typically Dynamics.set) for a list of the products installed.

Information from theapplication assembly

XML file is displayed inIntelliSense.


C H A P T E R 6 D I C T I O N A R Y A S S E M B L Y G E N E R A T O R

Optionally, you can specify the launch file that the Dictionary Assembly Generatorwill look in to find the list of installed products and the corresponding dictionarylocations. If you don’t supply the name of the launch file, DAG.exe will look for thelaunch file named Dynamics.set in the current location.

Since you are running DAG.exe from a different location than where Microsoft DynamicsGP 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 beingrun from. This means the user running DAG.exe must be part of the Administrators groupor the Power Users group on Windows XP. On a system running with User AccountControl (UAC), it means launching DAG.exe with Administrative privileges.

Building an application assemblyThe Dictionary Assembly Generator will build an application assembly for the maindictionary for an application or for the forms dictionary for an application. Whengenerating an assembly for an application dictionary, use the /M parameter. Forexample, the following command generates the application assembly for the maindictionary of the Sample Integrating Application. This application has the productID value 3333. The path to the launch file (Dynamics.set) is supplied.

dag.exe 3333 "C:\Program Files\Microsoft Dynamics\GP\Dynamics.set" /M

This command produces two files:

• 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 dictionaryof the Field Service product (with dictionary ID 949).

dag.exe 949 "C:\Program Files\Microsoft Dynamics\GP\Dynamics.set" /F

This command produces two files:

• Application.FieldService.ModifiedForms.dll• Application.FieldService.ModifiedForms.xml

Refer to Modified forms on page 69 for details about creating an application assembly for theforms dictionary (Forms.dic) used by Microsoft Dynamics GP.

Signing an application assemblyYou may want to sign the application assemblies you create. This is a good practice,because it helps ensure that only the official version of an application assembly isbeing used. The Dictionary Assembly Generator can sign the assemblies that itcreates. It can fully sign the assemblies, or delay sign them. You can use the SN.exeutility (included with the .NET Framework) to create a strong name key file (.snk)used to sign the assembly.

Once you create and use a strong name key file, keep it in a safe location. You will need to useit every time you build or rebuild application assemblies.

The following example shows how the application assembly for the sampleintegrating application is fully signed using the Sample.snk strong name key. TheSample.snk file was generated using the SN.exe utility.


/S:Sample.snk



Overriding the application assembly nameWhen creating an application assembly for a dictionary, the Dictionary AssemblyGenerator will use the product name from the launch file. This may not be the nameyou want to use for the application assembly. You can use the /N parameter tospecify a different name for the application assembly being generated.

For example, the following command will create an application assembly for thesample integrating application, but use the name “Develop” instead of the productname in the launch file.


/N:Develop

The generated application assembly will have the name Application.Develop.dll.

Overriding the main referenced dictionary nameWhen generating application assemblies for dictionaries that integrate withMicrosoft Dynamics GP, the Dictionary Assembly Generator must be able toreference the application assembly for the main dictionary (typicallyApplication.Dynamics.dll). If the application assembly for the main dictionary hasbeen given a different name, you can use the /NM parameter to specify which newname so the application assembly can be found.

For example, if the application assembly for the main dictionary was namedApplication.DynamicsGP.dll, you would use the following command to create anapplication assembly for the sample integrating application. Notice that the /NMparameter is used to specify the name of the main application assembly that is beingreferenced.


/NM:DynamicsGP

Optimizing the assembly generating process

Producing an application assembly for large dictionaries is a resource-intensiveprocess. The Dictionary Assembly Generator will use a large amount of memory(often over 1 gigabyte) and substantial processor time when producing anapplication assembly. To optimize the process, do the following:

• Use the best hardware you have available to generate the application assembly.

• Close all other applications before starting the process.

• Temporarily turn off background processing tasks, such as virus scanning.


Chapter 7: Accessing Dictionary ResourcesTo create an integration for Microsoft Dynamics GP or the additional applicationsthat are installed with it, your code must access resources in the various applicationdictionaries. This portion of the documentation describes how to do this for yourproject. 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 tothe application assembly for that dictionary. When you create a new Visual StudioTools for Microsoft Dynamics GP project, it will automatically contain a reference tothe Application.Dynamics.dll application assembly. This provides access toresources in the Dynamics.dic dictionary. To access resources in other dictionaries,add references to the application assemblies for them.

If a dictionary doesn’t have a corresponding application assembly, refer to Chapter 6,“Dictionary Assembly Generator,” to learn how to create one.

For example, to access resources from the “Sample Integrating App” applicationinstalled with Microsoft Dynamics GP, the project should contain a reference to theApplication.SampleIntegratingApp.dll application assembly. The followingillustration shows this reference for a C# project.

This reference providesaccess to the resources in

the correspondingdictionary.



Namespace

Resources for a dictionary are accessed through the following namespace:

Microsoft.Dexterity.Applications

To make it convenient to access resources, this namespace is included in the C#project template with the using statement. In the Visual Basic project template, it’sincluded using the Imports statement. Referencing the namespace prevents youfrom having to fully-qualify references to dictionary resources.

Dictionary class

The resources in a dictionary are accessed through a single class that is availableafter you add the reference to the dictionary’s application assembly. The class hasthe same name that appears in the application assembly. For instance, the class toaccess resources for the Dynamics dictionary is named Dynamics. Similarly, theclass used to access resources for the Sample Integrating Application is namedSampleIntegratingApp. This is the same name that appears in the applicationassembly, Application.SampleIntegratingApp.dll.

The five primary resource types in a dictionary are accessed through properties ofthe 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 alist of the specific type of resources available in the dictionary. For example, thefollowing 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 theproperties, methods, and events available for that resource. The followingillustration shows some of the properties, methods, and events for the AboutBoxform in the Dynamics dictionary.

Type the dictionary class nameand the resource type

property. IntelliSense displaysa list of resources.


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 E S O U R C E S

Accessing additional resources

Several additional resource types are accessed through the Forms property of adictionary class. These include:

• Windows• Commands• Form-level procedures• Form-level functions• Form-level table buffers

As an example, the following C# statement opens the Customer Maintenancewindow. Notice how the window is accessed through the form object.

Dynamics.Forms.RmCustomerMaintenance.RmCustomerMaintenance.Open();

Windows provide further access to two additional resource types:

• Fields• Scrolling windows

For instance, the following C# statement sets the value of the Comment 1 field in theVendor 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, ResourceReference.

Variables for dictionary resources

Within your code, it may be useful to create variables for specific resources in anapplication dictionary. The definitions for the various dictionary resources arefound in an additional namespace available in the application assembly. Thisnamespace has the same name that appears in the application assembly, but has“Dictionary” appended. For instance, to reference the definitions for resources inthe Dynamics main dictionary, you would use this namespace:

Microsoft.Dexterity.Applications.DynamicsDictionary

To reference resources for the Sample Integrating Application, you would use thisnamespace:

Microsoft.Dexterity.Applications.SampleIntegratingAppDictionary;

After creating the variable, you can assign its value and then use it in your code. Forexample, the following C# code creates a variable for the Vendor Maintenance formin Microsoft Dynamics GP. It assigns the form to the variable, and then uses it toopen the form.

PmVendorMaintenanceForm VendorMaintenanceForm;

VendorMaintenanceForm = Dynamics.Forms.PmVendorMaintenance;

VendorMaintenanceForm.Open();



Using a variable can simplify your code, especially when accessing dictionaryresources that have long names. For example, the following C# code creates avariable for the Customer Maintenance window in Microsoft Dynamics GP. Then itsets the values of two fields in the window. Notice it take less code to set the fieldwhen the variable for the window is used.

// Create the variable and set its value

RmCustomerMaintenanceForm.RmCustomerMaintenanceWindow CustMaintWindow;

CustMaintWindow = Dynamics.Forms.RmCustomerMaintenance.RmCustomerMaintenance;

// Accessing window fields requires less code when using the variable

CustMaintWindow.Comment1.Value = "Comment 1";

Dynamics.Forms.RmCustomerMaintenance.RmCustomerMaintenance.Comment2.Value =

"Comment 2";


Chapter 8: EventsApplications that integrate with Microsoft Dynamics GP often need to be notifiedwhen specific events occur in the system. This portion of the documentationdescribes how to register to be notified when events occur in the system. It alsodescribes how to write event handlers that can respond to the events. Information isdivided 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 ofin the system. Event registrations are added to the Initialize() method, located inthe template code that is automatically added when you created your Visual StudioTools 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 followingevents available:

• OpenBeforeOriginal• OpenAfterOriginal• CloseBeforeOriginal• CloseAfterOriginal

Refer to each resource type described in Part 3, Resource Reference, for the list ofevents that are available for that resource.

To register an event, find the resource for which you want to register the event. Pickthe event you want, and then specify the event handler method. The event handleris 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 byreferencing the resource for which you want to register an event. Add the +=operator, and Visual Studio will display IntelliSense indicating it will complete theevent handler. Simply press the TAB key to add the event handler registration.



After the event handler registration is added, Visual Studio will offer to add theevent handler method for the new event. Press the TAB key again to add the eventhandler method. When you’re finished, the completed event will look similar to thefollowing:

public void Initialize()

{

Dynamics.Forms.RmCustomerMaintenance.OpenAfterOriginal += new

EventHandler(RmCustomerMaintenance_OpenAfterOriginal);

}

void RmCustomerMaintenance_OpenAfterOriginal(object sender, EventArgs e)

{

throw new Exception("The method or operation is not implemented.");

}

Visual BasicRegistering an event in a Visual Basic project requires two steps. First, in theInitialize() method of the project, the AddHandler statement registers the event.The AddHandler statement takes two parameters. The first specifies the resourceand event, while the second specifies the event handler method that will be run. Thefollowing example registers the AfterOpen event for the Customer Maintenanceform in Microsoft Dynamics GP.

Sub Initialize() Implements IDexterityAddIn.Initialize

AddHandler Dynamics.Forms.RmCustomerMaintenance.OpenAfterOriginal, _

AddressOf RMCustMaintAfterOpen

End Sub

In the second step, the event handler method is added. The parameters for thismethod must match those required by the event. The IntelliSense for the eventdisplays the parameters the event handler must have.

The following example shows the event handler method added for the eventcreated in the previous example.

Public Sub RMCustMaintAfterOpen(ByVal sender As Object, ByVal e _

As System.EventArgs)

MsgBox("Not Implemented")

End Sub

The parameters requiredfor the event handler

method are displayed.


C H A P T E R 8 E V E N T S

Responding to eventsThe event handler method contains the code that runs in response to the event. Thiscode can perform whatever action is required for your integrating application. Forexample, the following C# code is the event handler that runs in response to thevalue of the Sales Document Number field being changed in the Sales TransactionEntry 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 argumentsThe event arguments for some events provide additional information about theevent. The event arguments for procedure events and function events allow accessto the parameters for the procedure or function call. For instance, the following C#example is the event handler for InvokeAfterOriginal event for theGetAutoComplete function in Microsoft Dynamics GP. The event argumentscontain the parameters that were passed into the function. The event handlerexamines 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 andmessage displayed in the modal dialog. For example, the following Visual Basiccode is the event handler for the BeforeModalDialog event of the Sales TransactionEntry window. It shows how the event arguments are used to examine the messagetext 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)

' Examine the dialog to determine whether it is the one to respond do

If e.DialogType = DialogType.Ask Then

If e.Message.Contains("want to add a customer") Then

' Click the Customer button in the modal dialog

e.Response = DialogResponse.Button1

End If

End If

End Sub



Cancelling eventsSome events can be cancelled through the event handler. Typically, these are eventsthat occur before the event in the core application, such as the OpenBeforeOriginalevent for a form. The event argument parameter that is passed to the event handlerfor 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 theBeforeOpen event of the Customer Maintenance form. The event handler methodexamines the current user logged into the system. If it’s the “sa” user, a message isdisplayed and the window isn’t opened. Notice how the event arguments are usedto cancel the event.

Public Sub RMCustMaintBeforeOpen(ByVal sender As Object, ByVal e _

As System.ComponentModel.CancelEventArgs)

If Dynamics.Globals.UserId.Value = "sa" Then

'Display the message

MsgBox("Do not access this window as the Administrator")

'Prevent the form from opening

Dynamics.Forms.RmCustomerMaintenance.Close()

'Cancel pending events

e.Cancel = True

End If

End Sub

Unregistering events

At some point after you have registered an event, the event may no longer beneeded. To unregister an event, use the standard syntax for either C# or VisualBasic. 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 exceptionwill be thrown.

C#The following C# example shows how you would unregister an AfterModalDialogevent. The method named IvItemMaintenance_AfterModalDialog had beenregistered as the event handler for the modal dialog event.

ItemMaintenanceForm.IvItemMaintenance.AfterModalDialog -= new

EventHandler<AfterModalDialogEventArgs>(IvItemMaintenance_AfterModalDialog);


C H A P T E R 8 E V E N T S

Visual BasicThe following Visual Basic example shows how you would unregister theInvokeAfterOriginal event for the AddSuccessfulLoginRecord procedure. Themethod named AddSuccessfulLogin had been registered as the event handler forthe procedure event.

RemoveHandler Dynamics.Procedures.AddSuccessfulLoginRecord.InvokeAfterOriginal, _

AddressOf AddSuccessfulLogin


Chapter 9: Working with TablesA Visual Studio Tools integration can interact directly with tables defined inMicrosoft Dynamics GP. Using the table integration capability is much simpler thancreating and managing external connections to the Microsoft Dynamics GPdatabase. Information about working with tables is divided into the followingsections:

• Tables in Microsoft Dynamics GP• Table buffers• Opening and closing tables• Keys• Retrieving a row• Saving a row• Updating a row• Removing a row• Table operation errors• Ranges• Row locking• Multiuser processing

Tables in Microsoft Dynamics GP

To learn about tables in Microsoft Dynamics GP, you will need to access informationfrom the following sources.

Resource Descriptions toolThe Resource Descriptions tool available in Microsoft Dynamics GP providesessential details about each table in the application. Information such as the fields inthe table and the keys defined for the table can be found here.

Important details, such as thekeys defined for the table,can be found in the Table

Descriptions window.



Microsoft Dynamics GP SDKThe Microsoft Dynamics GP SDK contains detailed diagrams and descriptions ofthe tables in Microsoft Dynamics GP. You can use these diagrams to learn about thetable in a specific module, and how the tables work together. Information abouthow transactions flow through the various tables is also available in the MicrosoftDynamics GP SDK.

IntelliSenseThe IntelliSense available in Visual Studio will be helpful by listing what tables areavailable, 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 thetable buffer comes from either the table or a script that has run. Your code willinteract with the table buffer when you perform operations on the table. There aretwo types of table buffers: global and form-level.

A global table buffer is created when a table is accessed directly through the global listof tables. Global table buffers are accessed through the dictionary class. This classhas a Tables property that provides access to the collection of tables defined in thedictionary. A global table buffer is not associated with any specific form. This makesglobal table buffers useful in situations where a Visual Studio Tools integrationmust read from or write to a Dynamics GP table, but isn’t interacting with the userinterface.

By default, a global table buffer for a table is shared with all of the other VisualStudio Tools add-ins that are accessing that same table. If you want your integrationto create a global table buffer that is not shared, use the Clone() method whencreating the instance of the global table buffer.

A form-level table buffer is created when a table is attached to a form in MicrosoftDynamics GP. There is one table buffer for each table that is attached to the form.Each form-level table buffer is shared by the code that is part of the form, as well asany code outside of the form that accesses the table through that form. The Tablesproperty for the form allows access to the table buffers for the tables that areattached to the form. Because they are shared, form-level table buffers aren’ttypically used by Visual Studio Tools integrations to directly read from or write totables. Instead, the form-level table buffers are examined to find what data theDynamics GP window has read or is writing to the specific table.

IntelliSense lists whichtables are available. A

description of each tableis also provided.

Global Visual Studio ToolsApplication Code

Dynamics GPTable Table Buffer


C H A P T E R 9 W O R K I N G W I T H T A B L E S

Opening and closing tablesThere is no explicit “open” operation for a table in Visual Studio Tools. The firsttime a table buffer is accessed, the table is automatically opened. The table bufferremains open until it is closed.

When your integrating application’s code has finished working with a global tablebuffer, it must be closed using the Close() method for the table. Failing to close aglobal table buffer will cause a “Background process is running: Exit Aborted” errorwhen 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 tablebuffer. The first row of the table (the RM Customer Master table) is retrieved, andthe customer number is displayed. Notice how the table buffer is closed at the endof the example.

RmCustomerMstrTable CustomerMasterTable;

CustomerMasterTable = Dynamics.Tables.RmCustomerMstr;

// Read the first row of the table

CustomerMasterTable.GetFirst();

// Display the name for the row retrieved

MessageBox.Show(CustomerMasterTable.CustomerName.Value);

// Close the table buffer

CustomerMasterTable.Close();

Form-levelVisual Studio ToolsApplication Code

Dynamics GP Tables

Table Buffers

Dynamics GPWindow

Form

The user will see this errorwhen global table buffers are

left open in a Visual StudioTools integration.



Keys

A key is a field or combination of fields in a table that is used to sort and locatespecific rows in the table. Typically, the value of the key field or fields is unique foreach row in a table so a specific row can be located. Keys that don’t uniquelyidentify 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 youspecify the key you want to use for a table, you will supply the correspondinginteger. The Table Descriptions window in Microsoft Dynamics GP lists the keys foreach 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 whenyou want to perform operations on a range of rows in the table. You will learn moreabout this in Ranges on page 53.

Retrieving a row

Retrieving a row from a table is a multi-step process. First, you must decide whichkey you want to use to retrieve the row. Use the Table Descriptions window inMicrosoft Dynamics GP to view the keys and each key’s components. Specify thekey to use, and then set the values of the key fields. Finally, use the Get() orChange() method for the table to retrieve the record. Which you use depends onwhether you want to lock the record. You will learn more about locking in Rowlocking on page 57.

The following C# example retrieves the row for the customer American ElectricalContractor from the RM_Customer_MSTR table. The second key of theRM_Customer_MSTR table is used. This key contains one component, theCustomer Name. The contact person for the retrieved customer is displayed in adialog.

// Variable for any table operation error

TableError err;

// Create a reference to the table



// Set the key to use for the table

// Key 2 - Contains the Customer Name

CustomerMasterTable.Key = 2;

// Set the value for the key columns

CustomerMasterTable.CustomerName.Value = "American Electrical Contractor";

The keys for the table arelisted in numeric order.

The fields in each key arelisted here.



// Retrieve the row

err = CustomerMasterTable.Get();

if (err == TableError.NoError)

{

MessageBox.Show(CustomerMasterTable.ContactPerson.Value);

}

else

{

// Display the error that occurred

MessageBox.Show(err.ToString());

}

// Close the table


Saving a row

To save a new row in a table, set the fields in the table to the values you want tosave. 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 thevalues for the fields in the table, then saves the new row.


TableError err;


GlAccountCategoryMstrTable CategoryMasterTable;

CategoryMasterTable = Dynamics.Tables.GlAccountCategoryMstr;

// Set the fields in the table

CategoryMasterTable.AccountCategoryNumber.Value = (short)49;

CategoryMasterTable.AccountCategoryDescription.Value = "Profit Sharing";

// Save the new row

err = CategoryMasterTable.Save();

if(err == TableError.Duplicate)

{

MessageBox.Show("Account category already exists");

}

// Close the table

CategoryMasterTable.Close();



Updating a row

To update a row in a table, first read the row with the Change() method. Thisretrieves the row and locks it, allowing you to make changes. Set the values of thefields you want to change for the row. Finally, use the Save() method to save thechanged row back to the table.

The following C# example reads the row for Adam Park Resort. The Contact Personfor this row is changed the “Steve K.” Then the row is saved back to theRM_Customer_MSTR table.


TableError err;





// Key 1 - Contains the Customer Number


// Set the key field in the table

CustomerMasterTable.CustomerNumber.Value = "ADAMPARK0001";

// Attempt to read the row. The Change() method will lock the row.

err = CustomerMasterTable.Change();


{

// The row was read successfully, so update the value

CustomerMasterTable.ContactPerson.Value = "Steve K.";

// Save the updated row

err = CustomerMasterTable.Save();

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());

}

// Close the table




Removing a row

To remove a row from a table, first read the row with the Change() method. Thisretrieves the row and locks it. Then use the Remove() statement to remove the rowfrom 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 isremoved from the table.


TableError err;


IvItemMstrTable ItemMasterTable;

ItemMasterTable = Dynamics.Tables.IvItemMstr;


// Key 1 - Contains the Item Number

ItemMasterTable.Key = 1;

// Set the key field in the table

ItemMasterTable.ItemNumber.Value = "WIRE100";

// Attempt to read the row. The Change() method will lock the row.

err = ItemMasterTable.Change();


{

// Attempt to remove the row

err = ItemMasterTable.Remove();


{

MessageBox.Show("An error occured removing the row: " +

err.ToString());

}

}

// Close the table

ItemMasterTable.Close();



Table operation errors

An error code is returned from each of the table operations that can be performed.The possible error codes are contained in the TableError enumeration. Many of theerrors included in the enumeration will not occur in the released versions ofMicrosoft Dynamics GP. The following table describes the error values that yourVisual Studio Tools integration is likely to encounter:

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. Ifthe operation was successful, the next processing step can continue.

• Check for a specific error, such as NotFound. The code must respondappropriately, such as displaying a message for the user.

If an unexpected error occurs after performing a table operation, it’s always a goodidea to display the details of the error to the user. Include information such as thetable, 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 surethat your code closes any tables it has accessed. Otherwise, the user won’t be able to exitMicrosoft Dynamics GP.

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.



Ranges

When working with tables, it is often efficient to limit the amount of informationbeing accessed. You can do this by setting up a range for the table. A range is basedon a key for the table, and allows you to access a specified portion of the rows in thetable. The selected range will be treated as an entire table. For instance, calling theGetFirst() method returns the first row in the range. Calling the GetLast() methodreturns 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 isassociated with. To clear the range specified for a table, use the RangeClear()method.

Example 1 - Range with simple keyIn the following C# example, a range is used to limit the rows accessed to only thosecustomers whose names begin with “A”. Notice that the second key for the table,composed of the Customer Name field, is used for the RangeStart() andRangeEnd() methods. The first and last rows in the range are displayed.


TableError err;





// Key 2 - Contains the Customer Name


// Specify the start of the range

CustomerMasterTable.Clear();

CustomerMasterTable.CustomerName.Value = "A";

CustomerMasterTable.RangeStart();

// Specify the end of the range

CustomerMasterTable.Clear();

CustomerMasterTable.CustomerName.Value = "B";

CustomerMasterTable.RangeEnd();

// Display the first item in the range

err = CustomerMasterTable.GetFirst();


{

MessageBox.Show("First customer: " +

CustomerMasterTable.CustomerName.Value);

}

else

{

MessageBox.Show("An error occured retrieving the row: " +

err.ToString());

}



// Display the last item in the range

err = CustomerMasterTable.GetLast();


{

MessageBox.Show("Last customer: " +

CustomerMasterTable.CustomerName.Value);

}

else

{


err.ToString());

}

// Close the table


Example 2 - Range with multi-segment keyIf a key is composed of several segments, you can create ranges based on serveralkey segments. It’s important that all segments of the key be set when specifying thestart and end of the range. The Clear() and Fill() methods are often used whencreating a range based on a multi-segment key. They are used to set all of the fieldsin the table buffer to the empty value or the filled value. This ensures that all of thekey segments have been specified before the RangeStart() or RangeEnd() methodsare called.

For example, the following C# code creates a range for the IV_Item_MSTR table thatincludes only items in the COMPONENTS class. The range is created using key 3for the Item Master table. This key has two segments: Item Class Code and ItemNumber.

To set the beginning of the range, the Clear() method is used to set the fields in theIV_Item_MSTR table buffer to the minimum value. The Item Class Code field in thetable buffer is set to “COMPONENTS”. The RangeStart() method specified this isthe beginning of the range.

To set the end of the range, the Fill() method is used to set the fields in theIV_Item_MSTR table buffer to the maximum value. The Item Class Code field in thetable buffer is set to “COMPONENTS”. The RangeEnd() method specifies this is theend of the range.

The key values for the range are shown in the following illustration. The range willinclude rows where the Item Class Code value is “COMPONENT” and the ItemNumber can be any value.

Range Start

Range End

Item Class Code Item Number

“COMPONENT” (Cleared)

“COMPONENT” (Filled)




TableError err;


IvItemMstrTable ItemMasterTable;

ItemMasterTable = Dynamics.Tables.IvItemMstr;


// Key 3 - Contains the Item Class Code and the Item Number

ItemMasterTable.Key = 3;


ItemMasterTable.Clear();

ItemMasterTable.ItemClassCode.Value = "COMPONENTS";

ItemMasterTable.RangeStart();


ItemMasterTable.Fill();

ItemMasterTable.ItemClassCode.Value = "COMPONENTS";

ItemMasterTable.RangeEnd();

// Read through the items in the range

StringBuilder itemList = new StringBuilder();

err = ItemMasterTable.GetFirst();

while(err == TableError.NoError)

{

// Add the item to the list

itemList.AppendLine(ItemMasterTable.ItemNumber + " " +

ItemMasterTable.ItemDescription);

// Get the next item in the range

err = ItemMasterTable.GetNext();

}

// Display the list of items

MessageBox.Show(itemList.ToString());

// Close the table

ItemMasterTable.Close();

Example 3 - Removing rows in a rangeOnce a range is created for a table, you can use the RangeRemove() method toremove all of the rows in that range from the table. In many cases, this will be fasterthan removing individual rows using the Remove() method.

The following C# example deletes all customer information for St. Patrick’sHospital. A single row must be deleted from the RM_Customer_MSTR and theRM_Customer_MSTR_SUM tables. Several rows must be deleted from theRM_Customer_MSTR_ADDR table. A range is used to remove the rows from thistable.


TableError err;



// Create references to the tables



RmCustomerMstrSumTable CustomerMasterSummaryTable;

CustomerMasterSummaryTable = Dynamics.Tables.RmCustomerMstrSum;

RmCustomerMstrAddrTable CustomerMasterAddressTable;

CustomerMasterAddressTable = Dynamics.Tables.RmCustomerMstrAddr;

// Delete the row from the Customer Master Summary table

CustomerMasterSummaryTable.Key = 1;

CustomerMasterSummaryTable.CustomerNumber.Value = "STPATRIC0001";

err = CustomerMasterSummaryTable.Change();


{

err = CustomerMasterSummaryTable.Remove();

}

// Close the table

CustomerMasterSummaryTable.Close();

// Delete the row from the Customer Master table


CustomerMasterTable.CustomerNumber.Value = "STPATRIC0001";

err = CustomerMasterTable.Change();


{

err = CustomerMasterTable.Remove();

}

// Close the table


// Delete the rows from the Customer Master Address table

// Key 1 has two segments (Customer Number and Address Code)

CustomerMasterAddressTable.Key = 1;


CustomerMasterAddressTable.Clear();

CustomerMasterAddressTable.CustomerNumber.Value = "STPATRIC0001";

CustomerMasterAddressTable.RangeStart();


CustomerMasterAddressTable.Fill();

CustomerMasterAddressTable.CustomerNumber.Value = "STPATRIC0001";

CustomerMasterAddressTable.RangeEnd();

// Remove the rows from the range

CustomerMasterAddressTable.RangeRemove();

// Close the table

CustomerMasterAddressTable.Close();



Row locking

A row must be locked to delete it or save any changes made to it. A lock is appliedwhen a row is read from a table. Two types of locked can be used: passive andactive.

Passive lockingA passive lock allows other users to access the row. They can delete the row or makechanges to it. Passive locking ensures that other users accessing the row can bemade aware that the row has been deleted or that the contents of the row havechanged. 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 lockingAn active lock allows other users to read the row, but not make any changes or deletethe row. Active locking ensures that the user who has the active lock is the only userwho can make changes or delete the row. If other users try to delete or change therow, they will receive a sharing error. An ative lock is applied each time a row isread using the Change() method and the activeLock parameter for the method is setto true.

Not all tables in Microsoft Dynamics GP allow active locking. If you try to actively lock arow on a table that doesn’t support it, a NotSupported error will be returned.

Releasing locksAny of the following actions release a row lock:

• Using the Release() method.

• Using the Save() method or the Remove() method, regardless of whether themethod 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 thesame time. This is accomplished through Optimistic Concurrency Control (OCC), aform of record locking that allows multiple users to work in the same tables andaccess the same rows with minimal restrictions, while helping to ensure dataintegrity.

To allow multiple users to successfully use Microsoft Dynamics GP while VisualStudio Tools integrations are accessing data, you must choose the type of lockingused. You must also handle any error conditions that occur as a result of multipleusers working with the same row in a table.



The following table lists the various locking scenarios that can occur. The eventslisted happen in order from left to right. For example, in the first row User Apassively locks a row, then User B passively locks the same row. User A deletes therow, then User B changes the contents of the row and saves the row. The changesUser B made will be saved.

Scenarios 1 through 3 don’t produce any errors. To be multiuser compatible, yourapplication should be able to handle scenarios 4 to 10, alerting users that an erroroccurred, and allowing them to respond appropriately.

Use the error value returned from the various table operations like Save() orRemove() to trap errors so your code can deal with the errors that occur. Thefollowing examples show how to trap for multiuser errors when reading, savingand removing records.

You should not check for multiuser error conditions on tables containing text fields. Textfields are those that store text up to 32,000 characters long. Multiuser error codes are notproperly returned for tables containing text fields.

User A User B User A User B Result

1 Passively locks a row.

Passively locks the same row.

Deletes the row. Changes the contents of the row and saves the changes.

The changes User B made will be saved.



Changes the contents of the row and saves the row.

Deletes the row. The row will be deleted.



Changes a field and saves the row.

Changes a different field and saves the row.

Both changes will be saved.



Changes a field and saves the row.

Changes the same field and attempts to save the row.

User B will get an error indicating the row changed. User B’s changes won’t be saved.



Deletes the row. Attempts to delete the row.

User B will get an error indicating the row is missing.

6 Actively locks a row.


Keeps the active lock.

Attempts to delete the row or change a field and save the row.

User B will get a row locked error. The row won’t be deleted or the changes won’t be saved.



Deletes the row. The active lock is released.

Changes the row and saves it or deletes the row.

If user B changed the row and saved, the changes will be saved.If User B attempts to delete the row, User B will get an error indicating the row is missing.



Makes changes and saves the row. The active lock is released.

Changes the row and saves it or deletes the row.

If User B changed the same field as User A, User B will get an error indicating the row changed. User B’s changes won’t be saved. If user B changed different fields, the changes will be saved. If User B deleted the row, the row will be deleted.


Actively locks the same row.

Attempts to delete the row or change a field and save the row.

Keeps the active lock.

User A will get a row locked error, even though User B’s active lock came later than User A’s lock.


Attempts to actively lock the same row.

User B will get a row locked error.



Example 1The following C# example reads and actively locks the first row in theRM_Sales_WORK table. It uses the value returned from the ChangeFirst() methodto handle the Sharing error resulting from the row being actively locked by anotheruser.


TableError err;

// Create references to the tables

RmSalesWorkTable SalesWorkTable;

SalesWorkTable = Dynamics.Tables.RmSalesWork;

// Release any existing lock

SalesWorkTable.Release();

// Retrieve the first row and actively lock it

err = SalesWorkTable.ChangeFirst(true);

if (err == TableError.Sharing)

{

// The row is actively locked by another user

MessageBox.Show("This row is currently locked by another user.");

}

// Close the table

SalesWorkTable.Close();

Example 2The 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 valuefrom the Save() method is used to handle an error resulting from the row beingchanged or actively locked by another user.


TableError err;

// Create reference to the table



// Release any existing lock

CustomerMasterTable.Release();

// Read the first row in the table

err = CustomerMasterTable.ChangeFirst();

// Change the Salesperson ID

CustomerMasterTable.SalespersonId.Value = "STEVE K.";

// Save the changed row


// Handle any errors

if (err == TableError.Changed)

{

// The row was changed by another user.

MessageBox.Show("This row has been changed by another user. Their changes

will be overridden.");



// Re-read the current row to lock it

CustomerMasterTable.Change();

// Re-write the value

CustomerMasterTable.SalespersonId.Value = "STEVE K.";

// Attempt the save again



{

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());

}

// Close the table


Example 3The following script reads the last row in the GL_Account_Category_MSTR tableand attempts to delete it. The error value returned from the Remove() method isused to handle an error resulting from the row being actively locked or alreadydeleted by another user.


TableError err;

// Create reference to the table

GlAccountCategoryMstrTable AccountCategoryMasterTable;

AccountCategoryMasterTable = Dynamics.Tables.GlAccountCategoryMstr;

// Release any lock on the row

AccountCategoryMasterTable.Release();

// Retrieve the last row

err = AccountCategoryMasterTable.ChangeLast();


{

// Row was read and can be removed

err = AccountCategoryMasterTable.Remove();

if (err == TableError.Sharing)

{



// The row is actively locked

MessageBox.Show("This row is actively locked by another user.

It cannot be removed.");

}

else if (err == TableError.NotFound)

{

// The row was removed by another user

MessageBox.Show("This row was removed by another user.");

}

else if (err != TableError.NoError)

{


MessageBox.Show("An error occured removing the row: " +

err.ToString());

}

}

else

{



err.ToString());

}

// Close the table

AccountCategoryMasterTable.Close();


Chapter 10: Building and DeployingThis portion of the documentation describes how to build and deploy an integrationcreated with Visual Studio Tools for Microsoft Dynamics GP. Information is dividedinto the following sections:

• Setting assembly information• Building an integration• Deploying an integration

Setting assembly information

It’s important to set the assembly information so the assembly you build for yourVisual Studio Tools for Microsoft Dynamics GP integration is properly identifiedand versioned. Be sure you set the following items:

• Title• Description• Company• Major, minor, and build numbers

C# applicationFor integrations written in C#, the assembly information is set in theAssemblyInfo.cs source file for the project. The following portion of this file showsthe various name values that should be set.

// General Information about an assembly is controlled through the following

// set of attributes. Change these attribute values to modify the information

// associated with an assembly.

[assembly: AssemblyTitle("Estimate Freight")]

[assembly: AssemblyDescription("Estimate Freight Sample Integration")]

[assembly: AssemblyConfiguration("")]

[assembly: AssemblyCompany("Microsoft")]

[assembly: AssemblyProduct("EstimateFreight")]

[assembly: AssemblyCopyright("Copyright © Microsoft 2009")]

[assembly: AssemblyTrademark("")]

[assembly: AssemblyCulture("")]

The following portion of this file shows the version, build, and revision numbersthat should be set.

// Version information for an assembly consists of the following four values:

//

// Major Version

// Minor Version

// Build Number

// Revision

//

// You can specify all values or default the Revision and Build Numbers

// by using the '*' as shown below:

[assembly: AssemblyVersion("1.0.0.0")]

[assembly: AssemblyFileVersion("1.0.0.0")]



Visual Basic applicationFor integrations written in Visual Basic, the assembly information is set in theAssembly Information window. Access this window. To view this windows, chooseto display the properties for the Visual Basic project. Click the Application tab, andthen click the Assembly Information button.

Building an integration

To build the integration, complete the following procedure:

1. Set the solution configuration.If you’re building a test version of the integration, set the solution configurationto “Debug”. If you are building a final version of the integration, set thesolution configuration to “Release”.

2. Build the solution.Choose Build Solution from the Build menu.

3. Verify there were no build warnings.If there were build warnings, fix them and build again.

4. Copy the assembly to the AddIns folder.Copy the assembly for your integration from the “Debug” or “Release” folderfor your project to the AddIns folder in the Microsoft Dynamics GP installation.

5. Copy any application assemblies needed.If you created any application assemblies for your integration, be sure to copythem to the Microsoft Dynamics GP folder.

6. Start Microsoft Dynamics GP.Your integrating application should be loaded when Microsoft Dynamics GPstarts. Verify that your integration is working properly.

Set the solutionconfiguration to either

Debug or Release.


C H A P T E R 1 0 B U I L D I N G A N D D E P L O Y I N G

Deploying an integration

When deploying your integration built with Visual Studio Tools for MicrosoftDynamics GP, be sure that you include the following:

• The assembly for your integration.

• Any additional application assemblies you generated that are specific to yourintegration.

• Instructions that explain how to install your integration.


Chapter 11: DebuggingWhen developing an integrating application, you may find it necessary to examinethe code with the Visual Studio debugger. Information about debugging yourMicrosoft 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 followingprocedure.

1. Build and deploy the integration.Be sure that you have built the Debug version of your project.

2. Start Microsoft Dynamics GP.Microsoft Dynamics GP must be running so that your integrating application isloaded.

3. Set breakpoints in your code.Within Visual Studio, set breakpoints in your code to indicate where you wantprocessing to wait.

4. Choose to attach to a process.Since your integrating application is running within the Dynamics.exe process,you must attach the Visual Studio debugger to this process. From within VisualStudio, choose Attach to Process from the Debug menu.

5. Select the Dynamics.exe process.In the Attach to Process window, locate the Dynamics.exe process and select itin the list.

Click Attach to attach to the process. Control will be returned to Visual Studio.

Locate the Dynamics.exeprocess and select it in

the list.



Examining the application

Once your integrating application has stopped at a breakpoint, you can use VisualStudio’s tools to examine your code. Do the following:

1. Switch to Microsoft Dynamics GP.

2. Perform the actions to exercise your code.Within Microsoft Dynamics GP, perform the actions that will execute the codeyou want to examine.

3. Examine your code.When Visual Studio encounters a breakpoint, it will become the activeapplication. Use the tools within Visual Studio to examine your code.

4. Finish debugging.When you have finished debugging your integrating application, choose StopDebugging 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 MicrosoftDynamics GP application. To disable events, use the Customization Status windowin Microsoft Dynamics GP. To open this window, point to Customize in the Toolsmenu, and then choose Customization Status. Select the Microsoft Dynamics GPproduct, and then click Disable. Be sure to enable the events after you havecompleted your tests.

Examine your code whilestopped at the

breakpoints you set.


Chapter 12: Modified and Alternate FormsTo access modified or alternate forms from a Visual Studio Tools for MicrosoftDynamics GP, a special process is used. This portion of the documentation describesthe 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. Toaccess these modifications from your Visual Studio Tools for Microsoft DynamicsGP project, complete the following procedure:

1. Create an application assembly for the forms dictionary.If the forms dictionary for the application that has been modified doesn’t havean application assembly, create one using the process described in Chapter 6,“Dictionary Assembly Generator.” For example, the following commandcreates the application assembly for the forms dictionary of the core DynamicsGP product:

dag.exe 0 "C:\Program Files\Microsoft Dynamics\GP\Dynamics.set" /F /N:Dynamics

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”.

2. Add the reference to the application assembly for your project.In Visual Studio, add the reference to the application assembly. The followingillustration show the reference added for the application assembly that providesaccess to modified forms for the Dynamics GP core dictionary.

3. Access the modified forms.Modified forms are accessed through an additional dictionary class that has thesame name as the application’s dictionary class, but with the additional phrase“Modified”. For instance, the dictionary class used to access modified forms forthe Dynamics core application is:

DynamicsModified

This reference to theapplication assembly provides

access to the modified formsfor the application.



The following C# code sets the value of a new field on the Credit Limit window ofthe Customer Maintenance form. The new field is a local field, added with theModifier, and named “Test”.

DynamicsModified.Forms.RmCustomerMaintenance.RmCreditLimit.LocalTest.Value =

"Modified Field";

When accessing resources that are defined in the main dictionary for an application, accessthem through the main dictionary class, rather than through the “Modified” class for theapplication.

Alternate forms

Alternate forms are forms from the core Dynamics dictionary that have beenchanged by a third-party developer, and are stored in a third-party dictionary. Thenew and changed resources for the alternate form are accessed through the third-party application’s application assembly. To access alternate forms from you VisualStudio Tools for Microsoft Dynamics GP project, complete the following procedure:

1. Create an application assembly for the third-party dictionary.If the third-party dictionary doesn’t already have an application assembly,create one using the process described in Chapter 6, “Dictionary AssemblyGenerator.” For example, the following command creates the applicationassembly for the Sample Integrating Application, to which an alternate form(PM Vendor Maintenance) was added for this example:


2. Add the reference to the application assembly for your project.In Visual Studio, add the reference to the application assembly. The followingillustration show the reference added for the application assembly that providesaccess to the alternate forms in the Sample Integrating App application.

3. Access the alternate forms.Alternate forms are accessed through the dictionary class for the assembly thatcontains them. For instance, the alternate forms in the Sample Integrating Appapplication would be accessed through its dictionary class:

SampleIntegratingApp

This reference to theapplication assembly provides

access to the alternate formsfor the application.


C H A P T E R 1 2 M O D I F I E D A N D A L T E R N A T E F O R M S

The following C# code sets the value of a new field on the Vendor Maintenancewindow of the alternate version of the Vendor Maintenance form, which is part ofthe 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 todevelop an integration for general distribution, we recommend that you limit thereferences 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 integrationwhich accesses modified or alternate forms, be sure that your code properly handlescases when these resources are not available.

For instance, when you set or retrieve the value of a field, use a try...catch block toenclose the statements. This allows your code to catch any exceptions that arethrown because the field cannot be accessed. The following C# example shows howa field in window for an alternate version of the Vendor Maintenance form can beset within a try...catch block.

// Set the Status local field in the alternate form

try

{

SampleIntegratingApp.Forms.PmVendorMaintenance.PmVendorMaintenance.

LocalStatus.Value = "Preferred";

}

catch (Exception ex)

{

// The field was not accessible. In this example, display a message.

MessageBox.Show(ex.Message);

}


Chapter 13: Implementing Macro SupportYou can add macro support for the forms you create with Visual Studio Tools.Information about doing this is contained in the following sections:

• Overview of macro support• Recording macros• Playing macros• Handling asynchronous processes during playback

Overview of macro support

In Visual Studio Tools, forms you create that inherit from the DexUIForm can beintegrated into the macro system in Microsoft Dynamics GP. Support for the macrosystem is not automatic. To support the macro system you will do the following:

• You must add calls to the RecordMacroItem() in the appropriate places in yourVisual 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 processesthat the macro system will need to wait for, you will need to override theIsAsynchEventPending() method.

Recording macros

In your Visual Studio Tools form, identify the places that the user can performactions. Actions include things like clicking buttons, adding text to text fields, ormoving the focus. In the events that run due to these user actions, you will add codethat calls the RecordMacroItem() method to record a text string and optionalcomment that identify and describe the action. For example, the following C# coderecords a macro command for the Energy Star check box:

RecordMacroItem("ClickHit EnergyStar", "Toggle the Energy Star check box");

The text strings passed to the RecordMacroItem() method are written to the macroas ShellCommand macro statements.

ShellCommand 'ClickHit EnergyStar' # Toggle the Energy Star check box

The the RecordMacroItem() method records values only when a macro is being recorded.

Macro syntaxThe text string and optional comment recorded in the macro are the onlyinformation available to your Visual Studio Tools add-in when the macro is playedback. These text strings must contain enough information for your code todetermine the action that must be performed.

There is no predefined syntax for the text strings recorded. You must define the textstrings so that they can be parsed by your add-in, and then the add-in can performthe actions indicated. The macro support in the Environmental Details Visual StudioTools sample is a good starting point. The syntax of its macro statements is similarto the standard Microsoft Dynamics GP macro language.



PlacementWhere you place the RecordMacroItem() calls in your code can affect how data iswritten to the macro. Some experimenting may be required to find which event for acontrol is most appropriate for recording a macro action. For example, whenrecording the text entered into a text box control, the Validating event is the mostappropriate place for the RecordMacroItem() call. The following C# example showsthe Validating event for the YearlyEnergyCost text box in the Environmental Detailssample.

private void textBoxYearlyEnergyCost_Validating(object sender,

CancelEventArgs e)

{

// Set the change flag for the Item Maintenance window

GPAddIn.ItemMaintenanceWindow.IsChanged = true;

// If a macro is being recorded, record the value.

RecordMacroItem("TypeTo YearlyEnergyCost \"" +

textBoxYearlyEnergyCost.Text + "\"", String.Empty);

}

The following table lists the event where the macro recording code should be placedfor common controls.

Playing macros

When a ShellCommand macro statement is played back, and your Visual StudioTools form is active, the PlayMacroItem() method will be called. You must overridethis method in your Visual Studio Tools add-in code, and process the macrostatements for your form. The following C# example shows how you override thebase method.

public override void PlayMacroItem(MacroPlaybackEventArgs e)

{

}

Event argumentsThe following event arguments are passed into the PlayMacroItem() method:

Handled This is a boolean parameter that indicates whether the action for macrostatement has been performed. You should check the value of this parameter at thebeginning of your PlayMacroItem() method. If its value is true, the macro statementhas already been handled, so your code should take no action. If you determine thatyour code should perform the action for the macro statement, set the Handledparameter to true when the action is complete. This tells other code that the macrostatement has already been processed.

MacroText This string parameter contains the macro string that was written bythe RecordMacroItem() method when the macro was recorded. You will need parsethis string to determine whether your add-in must perform the macro action.

Control Event

Text box Validating

Push Button Click

Check box Validating


C H A P T E R 1 3 I M P L E M E N T I N G M A C R O S U P P O R T

MacroComment This string parameter contains the comment that was writtenby the RecordMacroItem() method when the macro was recorded.

Processing macro statementsYour code will retrieve the MacroText parameter from the event arguments, andthen parse the text to determine whether this macro statement should be performedby your add-in. You can use any approach you like when parsing the macrostatement. The Environmental Details sample uses regular expressions to parse themacro statement. The following C# example shows the complete PlayMacroItem()method for the sample. Notice that if the code performs the macro action, it sets theHandled parameter to true. If it doesn’t perform the action, it allows the base classto do so.

public override void PlayMacroItem(MacroPlaybackEventArgs e)

{

Match m;

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;

}

}

// Process Notes text box

m = Regex.Match(e.MacroText, "TypeTo EnvNotes \"(.+)\"");

if (m.Success)

{


{

textBoxNotes.Focus();

textBoxNotes.Text = m.Groups[1].Value;

e.Handled = true;

}

}

// Process the push buttons and check boxes

m = Regex.Match(e.MacroText, "ClickHit (\\w+)");

if (m.Success)

{


{

// Energy Star check box

if (m.Groups[1].Value == "EnergyStar")

{

checkBoxEnergyStar.Focus();

checkBoxEnergyStar.Checked = !checkBoxEnergyStar.Checked;

e.Handled = true;

}



// Recyclable check box

if (m.Groups[1].Value == "Recyclable")

{

checkBoxRecyclable.Focus();

checkBoxRecyclable.Checked = !checkBoxRecyclable.Checked;

e.Handled = true;

}

// 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);

}

Handling asynchronous processes during playback

If your Visual Studio Tools form makes asynchronous calls to other processes thatthe macro system will need to wait for, you may need to override theIsAsynchEventPending() method of the DexUIForm base class. This method iscalled periodically when a macro is being played. If the method returns true, themacro system will wait for the asynchronous event to finish before additional macrostatements are processed.

Override the IsAsynchEventPending() method only if your Visual Studio Tools add-in hasasynchronous 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 runningan asynchronous process. In the IsAsynchEventPending() method, you will returnthe value of this flag. When the asynchronous process starts, you will set the flag totrue. This causes the macro system to wait for the asynchronous event. When theasynchronous process finishes, you will set the flag to false. This will allow themacro system to resume processing.

public override bool IsAsyncEventPending

{

get

{

// Return the value of the flag that indicates whether an

// asynchronous event is being processed.

return InAsyncEventFlag;

}

}


Chapter 14: Using LookupsLookups are special-purpose windows used to retrieve existing ID values forobjects in Microsoft Dynamics GP, such as customers, vendors, and salesdocuments. You may need to retrieve ID values for your Visual Studio Toolsintegration. In many cases, you can use the lookups defined in Microsoft DynamicsGP to retrieve ID values for fields on your Visual Studio Tools form. Informationabout using lookups is divided into the following sections:

• How lookups work• Available lookups• Lookup example

How lookups work

Lookup windows in Microsoft Dynamics GP are separate forms. The core Dynamicsdictionary contains lookups with basic lookup functionality. The lookup windowsthat the user sees in Microsoft Dynamics GP are actually alternate versions of theforms, and are defined in the SmartList dictionary. This means that your VisualStudio Tools code will reference lookups from the SmartList dictionary.

The following steps describe the basic operation of a lookup for a Visual StudioTools 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 musttrack that it has opened the lookup, so it will know to retrieve the value thatwas selected by the user.

Typically, each lookup used by a Visual Studio Tools integration is trackedusing a static variable defined in the GPAddIn class. The variable must be setwhen the lookup is opened, and cleared when the lookup returns a value.

2. Add code to open the lookup form.Typically, the user clicks a lookup button that opens the lookup form. In yourVisual Studio Tools form, you will add code to the lookup button that will openthe lookup form.

3. Register the ClickBeforeOriginal event for the Select button.A value is returned from the lookup when the user clicks the Select button inthe lookup form. You will register the ClickBeforeOriginal event on the Selectbutton to be notified when the button is clicked.

4. Return the ID of the selected item.When the user clicks the Select button in the lookup, the ID of the selected itemis returned by the event handler for the ClickBeforeOriginal event. This eventhandler also clears the static variable that is tracking that the lookup wasopened by the Visual Studio Tools integration.



Available lookups

Several different patterns have been used to code the lookup forms in MicrosoftDynamics GP. Each pattern requires a specific technique to use the lookup. To learnwhat lookups are available and how to call them, refer to the document titled“Calling Lookup Forms from Dexterity” in the Microsoft Dynamics GP SDK. Thelink for this document is found in the Foundation group of the Procedures andfunctions section of the Microsoft Dynamics GP SDK help file.

The Lookups sample, described in Chapter 29, “Lookups,” demonstrates how to use severalcommon lookup forms in a Visual Studio Tools integration.

In some cases, Visual Studio Tools cannot access all of the resources required to usethe lookup form. For example, some lookup forms are opened by calling proceduresthat have reference parameters. Because Visual Studio Tools cannot call procedureswith reference parameters, these lookup forms cannot be used with Visual StudioTools integrations.

Lookup example

The following example shows how to use the Customers and Prospects lookupform in Microsoft Dynamics GP to retrieve customer numbers for a Visual StudioTools integration.

1. Add a reference to the SmartList application assembly.The Customers and Prospects lookup is one of the enhanced lookups forMicrosoft Dynamics GP that are contained in the SmartList dictionary.

2. Add a Lookup button to the Visual Studio Tools form.Refer to Adding controls on page 25 for details about how to add a control to aVisual Studio Tools form.

3. Add the flag to track that a lookup was opened.In the GPAddIn class, add a static variable to track that a lookup was opened.The following C# example shows code that does this.

// Flag to track that a lookup was opened

public static Boolean ReturnToLookup = false;

4. Add code to open the lookup form.In the Click event for the Lookup button, add code that opens the lookup. Theactions that this code must perform will depend on the lookup that you areusing. Refer to the document “Calling Lookup Forms from Dexterity” in theMicrosoft Dynamics GP SDK for information about the available lookups. Forthe Customers and Prospects lookup, the following actions must be performed:

• The flag is set that indicates the lookup was opened by the Visual StudioTools integration.

• The CustomerLookup form must be opened.

• The Initialize procedure on the CustomerLookup form must be called. Thisconfigures how data is displayed in the lookup.


C H A P T E R 1 4 U S I N G L O O K U P S

The following C# example shows how the Customers lookup is opened.

private void CustomerLookup_Click(object sender, EventArgs e)

{

// Create a reference to the CustomerLookup form

Microsoft.Dexterity.Applications.SmartListDictionary.

CustomerLookupForm customerLookup = SmartList.Forms.CustomerLookup;

// Set the flag indicating that we opened the lookup

GPAddIn.ReturnToLookup = true;

// Open the CustomerLookup form

customerLookup.Open();

// Call the Initialize procedure to configure the Customer Lookup

customerLookup.Procedures.Initialize.Invoke(1, 0,

CustomerNumber.Text, "", "", "", "", "");

}

5. Register the ClickBeforeOriginal event for the Select button.In the Initialize method of the GPAddIn class, register the ClickBeforeOriginalevent of the Select button on the CustomerLookup window. The following C#example shows this registration.

// Select button on the Customers lookup window

Microsoft.Dexterity.Applications.SmartListDictionary.CustomerLookupForm

customerLookupForm = SmartList.Forms.CustomerLookup;

customerLookupForm.CustomerLookup.SelectButton.ClickBeforeOriginal +=

new System.ComponentModel.CancelEventHandler(

SelectButton_ClickBeforeOriginal);

6. Return the ID of the selected item.In the event handler for the ClickBeforeOriginal event of the Select button,check the flag that indicates whether the Visual Studio Tools add-in opened thelookup. If it did, then return the customer number for the customer selected inthe scrolling window of the Customers and Prospects lookup. The following C#example shows the event handler that performs these actions.

void SelectButton_ClickBeforeOriginal(object sender,

System.ComponentModel.CancelEventArgs e)

{

// Run this code only if the add-in opened the lookup.

if (GPAddIn.ReturnToLookup == true)

{

// Retrieve the customer number of the row selected in the

// scrolling window of the Customers lookup.

Microsoft.Dexterity.Applications.SmartListDictionary.

CustomerLookupForm customerLookupForm =

SmartList.Forms.CustomerLookup;

string customerNumber = customerLookupForm.CustomerLookup.

CustomerLookupScroll.CustomerNumber.Value;

// Display the value retrieved

LookupsWindow.CustomerNumber.Text = customerNumber;



// Clear the flag that indicates a value is to be retrieved from

// the lookup.

GPAddIn.ReturnToLookup = false;

}

}

PA

RT

3: R

ES

OU

RC

E R

EFE

RE

NC

E


Part 3: Resource ReferenceThis portion of the documentation provides detailed information about each type ofresource you can access with Visual Studio Tools for Microsoft Dynamics GP. Eachresource has the following:

• Information about accessing the resource• A list of methods• A list of properties• A list of events

The following resources are discussed:

• Chapter 15, “Forms,” describes form resources.

• Chapter 16, “Windows,” describes window resources.

• Chapter 17, “Scrolling Windows,” describes scrolling window resources.

• Chapter 18, “Window Fields,” describes window field resources.

• Chapter 19, “Tables,” describes table resources.

• Chapter 20, “Table Fields,” describes table field resources.

• Chapter 21, “Commands,” describes command resources.

• Chapter 22, “Globals,” describes global variable resources.

• Chapter 23, “Procedures,” describes procedure resources.

• Chapter 24, “Functions,” describes function resources.

• Chapter 25, “Composites,” describes composite resources.


Chapter 15: FormsForms are the basic resource of the Microsoft Dynamics GP application. Theyprovide the organization for the interface presented to the user. The following itemsfor forms are discussed:

• Accessing forms• Form methods• Form properties• Form events

Accessing forms

Forms for an application dictionary are accessed through the dictionary class. Thisclass has a Forms property that provides access to the collection of forms in thedictionary. The dictionary class for the application dictionary is located in thefollowing namespace:


For instance, to access the collection of forms in the Dynamics dictionary, use thefollowing syntax:

Microsoft.Dexterity.Applications.Dynamics.Forms

To access a specific form, such as the Sales Transaction Entry form (SopEntry), usethe 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 thatappears in windows in Microsoft Dynamics GP. The menu item will be availablewhen the form is open. This method takes three parameters:

EventHandler – The function that will be run when the menu item is chosen inMicrosoft Dynamics GP.

MenuItemName – A string containing the text that will be displayed for the menuitem.

AcceleratorKey – A string containing a single character that will be used as theaccelerator key for the menu item. Be sure this accelerator key does not conflict withany existing accelerator keys. If you don’t want an accelerator key, use the emptystring.

P A R T 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 argumentslike standard event handlers.

static void OpenEstimateFreight(object sender, EventArgs e)

{

if (EstimateFreightForm == null)

{

EstimateFreightForm = new EstimateFreight();

}

else

{

if (EstimateFreightForm.Created == false)

{

EstimateFreightForm = new EstimateFreight();

}

}

// Always show and activate the WinForm

EstimateFreightForm.Show();

EstimateFreightForm.Activate();

}

}

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 DynamicsGP.

Dim EstimateFreightHandler as System.EventHandler

EstimateFreightHandler = New System.EventHandler(AddressOf

OpenEstimateFreight)

Dynamics.Forms.SOPEntry.AddMenuHandler(EstimateFreightHandler, "Estimate

Freight", "F")

This code is the event handler for the menu item. Notice that it also takes twoarguments like standard event handlers.

Shared Sub OpenEstimateFreight(ByVal sender As Object, ByVal e As EventArgs)

If EstimateFreightForm Is Nothing Then

Try

EstimateFreightForm = New EstimateFreightForm()

Catch ex As Exception

MessageBox.Show(ex.Message)

End Try

Else

If EstimateFreightForm.Created = False Then

EstimateFreightForm = New EstimateFreightForm()

End If

End If


C H A P T E R 1 5 F O R M S

' Always show and activate the WinForm

EstimateFreightForm.Show()

EstimateFreightForm.Activate()

End Sub

Close()The Close() method closes the form.

Dispose()The Dispose() method releases the memory used for the form after it is no longerneeded.

Open()The Open() method attempts to open the form.

Form properties

Forms provide the following properties:

• Commands• Functions• IsOpen• IsChanged• Procedures

CommandsThe Commands property provides access to the list of commands that are definedby the form. Refer to Chapter 21, “Commands,” to learn more about usingcommands in your application.

FunctionsThe Functions property provides access to the list of form-level functions that aredefined by the form. Refer to Chapter 24, “Functions,” for more information aboutfunctions.

IsChangedThe IsChanged property has the value true if the change flag for the form is set, andfalse if it is not. The change flag is automatically set to true when any field value forthe form has changed.

IsOpenThe IsOpen property has the value true if the form is open, and false if it is not.

ProceduresThe Procedures property provides access to the list for form-level procedures thatare defined by the form. Refer to Chapter 23, “Procedures,” to learn more aboutusing procedures.

TablesThe Tables property provides access to the list of tables that are attached to theform. Refer to Chapter 9, “Working with Tables,” and Chapter 19, “Tables,” for moreinformation about using the tables attached to forms.



Form events

Forms provide the following events:

• OpenBeforeOriginal• OpenAfterOriginal• CloseBeforeOriginal• CloseAfterOriginal

OpenBeforeOriginalThis event occurs when the form is opened, but before the form’s open event is run.This event can be canceled.

OpenAfterOriginalThis event occurs when the form is opened, but after the form’s open event is run.

CloseBeforeOriginalThis event occurs when the form is closed, before the form’s close event is run. Thisevent can be canceled.

CloseAfterOriginalThis event occurs when the form is closed, after the form’s close event is run.


Chapter 16: WindowsWindows are a part of form in Microsoft Dynamics GP. They display the userinterface for the application. The following items are discussed:

• Accessing windows• Window methods• Window properties• Window events

Accessing windowsWindows for an application dictionary are accessed as properties of the form thatthey 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 MicrosoftDynamics 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 inthe window will be focused. Any pending “validate” or “leave” events for thecurrently-focused field will be run. Use this method in situations where you wantall of the pending actions to be run before your integrating application performs itsprocessing.

Window properties

Windows provide the following properties:

• IsChanged• IsOpen

IsChangedThe IsChanged property has the value true if the change flag for the form is set, andfalse if it is not. The change flag is automatically set to true when any field value forthe window has changed.

IsOpenThe IsOpen property has the value true if the window is open, and false if it is not.



Window events

Windows provide the following events:

• OpenBeforeOriginal• OpenAfterOriginal• ActivateBeforeOriginal• ActivateAfterOriginal• CloseBeforeOriginal• CloseAfterOriginal• PrintBeforeOriginal• PrintAfterOriginal• BeforeModalDialog• AfterModalDialog

OpenBeforeOriginalThis event occurs when the window is opened, but before the window’s open eventis run. This event can be canceled.

OpenAfterOriginalThis event occurs when the window is opened, but after the window’s open event isrun.

ActivateBeforeOriginalThis event occurs each time the window becomes active, before the window’sactivate event is run. The activate event occurs every time the window is opened orbrought 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 causedialogs to appear because the application can become suspended in an endless loop.

ActivateAfterOriginalThis event occurs each time the window becomes active, after the window’s activateevent is run.

CloseBeforeOriginalThis event occurs when the window is closed, but before the window’s close eventis run. This event can be canceled.

CloseAfterOriginalThis event occurs when the window is closed, but after the window’s close event isrun.

PrintBeforeOriginalThis event occurs when the print action for the window is chosen, but before thewindow’s print event is run. The print action for a window occurs when the userchooses the Print menu item from the File menu, or clicks the Print button on thewindow. This event can be canceled.

PrintAfterOriginalThis event occurs when the print action for the window is chosen, but after thewindow’s print event is run.


C H A P T E R 1 6 W I N D O W S

BeforeModalDialogThis event occurs when the a modal dialog is displayed by a window, but before thedialog is actually shown to the user. The event arguments allow access theproperties of the modal dialog:

DialogType Indicates the type of modal dialog that is being displayed. TheDialogType enumeration defines the following available types:

Message Contains the text that is displayed in the modal dialog. Setting the valueof this property in the BeforeModalDialog event allows you to change the textdisplayed in the modal dialog. Typically, the value of this parameter is examined tofind 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 tochange 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 tochange 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 ofthis property in the BeforeModalDialog event allows you to change the textdisplayed in the button or the editable field.

Response Indicates the response to the modal dialog. The DialogResponseenumeration defines the available responses:

Setting this property in the BeforeModalDialog event allows your code to respondto the dialog, and prevents the dialog from being displayed to the user. Setting theresponse to None will allow the dialog to be displayed.

The following Visual Basic example creates references to the Sales Transction Entryform and window, and then registers a BeforeModalDialog event for the SalesTransaction Entry window.

' Create a reference to the Sales Transtion Entry form

Shared SOPEntryForm As SopEntryForm = Dynamics.Forms.SopEntry

Type Description

Ask A modal dialog generated by the error, warning, or ask() script commands.

GetString A modal dialog generated by the getstring() command.

Response type Description

Button1 Button 1 in the modal dialog is clicked.



Ok The OK button in the getstring() modal dialog is clicked.

Cancel The Cancel button in the getstring() modal dialog is clicked.

None No response was made.



' Create a reference to the Sales Transaction Entry window

Shared SOPEntryWindow As SopEntryForm.SopEntryWindow = SOPEntryForm.SopEntry

Sub Initialize() Implements IDexterityAddin.Initialize

AddHandler SOPEntryWindow.BeforeModalDialog, AddressOf _

SopEntryWindow_BeforeModalDialog

End Sub

The following example is the BeforeModalDialog event handler for the eventregistered inthe previous example. When a modal dialog is to be displayed, thecode examines the text of the message to determine whether it is the message thatasks 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 anew customer should be created. This prevents the modal dialog from beingdisplayed.

Private Sub SopEntryWindow_BeforeModalDialog(ByVal sender As Object, ByVal e

As BeforeModalDialogEventArgs)

' Examine the dialog to determine whether it is the one to respond do

If e.DialogType = DialogType.Ask Then

If e.Message.Contains("want to add a customer") Then

' Click the Customer button in the modal dialog

e.Response = DialogResponse.Button1

End If

End If

End Sub

AfterModalDialogThis event occurs when the user has acted on a modal dialog displayed by awindow. This event allows you to retrieve the choice that the user made in themodal dialog. Typically, you will examine the DialogType and Message propertiesin the event arguments to find out what dialog is being displayed. Then you canexamine the Response property in the event arguments to learn how the userresponded to the dialog.

The following C# example creates references to the Item Maintenance form and theItem Maintenance window, and then registers for the AfterModalDialog event forthe Item Maintenance window.

// Create a reference to the Item Maintenance form

public static IvItemMaintenanceForm ItemMaintenanceForm =

Dynamics.Forms.IvItemMaintenance;

// Create a reference to the Item Maintenance window

public static IvItemMaintenanceForm.IvItemMaintenanceWindow

ItemMaintenanceWindow = ItemMaintenanceForm.IvItemMaintenance;


{

ItemMaintenanceForm.IvItemMaintenance.AfterModalDialog +=

new EventHandler<AfterModalDialogEventArgs>

(IvItemMaintenance_AfterModalDialog);

}


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 eventregistered inthe previous example. When a modal dialog is to be displayed, thecode examines the text of the message to determine whether it is the message thatasks the user whether they want to delete the current item. The Response propertyof the event arguments is examined to find out whether the user clicked Delete inthe modal dialog. If the user did, the additional information stored for the item isalso deleted.

void IvItemMaintenance_AfterModalDialog(object sender,

AfterModalDialogEventArgs e)

{

// Is it an 'ask' dialog?

if (e.DialogType == DialogType.Ask)

{

// It it verifying a delete action?

if (e.Message.Contains("want to delete"))

{

// Did the user click Delete (button 1)?

if (e.Response == DialogResponse.Button1)

{

// Delete the environmental details for the current item.

DataAccessHelper.DeleteEnvironmentalDetails();

}

}

}

}


Chapter 17: Scrolling WindowsScrolling windows are a special type of window in Microsoft Dynamics GP that areused to display or access data directly from a database table. The following itemsare discussed:

• Accessing scrolling windows• Scrolling window methods• Scrolling window properties• Scrolling window events

Accessing scrolling windows

Scrolling windows for an application dictionary are accessed as properties of thewindow that they are contained in. For example, the Line Scroll scrolling window inthe Sales Transaction Entry window of Microsoft Dynamics GP is accessed using thefollowing syntax:

Dynamics.Forms.SopEntry.SopEntry.LineScroll

The IntelliSense in Visual Studio will tell you what scrolling window in MicrosoftDynamics GP is being referred to by the expression.

Scrolling window methods

There are no additional methods for scrolling windows.

Scrolling window properties

There are no additional properties for scrolling windows.

Scrolling window events

Scrolling windows provide the following events:

• LineFillBeforeOriginal• LineFillAfterOriginal• LineEnterBeforeOriginal• LineEnterAfterOriginal• LineChangeBeforeOriginal• LineChangeAfterOriginal• LineLeaveBeforeOriginal• LineLeaveAfterOriginal• LineInsertBeforeOriginal• LineInsertAfterOriginal• LineDeleteBeforeOriginal• LineDeleteAfterOriginal

LineFillBeforeOriginalThis event occurs before the line fill event for the scrolling window. The line fillevent occurs each time a new line is added to the scrolling window from the linkedtable, such as when the user scrolls to a new line. When the scrolling window firstfills, the line fill event occurs repeatedly until the scrolling window is full. The linefill event also occurs each time the user moves the focus to an existing line in thescrolling window. The line fill event occurs before the line enter event.



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 thescrolling window.

When using this event, you cannot examine the window fields for the scrolling window todetermine what row is being added. The values of the window fields will not have been setyet.

The LineFillBeforeOriginal event can be cancelled. If the event is cancelled, thecurrent row in the table linked to the scrolling window will not be added to thescrolling window.

For example, the following C# code registers the LineFillBeforeOriginal event forthe scrolling window in the Customers and Prospects window in MicrosoftDynamics GP.


{

Dynamics.Forms.CustomerLookup.CustomerLookup.CustomerLookupScroll.

LineFillBeforeOriginal += new System.ComponentModel.CancelEventHandler

(CustomerLookupScroll_LineFillBeforeOriginal);

}

The following is the C# code that runs in response to this event. It allows onlycustomers in the “TERRITORY 2” sales territory to be displayed. TheRmCustomerMstr table is linked to the scrolling window, so the values for thescrolling window come from this table. Notice how the code is accessing the currentrow of the form-level table buffer for the RmCustomerMstr table to find out whatrow is being added to scrolling window. The SalesTerritory field in the current rowof the table is examined. If it is not “TERRITORY 2”, the event is cancelled. Thisprevents the row from being displayed in the scrolling window.

void CustomerLookupScroll_LineFillBeforeOriginal(object sender,

System.ComponentModel.CancelEventArgs e)

{

if(Dynamics.Forms.CustomerLookup.Tables.RmCustomerMstr.SalesTerritory.

Value != "TERRITORY 2")

{

// Not in TERRITORY 2, so do not display the line

e.Cancel = true;

}

}

LineFillAfterOriginalThis event occurs after the line fill event for the scrolling window.

LineEnterBeforeOriginalThis event occurs when the focus moves to a line in the scrolling window, but beforethe scrolling window’s line enter event is run. This event can be canceled.

LineEnterAfterOriginalThis event occurs when the focus moves to a line in the scrolling window, but afterthe scrolling window’s line enter event is run.


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

LineChangeBeforeOriginalThis event occurs when the focus leaves a line in the scrolling window, and thecontents of the line has been modified. The event runs before the scrolling window’sline change event is run. This event can be canceled.

LineChangeAfterOriginalThis event occurs when the focus leaves a line in the scrolling window, and thecontents of the line has been modified. The event runs after the scrolling window’sline change event is run.

LineLeaveBeforeOriginalThis event occurs when the focus leaves a line in the scrolling window, but beforethe scrolling window’s line leave event is run. This event can be canceled.

LineLeaveAfterOriginalThis event occurs when the focus leaves a line in the scrolling window, but after thescrolling window’s line leave event is run.

LineInsertBeforeOriginalThis event occurs when a new line is added to the scrolling window, but before thescrolling window’s line insert event is run. This event can be canceled.

LineInsertAfterOriginalThis event occurs when a new line is added to the scrolling window, but after thescrolling window’s line insert event is run.

LineDeleteBeforeOriginalThis event occurs when a line is removed from the scrolling window, but before thescrolling window’s line delete event is run. This event can be canceled.

LineDeleteAfterOriginalThis event occurs when a line is removed from the scrolling window, but after thescrolling window’s line delete event is run.


Chapter 18: Window FieldsWindow fields display individual data items on a window. The following items arediscussed:

• Accessing window fields• Window field methods• Window field properties• Window field events

Accessing window fields

Windows fields for an application dictionary are accessed as properties of thewindow or scrolling window that they are contained in. For example, the SOPNumber (SopNumber) field is available on the Sales Transaction Entry window(SopEntry). To access it, you would use the following syntax:

Dynamics.Forms.SopEntry.SopEntry.SopNumber

As another example, the QTY To Backorder (QtyToBackOrder) field is available onthe Line Scroll (LineScroll) scrolling window of the Sales Transaction Entrywindow(SopEntry). To access this field, you would use the following syntax:

Dynamics.Forms.SopEntry.SopEntry.LineScroll.QtyToBackOrder

The IntelliSense in Visual Studio will tell you what field in Microsoft Dynamics GP is beingreferred to by the expression.

Some fields in windows are called local fields, because they are used only within aspecific form. For instance, the Sales Transaction Entry window (SopEntry) containsa local field named (L) BillTo Address 1. The (L) in the name is the standard waylocal fields are identified in Microsoft Dynamics GP. In a Visual Studio Tools forMicrosoft 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 1local field, you would use the following syntax:

Dynamics.Forms.SopEntry.SopEntry.LocalBillToAddress1

Window field methods

Window fields provide the following methods:

• Clear()• Disable()• Enable()• Fill()• Focus()• ForceValidate()• Hide()• Lock()• RunValidate()• Show()• Unlock()



Clear()The Clear() method sets the field to its cleared value. The following table lists thecleared value for standard datatypes:

Disable()The Disable() method makes the field appear in a disabled state, and prevents theuser 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 filledvalue for standard datatypes:

Focus()The Focus() method moves the focus to the field.

ForceValidate()The ForceValidate() method controls whether the validate event will occur whenthe focus leaves the field. If the validate event occurs, any validation code for thefield will be run. This method takes one boolean parameter. Supplying the valuetrue forces the validate event to occur. Supplying the value false clears any previouscall 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’sappearance will not change.

Datatype Cleared value

Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string

Time 000000 which corresponds to 12:00:00 AM

Datatype Filled value

Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647

String The length byte (first byte) of the string is set to the storage size of the string minus 1. Each of the remaining bytes is set to string equivalent of ASCII 255.

Time 23:59:59


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 berun.

Show()The Show() method causes a previously hidden field to become visible andaccessible to the user.

Unlock()The Unlock() method causes a previously locked field to become accessible to theuser.

Window field properties

Window fields have the following properties:

• IsEmpty• IsFilled• Value

IsEmptyThe IsEmpty property returns the value true when the value of the field is emptyfor the specific field type. The following table lists the empty value for standarddatatypes:

IsFilledThe IsFilled property returns the value true when the value of the field is set to themaximum value for the specific field type. The following table lists the filled valuefor standard datatypes:

ValueThe Value property is used to set or retrieve the value of the field. The IntelliSensein Visual Studio will tell you what type of value is used for the field.

Datatype Empty value

Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string



Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647


Time 23:59:59



Window field events

Window fields provide the following events:

• Change• EnterBeforeOriginal• EnterAfterOriginal• LeaveBeforeOriginal• LeaveAfterOriginal• ValidateBeforeOriginal• ValidateAfterOriginal

ChangeThis event occurs when the value of the field changes, such as being set by the useror changed by other code in Microsoft Dynamics GP.

ClickAfterOriginalThis event occurs when the user clicks a button, but after the button’s click event isrun.

ClickBeforeOriginalThis event occurs when the user clicks a button, but before the button’s click event isrun. This event can be canceled.

EnterBeforeOriginalThis event occurs when the focus moves to the field, but before the field’s enterevent is run. This event can be canceled.

EnterAfterOriginalThis event occurs when the focus moves to the field, but after the field’s enter eventis run.

LeaveBeforeOriginalThis event occurs when the focus moves from the field, but before the field’s leaveevent is run. This event can be canceled.

LeaveAfterOriginalThis event occurs when the focus moves from the field, but after the field’s leaveevent is run.

ValidateBeforeOriginalThis event occurs when the focus is to move from the field, and the field has beenset to be validated. A field will be validated when its value has been changed, or thevalidation has been forced, such as with the ForceValidate() method. This eventoccurs before the field’s validate event. It can be canceled.

ValidateAfterOriginalThis event occurs when the focus is to move from the field, and the field has beenset to be validated. This event occurs after the field’s validate event.


Chapter 19: TablesTables are the basic resource of the Microsoft Dynamics GP application thatprovides access to the database. Methods provided for each table allow creating,retrieving, updating, or deleting rows from the table in the database. The followingitems 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 interactwith the table buffer when you perform operations on the table. There are two typesof table buffers: global and form-level.

Global table buffersA global table buffer is created when a table is accessed directly through the global listof tables. Global table buffers are accessed through the dictionary class. This classhas a Tables property that provides access to the collection of tables defined in thedictionary. The dictionary class for the application dictionary is located in thefollowing namespace:


For instance, to access the collection of tables in the Dynamics dictionary, use thefollowing syntax:

Microsoft.Dexterity.Applications.Dynamics.Tables

To access a specific table, such as the RM_Customer_MSTR table(RmCustomerMstr), use the syntax shown below. (This example assumes thenamespace mentioned above has been referenced.)

Dynamics.Tables.RmCustomerMstr

The IntelliSense in Visual Studio will tell you what table in Microsoft Dynamics GP isbeing referred to by the expression.

By default, a global table buffer for a table is shared with all of the other VisualStudio Tools add-ins that are accessing that same table. If you want your integrationto create a global table buffer that is not shared, use the Clone() method whencreating the instance of the global table buffer.

Form-level table buffersA form-level table buffer is created when a table is attached to a form in MicrosoftDynamics GP. There is one table buffer for each table that is attachd to the form.Each form-level table buffer is shared by the code that is part of the form, as well asany code outside of the form that accesses the table through that form. The Tablesproperty for the form allows access to the table buffers for the tables that areattached to the form. For example, to access the form-level procedures for SalesTransaction Entry Form (SopEntryForm) in Microsoft Dynamics GP, you would usethe following syntax:



Dynamics.Forms.SopEntry.Tables

The IntelliSense in Visual Studio will tell you what form-level table in Microsoft DynamicsGP 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 locksthe row, allowing changes to be made to it. The row retrieved is determined by thekey 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 beapplied to the row. The value false (the default value) specifies that a passive lockwill be applied.

ChangeFirst()The ChangeFirst() method retrieves the first row from the table and passively oractively locks the row, allowing changes to be made to it. The row retrieved isdetermined by the key specified for the table. The ChangeFirst() method has oneparameter:



C H A P T E R 1 9 T A B L E S

ChangeLast()The ChangeLast() method retrieves the last row from the table and passively oractively locks the row, allowing changes to be made to it. The row retrieved isdetermined by the key specified for the table. The ChangeLast() method has oneparameter:


ChangeNext()The ChangeNext() method retrieves the next row from the table and passively oractively locks the row, allowing changes to be made to it. The row retrieved isdetermined by the key specified for the table and the values of the key fields for therow currently in the table buffer. The ChangeNext() method has one parameter:


ChangePrevious()The ChangePrevious() method retrieves the previous row from the table andpassively or actively locks the row, allowing changes to be made to it. The rowretrieved is determined by the key specified for the table and the values of the keyfields for the row currently in the table buffer. The ChangePrevious() method hasone parameter:


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. Thisnew table buffer instance is not shared, so it is not accessible by other Visual StudioTools add-ins. The Clone() method has no effect when when with form-level tablebuffers.

Close()The Close() method closes the table buffer.


Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string




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. Therow retrieved is determined by the key specified for the table and the values thatwere specified for the key segments.

GetFirst()The GetFirst() method retrieves the first row from the table. No lock is applied tothe 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 therow. 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 tothe row. The row retrieved is determined by the key specified for the table and thevalues 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 isapplied to the row. The row retrieved is determined by the key specified for thetable 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 thetable buffer as the end of the range of rows in the table. The Key property specifieswhich key will be used for the range.

RangeRemove()The RangeRemove() method attempts to delete all of the rows in the current rangefrom the table.

RangeStart()The RangeStart() method specifies the current values of the key segments in thetable buffer as the beginning of the range of rows in the table. The Key propertyspecifies which key will be used for the range.


Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647


Time 23:59:59


C H A P T E R 1 9 T A B L E S

Release()The Release() method releases any passive or active lock for a row in the tablebuffer. The row values remain in the table buffer.

Remove()The Remove() method deletes the current row in the table buffer from the table. Therow 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 therow is locked in the table buffer, it will be updated. If no row in the table is locked, anew row will be added.

Table properties

Tables have the following property:

• Key

KeyThe Key property is used to set or retrieve the key currently being used by the tablebuffer to access the table. The keys for a table are identified by number, beginningwith the value 1. When you specify the key you want to use for a table, you willsupply the corresponding integer. The Table Descriptions window in MicrosoftDynamics GP lists the keys for each table, and the key segments (fields) that eachkey contains.


Chapter 20: Table FieldsTable fields represent individual data items in a row of a table. The following itemsare discussed:

• Accessing table fields• Table field methods• Table field properties

Accessing table fields

Table fields for an application dictionary are accessed as properties of the table thatthey are contained in. For example, the Item Number (ItemNumber) field isavailable in the Inventory Item Master (IvItemMstr) table. To access it, you woulduse the following syntax:

Dynamics.Tables.IvItemMstr.ItemNumber

The IntelliSense in Visual Studio will tell you what field in Microsoft Dynamics GP is beingreferred to by the expression.

Table field methods

Table fields provide the following methods:

• Clear()• Fill()

Clear()The Clear() method sets the field to its cleared value. The following table lists thecleared value for standard datatypes:

Fill()The Fill() method sets the field to its filled value. The following table lists the filledvalue for standard datatypes:


Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string



Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647


Time 23:59:59



Table field properties

Table fields have the following properties:




ValueThe Value property is used to set or retrieve the value of the field. The IntelliSensein Visual Studio will tell you what type of value is used for the field.


Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string



Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647


Time 23:59:59


Chapter 21: CommandsIn Microsoft Dynamics GP, commands are used to encapsulate a small piece offunctionality for the application. They are typically used for navigation. Commandscan appear in menus and also in toolbars in Microsoft Dynamics GP. The followingitems are discussed:

• Command types• Accessing commands• Command methods

Command types

A command can be one of the following types:

Form A form command opens the specified form.

Script A script command runs the script code that is defined for it.

Command list A command list command is a container for other commands. Acommand list can be used as a menu, submenu, or a toolbar.

Accessing commands

Commands for an application dictionary are accessed using the Commandsproperty of the form that they are contained in. Most commands in MicrosoftDynamics GP are contained in forms that are used specifically for commands. Thenames of these forms begin with “Command” and include the module for whichthe commands are used. For example, to access the command used to open theSmartList 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 isbeing 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 amenu or on a toolbar.

Disable()The Disable() method causes the command to appear disabled if it is displayed in amenu or on a toolbar. Once disabled, the command cannot be run.



Enable()The Enable() method causes a previously disabled command to become enabled. Itwill 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 inwhich it appears. The command can still be run.

Run()The Run() method performs the action of the command. For form commands, itopens the corresponding form. For script commands, it executes the script code thatis attached to the command.

Show()The Show() method causes a previously hidden command to be displayed in anymenu or toolbar in which it appears.

Uncheck()The Uncheck() method causes the command to appear unchecked if it is displayedin a menu or on a toolbar.


Chapter 22: GlobalsGlobals are used to hold values accessible to the entire Microsoft Dynamics GPapplication. The following items are discussed:

• Accessing globals• Global properties

Accessing globals

Globals for an application dictionary are accessed through the dictionary class. Thisclass has a Globals property that provides access to the collection of globals in thedictionary. The dictionary class for the application dictionary is located in thefollowing namespace:


For instance, to access the collection of globals in the Dynamics dictionary, use thefollowing syntax:

Microsoft.Dexterity.Applications.Dynamics.Globals

To access a specific global value, such as the current user’s ID (UserId), use thefollowing syntax:

Microsoft.Dexterity.Applications.Dynamics.Globals.UserId

Global properties

Globals have the following properties available:




Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string





ValueThe Value property is used to retrieve the value of the global. The IntelliSense inVisual Studio will tell you what type of value is used for the field. Global valuescannot be set from a Visual Studio Tools for Microsoft Dynamics GP project.


Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647


Time 23:59:59


Chapter 23: ProceduresThere are two types of procedures in a Dynamics GP application dictionary. Globalprocedures are blocks of code that are accessed from various places throughout theapplication. Parameters are used to send values to a procedure and also to returnvalues from it. Form-level procedures are like global procedures, with the exceptionthat they are defined as part of a specific form. Typically, they perform some actionspecific to the form they are defined for. The following items are discussed:

• Accessing global procedures• Accessing form-level procedures• Procedure methods• Procedure events• Parameters for procedures• Invokable procedures

Accessing global proceduresGlobal procedures for an application dictionary are accessed through the dictionaryclass. This class has a Procedures property that provides access to the collection ofglobal procedures in the dictionary. The dictionary class for the applicationdictionary is located in the following namespace:


For instance, to access the collection of global procedures in the Dynamicsdictionary, use the following syntax:

Microsoft.Dexterity.Applications.Dynamics.Procedures

To access a specific global procedure, such as the Get_Next_Form_Note_To_Openprocedure (GetNextFormNoteToOpen), use the syntax shown below. (This exampleassumes the namespace mentioned above has been referenced.)

Dynamics.Procedures.GetNextFormNoteToOpen

The IntelliSense in Visual Studio will tell you what global procedure in Microsoft DynamicsGP is being referred to by the expression.

Accessing form-level proceduresForm-level procedures for an application dictionary are accessed through the formthey are contained in. The Procedures property for the form allows access to theform-level procedures. For example, to access the form-level procedures for SalesTransaction Entry Form (SopEntryForm) in Microsoft Dynamics GP, you would usethe following syntax:

Dynamics.Forms.SopEntry.Procedures

The IntelliSense in Visual Studio will tell you what form-level procedure in MicrosoftDynamics GP is being referred to by the expression.

Procedure methodsProcedures provide the following method:

• Invoke()



Invoke()The Invoke() method is used to run the specified procedure. The parameters for thismethod will depend on the procedure that is being run. The following table lists thetypes of parameters for procedures:

The IntelliSense in Visual Studio will tell you the type of each parameter for a procedure. Itwill 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 theout keyword is required for the parameters to which values are returned.

Dynamics.Procedures.CheckNoteIdString.Invoke("Estimate Freight", out

isPresent, out formNumber);

You can refer to the Microsoft Dynamics GP SDK for details about the proceduresavailable to invoke. Some procedures in Microsoft Dynamics GP have optionalparameters defined. Visual Studio Tools does not support optional parameters. Youmust supply all parameters for a procedure when you invoke it from Visual StudioTools.

Procedure events

Procedures provide the following events:

• InvokeBeforeOriginal• InvokeAfterOriginal

InvokeBeforeOriginalThis event occurs when the procedure is invoked, but before the original procedureis run. The event arguments allow access the parameters of the procedure. Refer toParameters for procedures on page 115 to learn more about working with parametersin procedure events.

InvokeAfterOriginalThis event occurs when the procedure is invoked, but after the original procedure isrun.The event arguments allow access the parameters of the procedure. Refer toParameters for procedures on page 115 to learn more about working with parametersin procedure events.

The following C# example registers the InvokeAfterOriginal event for theAddSuccessfulLoginRecord procedure in Microsoft Dynamics GP.

Dynamics.Procedures.AddSuccessfulLoginRecord.InvokeAfterOriginal +=

new AddSuccessfulLoginRecordProcedure.InvokeEventHandler(

AddSuccessfulLoginRecord_InvokeAfterOriginal);

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.


C H A P T E R 2 3 P R O C E D U R E S

The following C# example is the event handler for the event registered in theprevious example. The event handler for the AddSuccessfulLoginRecord procedureis typically used to perform setup operations, because the user has successfullylogged into a company.

void AddSuccessfulLoginRecord_InvokeAfterOriginal(object sender,

AddSuccessfulLoginRecordProcedure.InvokeEventArgs e)

{

// Setup code is placed here

}

Parameters for procedures

When you invoke a procedure or use procedure events, you will need to work withthe parameters of the procedure.

Learning about the parametersThere are several ways you can learn about the parameters for a procedure:

• When invoking a procedure, the IntelliSense lists the parameters and their datatypes.

• The event arguments passed to the event handler for procedure events will listthe available parameters and their data types.

• The Parameters for Microsoft Dynamics GP section of the Microsoft Dynamics GPSDK contains a complete listing of the parameters for the procedures inMicrosoft Dynamics GP and several integrating dictionaries. The parameterdocuments in this section of the SDK also list the parameter names, which canbe helpful when determining how the parameters are used.

Accessing parameter valuesIn the InvokeBeforeOriginal and InvokeAfterOriginal event handlers, you can usethe event arguments to access the values of the parameters that were passed into theprocedure. Be aware that other applications that integrate with Microsoft DynamicsGP may have changed the values of the parameters.

Changing parameter valuesIn the InvokeBeforeOriginal and InvokeAfterOriginal event handlers, you canchange the values of “out” and “inout” parameters. The values of “in” parameterscannot be changed.

We recommend that you avoid changing parameter values in Microsoft Dynamics GPprocedures. Changing the parameter values can signficantly alter the operation of MicrosoftDynamics GP.

If a procedure is being processed in the background queue in Microsoft DynamicsGP, the event handler will be passed a copy of the original parameters for theprocedure. This means that any changes you make to the parameters will beignored.



Invokable procedures

With this release of Visual Studio Tools for Microsoft Dynamics GP, not allprocedures can be invoked. Procedures with the following characteristics cannot beinvoked:

• The procedure uses “anonymous” parameters. These parameter types aren’tknown at the time the application is compiled.

• The procedure uses “reference” parameters. These parameter types contain alink to a specific resource in the application dictionary.

• If a composite field used as a procedure parameter contains a reference value,that procedure cannot be invoked.

If a procedure cannot be run by this version of Visual Studio Tools, it will not beincluded in the procedure lists displayed by the IntelliSense in Visual Studio.


Chapter 24: FunctionsThere are two types of functions in a Dynamics GP application dictionary. Globalfunctions are blocks of code that are accessed from various places throughout theapplication. Parameters are used to send values to a function and also to returnvalues from it. In addition, functions always return a value. Form-level functions arelike global functions, with the exception that they are defined as part of a specificform. Typically, they perform some action specific to the form they are defined for.The following items are discussed:

• Accessing global functions• Accessing form-level functions• Function methods• Function events• Parameters for functions• Invokable functions

Accessing global functions

Global functions for an application dictionary are accessed through the dictionaryclass. This class has a Functions property that provides access to the collection ofglobal functions in the dictionary. The dictionary class for the application dictionaryis located in the following namespace:


For instance, to access the collection of global functions in the Dynamics dictionary,use the following syntax:

Microsoft.Dexterity.Applications.Dynamics.Functions

To access a specific global function, such as the GetCurrentDirectory function(GetCurrentDirectory), use the following syntax shown below. (This exampleassumes the namespace mentioned above has been referenced.)

Dynamics.Functions.GetCurrentDirectory

The IntelliSense in Visual Studio will tell you what global function in Microsoft DynamicsGP is being referred to by the expression.

Accessing form-level functions

Form-level functions for an application dictionary are accessed through the formthey are contained in. The Functions property for the form allows access to theform-level functions. For example, to access the form-level functions for SalesTransaction Entry Form (SopEntryForm) in Microsoft Dynamics GP, you would usethe following syntax:

Dynamics.Forms.SopEntry.Functions

The IntelliSense in Visual Studio will tell you what form-level function in MicrosoftDynamics GP is being referred to by the expression.



Function methodsFunctions provide the following method:

• Invoke()

Invoke()The Invoke() method is used to run the specified function. The parameters for thismethod will depend on the procedure that is being run. The following table lists thetypes of parameters for functions:

The Invoke() method will have a return value to which the return value of thefunction will be returned.

The IntelliSense in Visual Studio will tell you the type of each parameter and the returnvalue 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 functionsavailable to invoke. Some functions in Microsoft Dynamics GP have optionalparameters defined. Visual Studio Tools does not support optional parameters. Youmust supply all parameters for a function when you invoke it from Visual StudioTools.

Function eventsFunctions provide the following events:

• InvokeBeforeOriginal• InvokeAfterOriginal

InvokeBeforeOriginalThis event occurs when the function is invoked, but before the original function isrun. The event arguments allow access the parameters and return value of thefunction. Refer to Parameters for functions on page 119 to learn more about workingwith parameters and return value in function events.

InvokeAfterOriginalThis event occurs when the function is invoked, but after the original function isrun.The event arguments allow access the parameters and return value of thefunction. Refer to Parameters for functions on page 119 to learn more about workingwith parameters and return value in function events.

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.


C H A P T E R 2 4 F U N C T I O N S

The following C# example registers the InvokeAfterOriginal event for theGetAutoComplete function of the UserDefaultsForm in Microsoft Dynamics GP.

UserDefaultsForm.Functions.GetAutoComplete.InvokeAfterOriginal +=

new SyUserDefaultsForm.GetAutoCompleteFunction.InvokeEventHandler(

GetAutoComplete_InvokeAfterOriginal);

The following C# example is the event handler for the event registered in theprevious example. The event handler uses the event arguments to examine the firstparameter passed into the function. If the parameter value is “DYNSA”, the returnvalue of the function is set to false. This will turn off the auto-complete functionalityfor the DYNSA user.

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;

}

}

Parameters for functions

When you invoke a function or use function events, you will need to work with theparameters and return value of the function.

Learning about the parameters and return valueThere are several ways you can learn about the parameters and return value for afunction:

• When invoking a function, the IntelliSense lists the parameters and returnvalue, along with their data types.

• The event arguments passed to the event handler for function events will listthe available parameters and return value, along with their data types.

• The Parameters for Microsoft Dynamics GP section of the Microsoft Dynamics GPSDK contains a complete listing of the parameters and return values for thefunctions in Microsoft Dynamics GP and several integrating dictionaries. Theparameter documents in this section of the SDK also list the parameter andreturn value names, which can be helpful when determining how theparameters and return value are used.

Accessing parameter and return valuesIn the InvokeBeforeOriginal and InvokeAfterOriginal event handlers, you can usethe event arguments to access the values of the parameters that were passed into thefunction. You can also access the value returned from the function. Be aware thatother applications that integrate with Microsoft Dynamics GP may have changedthe values of the parameters or the return value.



Changing parameter and return valuesIn the InvokeBeforeOriginal and InvokeAfterOriginal event handlers, you canchange the values of “out” and “inout” parameters. The values of “in” parameterscannot be changed. You can also change the value returned from the function.

We recommend that you avoid changing parameter and return values in MicrosoftDynamics GP functions. Changing the parameter and return values can signficantly alterthe operation of Microsoft Dynamics GP.

Invokable functionsWith this release of Visual Studio Tools for Microsoft Dynamics GP, not all functionscan be invoked. Functions with the following characteristics cannot be invoked:

• The function uses “anonymous” parameters. These parameter types aren’tknown at the time the application is compiled.

• The function uses “reference” parameters. These parameter types contain a linkto a specific resource in the application dictionary.

• If a composite field used as a function parameter contains a reference value, thatfunction cannot be invoked.

If a function cannot be run by this version of Visual Studio Tools, it will not beincluded in the function lists displayed by the IntelliSense in Visual Studio.


Chapter 25: CompositesIn Microsoft Dynamics GP, a composite is a group of fields and their associated datatypes which form a single data type. Each part of the composite is called acomponent. In Microsoft Dynamics GP, composites are used to store data thatconsists of several parts, such as the account number. Composites are also used togroup together the parameters that are passed to procedures and functions. Thefollowing items are discussed:

• Composite types• Accessing composites• Composite field methods• Composite field properties• Composite field events

Composite typesWhen you access composite resources from a dictionary, each composite will haveseveral types defined for it. Each type is used in specific situations in MicrosoftDynamics GP. The following table describes the composite types.

In most cases, the IntelliSense will tell you what composite type is required for a specificsituation.

Accessing compositesComposites can be displayed as fields on windows, and are accessed as propertiesof the window or scrolling window they are contained in. Composites can also beused to create variables that are passed as parameters for procedures and functions.

Window fieldsComposite fields are accessed as properties of the window or scrolling window theyare contained in. For example, to access the Account Number CS field in theAccount Maintenance window of Microsoft Dynamics GP, you would use thefollowing syntax:

Dynamics.Forms.GlAccountMaintenance.GlAccountMaintenance.AccountNumberCs

Type Example Description

Base AccountNumberComposite The base implementation of the composite type.

Data AccountNumberCompositeData The base implementation of the composite type, but with properties that provide access to the components of the composite.

Read-only AccountNumberCompositeReadOnly A read-only version of the composite. It is used in cases such as passing the composite value as a parameter for a procedure or function.

With events AccountNumberCompositeWithEvents The composite with the standard window field events.

With full events AccountNumberCompositeWithFullEvents The composite with the standard window field events, and the same field events for each component of the composite.



VariablesIn some cases, you may want to retrieve the value of a composite and use it as avariable in your Visual Studio Tools integration. You can create an instance of thecomposite, and then set the value of the composite variable.

For example, the following C# code creates an instance of the AccountNumberCscomposite, which appears in the Account Maintenance window in MicrosoftDynamics GP. The value of this window field is retrieved. The value of eachcomponent is combined into a string and displayed in a message.

// Create an instance of the AccountNumberCs composite

Microsoft.Dexterity.Applications.DynamicsDictionary.AccountNumberCsComposite

Data accountNumber = new AccountNumberCsCompositeData();

// Reference the Account Maintenance form

Microsoft.Dexterity.Applications.DynamicsDictionary.GlAccountMaintenanceForm

AccountMaintenance = Dynamics.Forms.GlAccountMaintenance;

// Retrieve the Account Number value

accountNumber = AccountMaintenance.GlAccountMaintenance.AccountNumberCs;

string accountNumberString = "";

// Retrieve the individual components

for (int i = 0; i < accountNumber.Length; i++)

{

accountNumberString = accountNumberString + accountNumber[i] + " ";

}

// Display the account number

System.Windows.Forms.MessageBox.Show("Account number: " +

accountNumberString);

ParametersYou can create composite variables and pass them as parameters for procedures andfunctions. A variable based on the “read-only” composite type must be used as theparameter. To create a “read-only” composite variable, you must first create avariable based on the “data” composite type.

For example, the following C# code creates a variable of the typeAccountNumberCompositeData, and sets its component values. A variable of thetype AccountNumberCompositeReadOnly is created. Its constructor uses the“data” composite variable to supply the composite’s value. The “read-only” versionof the composite value is passed as a parameter to the ConvertAcctToAliasStrfunction.

Microsoft.Dexterity.Applications.DynamicsDictionary.AccountNumberComposite

Data accountNumberData = new AccountNumberCompositeData();

accountNumberData[0] = "000";



accountNumberData[3] = "";

// Create the read-only composite that is used for the function call

Microsoft.Dexterity.Applications.DynamicsDictionary.AccountNumberComposite

ReadOnly accountNumber = new AccountNumberCompositeReadOnly

(accountNumberData);


C H A P T E R 2 5 C O M P O S I T E S

// Convert the account number to its account alias

string alias = Dynamics.Forms.GlAcctBase.Functions.ConvertAcctToAliasStr.

Invoke(accountNumber);

// Display the account alias

System.Windows.Forms.MessageBox.Show("Account alias: " + alias);

ComponentsTo access the individual components for most composites, you can use theproperties of the composite. The composite will have a property for eachcomponent of the composite.

Some composites, such as the AccountNumberComposite, are defined dynamicallyby Microsoft Dynamics GP. These composites do not have the named properties toaccess the individual components of the composite. To access components for thesecomposites, you must use the component’s index. For instance, the following C#code creates an instance of the AccountNumber composite and sets the value ofeach component.

AccountNumberCompositeData accountNumberData = new

AccountNumberCompositeData();




accountNumberData[3] = "";

Composite field methods

Composite fields provide the following methods:

• 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. Thefollowing table lists the cleared value for standard datatypes:


Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string




Disable()The Disable() method makes the composite field appear in a disabled state, andprevents the user from making changes to the field.

Enable()The Enable() method allows a previously disabled composite field to receive userinput.

Fill()The Fill() method sets each component of the composite to its filled value. Thefollowing 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 whenthe focus leaves the composite field. If the validate event occurs, any validationcode 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 valuefalse clears any previous call to force the validate event to occur.

Hide()The Hide() method causes the composite field to become invisible and inaccessibleto the user.

Lock()The Lock() method causes a composite field to become inaccessible to the user. Thefield’s appearance will not change.

RunValidate()The RunValidate() method causes any validation code for the composite field to berun.

Show()The Show() method causes a previously hidden composite field to become visibleand accessible to the user.

Unlock()The Unlock() method causes a previously locked composite field to becomeaccessible to the user.


Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647


Time 23:59:59


C H A P T E R 2 5 C O M P O S I T E S

Composite field properties

Composite fields have the following properties:

• IsEmpty• IsFilled• Length• Value

IsEmptyThe IsEmpty property returns the value true when the value of the composite fieldis empty for the specific field type. The following table lists the empty value forstandard datatypes:

IsFilledThe IsFilled property returns the value true when the value of the composite field isset to the maximum value for the specific field type. The following table lists thefilled value for standard datatypes:

LengthThe Length property is used to retrieve the number of components in the compositefield.

ValueThe Value property is used to set or retrieve the value of the composite field. TheIntelliSense in Visual Studio will tell you what type of value is used for the field.


Date 0/0/0

Currency 0

Integer 0

Long 0

String Empty string



Date 12/31/9999

Currency 99999999999999.99999

Integer 32,767

Long 2,147,483,647


Time 23:59:59



Composite field events

Composite fields provide the following events:

• Change• EnterBeforeOriginal• EnterAfterOriginal• LeaveBeforeOriginal• LeaveAfterOriginal• ValidateBeforeOriginal• ValidateAfterOriginal

Composites of the type “with events” supply these events for the composite as asingle field. Composites of the type “with full events” supply these events for thecomposite as a single field, and also for each of the components of the composite.

ChangeThis event occurs when the value of the composite or component changes, such asbeing set by the user or changed by other code in Microsoft Dynamics GP.

EnterBeforeOriginalThis event occurs when the focus moves to the composite field or component, butbefore the field or component enter event is run. This event can be canceled.

EnterAfterOriginalThis event occurs when the focus moves to the composite field or component, butafter the field or component enter event is run.

LeaveBeforeOriginalThis 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.

LeaveAfterOriginalThis event occurs when the focus moves from the composite field or component,but after the field’s leave event is run.

ValidateBeforeOriginalThis 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 orcomponent will be validated when its value has been changed, or the validation hasbeen forced, such as with the ForceValidate() method. This event occurs before thecomposite field or component validate event. It can be canceled.

ValidateAfterOriginalThis 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 eventoccurs after the composite field or component validate event.

PA

RT

4: IN

TE

GR

AT

ION

EX

AM

PLE

S


Part 4: Integration ExamplesThis portion of the documentation describes integration examples that show how touse Visual Studio Tools for Microsoft Dynamics GP. The following examples arediscussed:

• Chapter 26, “Field Defaulter,” describes an example that uses events to defaultfield values in Microsoft Dynamics GP.

• Chapter 27, “Estimate Freight,” describes an example that estimates freightamounts for sales documents in Microsoft Dynamics GP.

• Chapter 28, “Environmental Details,”describes an example that storesadditional environmental detail information for items in Microsoft DynamicsGP.

• Chapter 29, “Lookups,” describes an example the shows how six commonlookups are implemented for a Visual Studio Tools integration.

The following table indicates which features of Visual Studio Tools for MicrosoftDynamics GP features are implemented in each sample.

Field Defaulter

Estimate Freight

Environmental Details

Lookups

Visual Studio Tools form X X X

Access to Dynamics GP fields X X X

Field events X X X X

Form events X X

Modal dialog events X

Procedure/function access X

Table access X X

DUOS integration X

Note integration X

Lookups X

Online help X

Macro support X


Chapter 26: Field DefaulterThis sample application demonstrates how events in Microsoft Dynamics GP can beused to default field values. The sample defaults the City and State fields when auser enters a value for the ZIP code field in the Customer Maintenance window. Thefollowing topics are discussed:

• Overview• Running the sample application• How Visual Studio Tools was used

Overview

This sample application integrates with the Customer Maintenance window inMicrosoft Dynamics GP. It automatically defaults values for the City and State fieldswhen the user supplies a known ZIP Code.

This sample uses a fixed set of ZIP Codes and correspond City and State values. Anactual application would use a more extensive set.

Running the sample application

To run this sample application, perform the following steps:

1. Extract the .zip archive containing the samples.In the folder where Visual Studio Tools was installed, locate the Samples.ziparchive. This archive contains both the C# and Visual Basic versions of thesamples. Extract this archive to a location that you have permissions to access.

2. Open the Field Defaulter sample solution.Using Visual Studio, open the solution file FieldDefaulter.sln for the C# orVisual Basic version of the sample.

3. Verify the references for the sample solution.Use Visual Studio to view the references for the project. The Estimate Freightsample should include references to the following assemblies:

• Application.Dynamics• Microsoft.Dexterity.Bridge

If any of these references for the project are not valid, re-add them to the project.

4. Set the Solution Configuration.Set the Solution Configuration to Release to build the release version of theapplication.

The City and State fieldsare set based on the ZIP

Code value entered.

P A R T 4 I N T E G R A T I O N E X A M P L E S


5. Build the application.From the Build menu, choose Build Solution. If there are no build errors, theassembly for the Field Defaulter application will be built.

6. Install the Field Defaulter assembly.Copy the FieldDefaulter.dll from the Release folder for the project to the AddInsfolder in the Microsoft Dynamics GP installation.

7. Start Microsoft Dynamics GP.The Field Defaulter sample application will loaded.

8. Open the Customer Maintenance window.In Microsoft Dynamics GP, open the Customer Maintenance window.

9. Enter a ZIP Code.For demonstration purposes, this sample application recognizes only a smallnumber of ZIP codes. You can enter any of the follow ZIP codes and have thecorresponding City and State filled in:

When you have finished, close Microsoft Dynamics GP.

How Visual Studio Tools was used

This sample application uses the eventing and resource access features of VisualStudio Tools for Microsoft Dynamics GP.

Resources accessedThe Field Defaulter sample uses the following resources in the Dynamicsdictionary:

Forms• RmCustomerMaintenance

Windows• RmCustomerMaintenance

EventsThe 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 ZIPcode value entered, their value are automatically set in the window.

02109 58104

53151 58474

55111 60605

56560 85012

58078 95014

58102 98052

58103


Chapter 27: Estimate FreightThis sample application demonstrates several techniques useful when creatingMicrosoft Dynamics GP integrations. The sample integrates with the SalesTransaction Entry window. The following topics are discussed:


Overview

This sample application integrates with the Sales Transaction Entry window inMicrosoft Dynamics GP. It retrieves shipping weight information about the items inthe current sales document, calculates an estimated shipping weight for all of theitems, and then estimates the freight cost. The estimated freight value is placed intothe Freight field of the Sales Transaction Entry window.

This sample uses a fixed set of shipping methods and shipping rates. An actualapplication would use a more extensive rate table, and possibly a web service toaccess freight rates.

The Estimate Freight sample uses the table access capabilities of Visual Studio Toolsto access data in Microsoft Dynamics GP.




2. Open the Estimate Freight sample solution.Using Visual Studio, open the solution file EstimateFreight.sln for the C# orVisual Basic version of the sample.

3. Verify the references for the sample solution.Use Visual Studio to view the references for the project. The Estimate Freightsample should include references to the following assemblies:

• Application.Dynamics• Microsoft.Dexterity.Bridge• Microsoft.Dexterity.Shell


The Estimate Freightwindow estimates freight

for the current salesdocument.




5. Build the application.From the Build menu, choose Build Solution. If there are no build errors, theassembly for the Estimate Freight application will be built.

6. Install the Estimate Freight assembly.Copy the EstimateFreight.dll from the Release folder for the project to theAddIns folder in the Microsoft Dynamics GP installation.

7. Install the Estimate Freight help file.Copy the EstimateFreight.chm help file from the EstimateFreight folder into theDynamics GP installation folder. The help file should be placed in the samefolder as the GreatPlains.chm help file.

8. Start Microsoft Dynamics GP.The Estimate Freight sample application will loaded.

9. Open the Sales Transaction Entry window.In Microsoft Dynamics GP, open the Sales Transaction Entry window.

10. Display a sales document.You can display an existing sales document or create a new sales document.

11. Add items to the sales document.Be sure the sales document has inventory items for which the estimatedshipping weight has been specified.

12. Display the Estimate Freight window.In the Additional menu, choose Estimate Freight. The Estimate Freight windowwill appear.

13. Choose a shipping method and calculate the freight.Choose either Air or Ground as the shipping method, and then click Calculateto calculate the estimated freight.

14. Return the Freight amount to the sales document.Click Save to return the estimated freight amount to the Freight field for thesales document.


This sample application uses several features of Visual Studio Tools for MicrosoftDynamics GP to implement this integration.

User interfaceThe special WinForm available for Dynamics GP add-ins was used when creatingthe Estimate Freight window. The customized buttons and images were also used.The sample illustrates technique that can be used to implement window-level notesand the online help link.


C H A P T E R 2 7 E S T I M A T E F R E I G H T

Resources accessedThe Estimate Freight sample uses many resources in the Dynamics dictionary:

Forms• SOPEntry• FormNote1• FormNote2• FormNote3• FormNote4• FormNote5

Windows• SOPEntry

Global procedures• CheckForNote• CheckNoteIdString• GetNextFormNoteToOpen

TablesData from the following tables is accessed to compute the estimated freight for thecurrent sales document:

• IvItemMstr (Inventory Item Master)• SopLineWork (SOP Line Work)

EventsThe Estimate Freight sample registers the following events in Microsoft DynamicsGP:

• A menu handler event for the Sales Transaction Entry form, used to open theEstimate Freight window.

• A form close event on the Sales Transaction Entry form, used to indicate whenthe 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 salesdocument.

• An enter event for the Freight field in the Sales Transaction Entry window, usedto ask the user whether they want to estimate the freight amount if a valuehasn’t been supplied.

• Several form close events for the various “Note” forms in Microsoft DynamicsGP, used to keep the Note button on the Estimate Freight window updated.


Chapter 28: Environmental DetailsThis sample application demonstrates several techniques useful when creatingMicrosoft Dynamics GP integrations. The sample integrates with the ItemMaintenance window. The following topics are discussed:


Overview

This sample application integrates with the Item Maintenance window in MicrosoftDynamics GP. It stores environmental information about the item. The additionaldata is stored in the DUOS (Dynamics User Object Store) table for the currentcompany.

This sample also implements support for the macro system, allowing macros to berecorded and played back for this window.




2. Open the Environmental Details sample solution.Using Visual Studio, open the solution file EnvironmentalDetails.sln for the C#or Visual Basic version of the sample.

3. Verify the references for the sample solution.Use Visual Studio to view the references for the project. The EnvironmentalDetails sample should include references to the following assemblies:

• Application.Dynamics• Microsoft.Dexterity.Bridge• Microsoft.Dexterity.Shell



The Environmental Detailswindow tracks environmental

information for the currentinventory item.



5. Build the application.From the Build menu, choose Build Solution. If there are no build errors, theassembly for the Environmental Details application will be built.

6. Install the Environmental Details assembly.Copy the EnvironmentalDetails.dll from the Release folder for the project to theAddIns folder in the Microsoft Dynamics GP installation.

7. Start Microsoft Dynamics GP.The Estimate Freight sample application will loaded.

8. Open the Item Maintenance window.In Microsoft Dynamics GP, open the Item Maintenance window.

9. Display an item.You can display an existing item or create a new item.

10. Display the Environmental Details window.In the Additional menu, choose Environmental Details. The EnvironmentalDetails window will appear.

11. Supply the environmental details for the item.Enter the following environmental details:

• Yearly energy cost• Notes• Recyclable• Energy Start Rated

12. Save the changes to the item.Click Save in the Item Maintenance window to save the changes for the item.


This sample application uses several features of Visual Studio Tools for MicrosoftDynamics GP to implement this integration.

User interfaceThe special WinForm available for Dynamics GP add-ins was used when creatingthe Environmental Details window.

Resources accessedThe Estimate Freight sample uses many resources in the Dynamics dictionary:

Forms• IvItemMaintenanceForm

Windows• IvItemMaintenanceWindow

TablesData for the integration is stored in the following table:

• SyUserObjectStoreTable (DUOS)


C H A P T E R 2 8 E N V I R O N M E N T A L D E T A I L S

This is the same table used by VBA to store data. The DUOSHelper class of theEnvironmental Details sample contains methods that are used to write, retrieve, anddelete rows from the DUOS table.

EventsThe Environmental Details sample registers the following events in MicrosoftDynamics GP:

• A menu handler event for the Item Maintenance form, used to display theEnvironmental Details form.

• A form open event on the Item Maintenance form, used to create an instance ofthe Environmental Details form.

• A form close event on the Item Maintenance form, used to indicate when theItem Maintenance window has been closed. This event closes theEnvironmental 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 itembeing 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 itembeing displayed.

• A change event for the Save Record field in the Item Maintenance window, usedto save the environmental details when the user saves the item.

• An after modal dialog event for the Item Maintenance window, used to retrievethe response when the user confirms whether to delete the current item. If theuser chooses to delete the current item, the corresponding environmentaldetails information is also deleted.

Macro supportCalls to the RecordMacroItem() method have been added to the controls in theEnvironmental Details form to support recording macro statements. ThePlayMacroItem() method from the DexUIForm base class has been overridden tosupport playback of the macro statements that have been recorded.


Chapter 29: LookupsThis sample application demonstrates how to use several common lookup forms inMicrosoft Dynamics GP. The following topics are discussed:


Overview

This sample application demonstrates how to implement common lookup forms ina Visual Studio Tools integration. Refer to Chapter 14, “Using Lookups,” for detailsabout how to implement lookups.

This sample implements the following lookups:

• Customer Number• Vendor ID• Item Number• GL Account Number• SOP Document Number• POP Document Number.




2. Open the Lookups sample solution.Using Visual Studio, open the solution file Lookups.sln for the C# or VisualBasic version of the sample.

3. Verify the references for the sample solution.Use Visual Studio to view the references for the project. The Lookups sampleshould include references to the following assemblies:

• Application.Dynamics• Application.SmartList• Microsoft.Dexterity.Bridge• Microsoft.Dexterity.Shell





5. Build the application.From the Build menu, choose Build Solution. If there are no build errors, theassembly the for the Lookups application will be built.

6. Install the Lookups assembly.Copy the Lookups.dll from the Release folder for the project to the AddInsfolder in the Microsoft Dynamics GP installation.

7. Start Microsoft Dynamics GP.The Lookups sample application will loaded.

8. Open the About Box window.In Microsoft Dynamics GP, open the About Box window. It is accessed from theHelp menu in the main Microsoft Dynamics GP window.

9. Display the Lookups window.In the Additional menu, choose Lookups. The Lookups window will appear.

10. Use the sample lookups.Use the sample lookups, just as you would any other lookups in MicrosoftDynamics GP.


This sample application uses the basic features of Visual Studio Tools for MicrosoftDynamics GP.

User interfaceThe special WinForm available for Dynamics GP add-ins was used when creatingthe Lookups window.

Resources accessedThe Lookups sample uses the following resources in the Dynamics and SmartListdictionaries:

Forms• AboutBox• CustomerLookupForm• VendorLookupForm• IvItemNumberLookupForm• AccountLookupForm• SopDocumentLookupForm• PopDocumentLookupForm

Composites• AccountNumberCompositeData

Form-level functions• ConvertAcctToStr of the GlAcct form


C H A P T E R 2 9 L O O K U P S

EventsThe Lookups sample registers the following events in Microsoft Dynamics GP:

• A menu handler event for the AboutBox form, used to open the Lookupswindow.

• A click event for the SelectButton field in each of the lookup windows, to notifythe Lookups sample that the user clicked the Select button.

• A validate event for the PopPoLookup field in the PopDocumentLookupwindow, to prevent the validation from running when the POP Number lookupis opened from a Visual Studio Tools integration. This is a work-around for anissue that causes the POP Number lookup to be closed immediately after beingopened.


GlossaryActive lock

A method of locking that ensures only oneuser can change or delete the contents of arow at one time. The data in the locked rowcan’t be changed or deleted by another useruntil the lock is released.

Alternate formsForms from the core Dynamics dictionarythat have been changed by a third-partydeveloper, and are stored in a third-partydictionary.

Application assemblyA .NET assembly used by Visual StudioTools to provide access to the resources inMicrosoft Dynamics GP dictionary. Eachapplication dictionary can have onecorresponding application assembly.

BufferA temporary storage area in a computer’smemory. The Microsoft Dynamics GPruntime uses several types of buffers, such astable buffers and window buffers.

Control areaA band drawn at the top of a MicrosoftDynamics GP window. Controls such asSave, Clear, and Delete buttons are placed inthe control area.

Dictionary Assembly GeneratorThe tool (DAG.exe) used to build applicationassemblies for dictionaries.

Dexterity Bridge assemblyThe assembly Microsoft.Dexterity.Bridge.dllthat provides the access to events inMicrosoft Dynamics GP, as well as theresources in the application dictionaries.

Dictionary classA class used to reference the resources in anapplication dictionary. The class is availableafter a reference to the application assemblyfor a dictionary has been added to the VisualStudio project.

Dexterity Shell assemblyThe assembly Microsoft.Dexterity.Shell.UI.dll that provides the drawing capabilitiesthat allow an integrating application tomatch the appearance of MicrosoftDynamics GP

Forms dictionaryThe dictionary in a Microsoft Dynamics GPinstallation that contains the modified formsfor an application. Each applicationdictionary can have a forms dictionary.

Global fieldsA type of field that can be used in any formor any table in Microsoft Dynamics GP.

Global variablesA variable available the entire time theMicrosoft Dynamics GP application is open.Visual Studio Tools code can read the valueof global variables.

KeyA field or combination of fields within a rowthat is used as the basis by which to store,retrieve, and sort the row in a table.

Launch fileA file that is used to start an application withthe Dynamics GP runtime engine. This filestores the location of the main applicationdictionary, the name and location of anyforms and reports dictionaries, and the nameand location of any integrating dictionaries.

Local fieldsSpecial fields that are defined for and usedonly within a specific form in MicrosoftDynamics GP.

Modified formsForms in the Microsoft Dynamics GPapplication that contain modifications madewith the Modifier.

Passive lockA method of locking that allows other usersto access and make changes to the row.

Product IDAn integer ID that is used to uniquelyidentify an application dictionary. TheDictionary Assembly Generator refers todictionaries based on their product ID.

SegmentsOne field of the group of fields that composea key for a table.

Status areaAn area at the bottom of a MicrosoftDynamics GP window created by a dividerline drawn across the window. Controls likebrowse buttons, note buttons, and helpbuttons are placed in the status area.

Table bufferA buffer that acts as an intermediate storagearea to hold one row from a table.


IndexAAccessing Dictionary Resources, chapter

35-38ActivateAfterOriginal, window event 88ActivateBeforeOriginal, window event 88active locks

defined 143described 57releasing 57

AddIns folder, described 12Additional menu, adding items to 83AddMenuHandler(), form method 83AfterModalDialog, window event 90alternate forms

accessing with code 70creating application assembly for 70defined 143guidelines for accessing 71using try...catch with 71

application assembliescreating 31defined 143described 12installing 5naming convention 31overriding name 34references to 35referencing main application

assembly 34shipped with Visual Studio Tools 12signing 33which to use 31

architecture, for Visual Studio Tools 11assembly information, for integrations 63asynchronous processes, handling for

macro playback 76AutoSetDexColors

control property 27WinForms property 24

Bbackground process error, when not

closing tables 47BeforeModalDialog, window event 89buffers, defined 143Building and Deploying, chapter 63-65building integrations 64buttons

field 28pictures for 28standard 27status area 28toolbar 27toolbar with separator 28types of 27

ButtonType property, for button controls 27

CC#

registering events 39setting assembly information 63unregistering events 42upgrading integrations 15

cancelling events 42Change

composite field event 126window field event 100

Change(), table method 102ChangeFirst(), table method 102ChangeLast(), table method 103ChangeNext(), table method 103ChangePrevious(), table method 103Check(), command method 109Clear()

composite field method 123table field method 107table method 103window field method 98

ClickAfterOriginal, window field event 100

ClickBeforeOriginal, window field event 100

Clone(), table method 103Close()

form method 85table method 103window method 87

CloseAfterOriginalform event 86window event 88

CloseBeforeOriginalform event 86window event 88

combo box controls, described 30command-line, for Dictionary Assembly

Generator 32Commands, form property 85commands

accessing through code 109chapter 109-110command list commands 109form commands 109methods for 109resource reference 109script commands 109types of 109

components, installed with Visual Studio Tools 7

components of compositesaccessing through code 123defined 121retrieving number of components 125

composite fieldsevents for 126methods for 123properties for 125

compositesaccessing components 123

composites (continued)accessing through code 121as procedure and function

parameters 122as variables 122as window fields 121chapter 121-126defined 121resource reference 121retrieving number of components 125types of 121

control areadefined 143described 24

Control Reference, chapter 27-30ControlArea, WinForms property 24controls

adding to forms 25buttons 27combo boxes 30control reference 27labels 30list boxes 30text boxes 29

conventions, in documentation 3Customization Status window 68

DDAG.exe, see Dictionary Assembly

GeneratorDebug, solution configuration 64debugging

attaching to a process 67chapter 67-68examining application 68integrations 67preparations for 67

deleting, rows from tables 51deploying integrations 65Developing Integrations, part 22-71devenv.exe, using to register templates 6Dexterity Bridge assembly

defined 143described 11

Dexterity Shell assemblydefined 143described 11

Dictionary Assembly Generatorapplication assembly 31chapter 31-34commands for 32creating application assemblies 31defined 143described 12, 31IntelliSense data file 32launch file used 33optimizing processing 34output from 31using 32when to use 31where installed 32

I N D E X


dictionary classdefined 143examples 36for alternate forms 70for modified forms 69resource types to access 36using to access dictionary resources

36dictionary resources

accessing 35accessing through dictionary class 36additional resources 37list of 82lists in IntelliSense 36namespace for accessing 36, 37variable for 37working with 82

Disable()command method 109composite field method 124window field method 98

disabling events 68Dispose(), form method 85documentation, symbols and conventions

3Dynamics.exe, application process when

debugging 67

EEnable()

command method 110composite field method 124window field method 98

EnterAfterOriginalcomposite field event 126window field event 100

EnterBeforeOriginalcomposite field event 126window field event 100

Environmental Detailsoverview 135running 135sample integration 135use of Visual Studio Tools 136

errors, for table operations 52Estimate Freight

overview 131running 131sample integration 131use of Visual Studio Tools 132

event arguments, when playing macros 74events

cancelling events 42chapter 39-43disabling 68event arguments 41overview 39registering 39registering with C# code 39registering with Visual Basic code 40responding to 41

events (continued)unregistering 42unregistering with C# code 42unregistering with Visual Basic code

43exceptions

example 71handling for modified and alternate

forms 71

Ffield, buttons 28Field Defaulter

overview 129sample integration 129use of Visual Studio Tools 130

fieldsglobal 143local 143table fields 107window fields 97

files, see tablesFill()

composite field method 124table field method 107table method 104window field method 98

focus, removing from current window 87Focus()

composite field method 124window field method 98

ForceValidate()composite field method 124window field method 98

form-level functionsaccessing through code 117described 117

form-level proceduresaccessing through code 113described 113

form-level table buffersaccessing 101described 46, 101

formsaccessing through code 83chapter 83-86events for 86methods for 83properties for 85resource reference 83

forms dictionariesapplication assemblies for 31application assembly for 69defined 143generating application assembly for

33function, events for 118Functions, form property 85functions

changing parameter values 120changing return values 120

functions (continued)chapter 117-120invokable procedures 120learning parameters 119learning return value 119methods for 118optional parameters 118parameter types 118parameters for 119resource reference 117return value 118

GGet(), table method 104GetFirst(), table method 104GetLast(), table method 104GetNext(), table method 104GetPrevious(), table method 104Getting Started, part 10-13global fields, defined 143global functions

accessing through code 117described 117

global proceduresaccessing through code 113described 113

global table buffersaccessing 101described 46, 101shared access 46, 101

globalsaccessing through code 111chapter 111-112defined 143properties for 111resource reference 111

HHide()


IImplementing Macro Support, chapter

73-76Initialize() method, for registering events

39installation

chapter 5-8Visual Studio Tools SDK 5

Integration Basics, chapter 11-13Integration Examples, part 128-141integrations

building 64debugging 67deploying 65setting assembly information 63

IntelliSense, table information in 46IntelliSense XML files

described 12generating 32


I N D E X

IntelliSense XML files (continued)installing 5naming convention 32

Invoke()function method 118procedure method 114

IsAsynchEventPending() method 76IsChanged, window property 87IsEmpty

composite field property 125global property 111table field property 108window field property 99

IsFilledcomposite field property 125global property 112table field property 108window field property 99

IsOpenform property 85window property 87

KKey, table property 105keys

defined 143for tables 48segments for 48

Llabel controls

described 30linked field 30

launch filedefined 143used by Dictionary Assembly

Generator 33LeaveAfterOriginal


LeaveBeforeOriginalcomposite field event 126window field event 100

Length, composite field property 125light bulb symbol 3LineChangeAfterOriginal, scrolling

window event 95LineChangeBeforeOriginal, scrolling

window event 95LineDeleteAfterOriginal, scrolling

window event 95LineDeleteBeforeOriginal, scrolling

window event 95LineEnterAfterOriginal, scrolling window

event 94LineEnterBeforeOriginal, scrolling

window event 94LineFillAfterOriginal, scrolling window

event 94LineFillBeforeOriginal, scrolling window

event 93

LineInsertAfterOriginal, scrolling window event 95

LineInsertBeforeOriginal, scrolling window event 95

LineLeaveAfterOriginal, scrolling window event 95

LineLeaveBeforeOriginal, scrolling window event 95

LinkField property, for label controls 30list box controls, described 30local fields

accessing 97defined 143described 97naming convention for 97

Lock()composite field method 124window field method 98

lockingactive locking 57multiuser scenarios 57passive locking 57releasing locks 57rows 57

lookupsavailable to use in Visual Studio Tools

78example 78operation of 77using existing lookup windows 77

Lookups sampleintegration 139overview 139running 139use of Visual Studio Tools 140

Mmacro support

asynchronous processes 76for Visual Studio Tools forms 73macro syntax 73overview 73playing macros 74recording macros 73

main dictionarygenerating application assembly for

33overriding application assembly

name 34margin notes 3menus, adding to Additional menu 83Microsoft Dynamics GP

events in 39tables 45

Microsoft Dynamics GP SDKinstalling 3table information in 46

Modified and Alternate Forms, chapter 69-71

modified formsaccessing with code 69

modified forms (continued)creating application assembly for 69defined 143guidelines for accessing 71using try...catch with 71using with Visual Studio Tools 69

multiuser processingdescribed 57reading rows 59removing rows 60updating rows 59

Nnames, overriding application assembly

name 34namespace, for accessing dictionary

resources 36, 37

OOpen()

form method 85window method 87

OpenAfterOriginalform event 86window event 88

OpenBeforeOriginalform event 86window event 88

optimistic concurrency control, described 57

optimizing, application assembly generation 34

Pparameters

for functions 119for procedures 115optional parameters 114, 118

passive locksdefined 143described 57releasing 57

PlayMacroItem() method, overriding 74prerequisites, for using Visual Studio

Tools for Microsoft Dynamics GP 3PrintAfterOriginal, window event 88PrintBeforeOriginal, window event 88Procedures, form property 85procedures

changing parameter values 115chapter 113-116events for 114invokable procedures 116learning parameters 115methods for 113optional parameters 114parameter types 114parameters for 115resource reference 113

process, attaching to Dynamics.exe for debugging 67

product ID, defined 143

I N D E X


product support, for Visual Studio Tools for Microsoft Dynamics GP 4

projectsadding a Dynamics GP form to 23creating for Visual Studio Tools 12

PullFocus(), window method 87

RRangeClear(), table method 104RangeEnd(), table method 104RangeRemove(), table method 104ranges

example 53, 54, 55for table access 53multi-segment key 54removing rows in a range 55simple key 53

RangeStart(), table method 104recording macro statements 73RecordMacroItem() method, described 73references, to application assemblies 35,

69, 70registering events 39registering Visual Studio templates 6regular expressions, for parsing macro

statements 75Release, solution configuration 64Release(), table method 105releasing locks on table rows 57Remove(), table method 105removing rows

from tables 51multiuser considerations 60

Resource Descriptions tool, described 45Resource Reference, part 82-120resources, see dictionary resourcesresponding to events 41retrieving rows

from tables 48multiuser considerations 59

row lockingactive locking 57described 57passive locking 57releasing locks 57

rowslocking 57removing from tables 51retrieving from tables 48saving in tables 49updating in tables 50

Run(), command method 110runtime components, for Visual Studio

Tools 11RunValidate()


Ssample integrations

Environmental Details 135

sample integrations (continued)Estimate Freight 131Field Defaulter 129installing 5Lookups 139

Save(), table method 105saving, rows in tables 49scrolling windows

accessing current row 94accessing through code 93chapter 93-95described 93events for 93preventing rows from displaying 94resource reference 93

SDK, for Microsoft Dynamics GP 3, 78segments

defined 143for keys 48

sharing global table buffers 46Show()


signing, application assemblies 33SN.exe, described 33solution configuration, for a Visual Studio

project 64standard buttons 27status area

buttons 28defined 143described 24

StatusArea, WinForms property 24strong name key file, described 33strong names, for application assemblies

33support, for Visual Studio Tools for

Microsoft Dynamics GP 4symbols in documentation 3

Ttable buffers

defined 143described 46, 101form-level 46global 46sharing access 46

table fieldsaccessing through code 107chapter 107-108methods for 107properties for 108resource reference 107

table ranges, example 53, 54, 55Tables, form property 85tables

accessing through code 46, 101chapter 101-105closing 47errors from table operations 52

tables (continued)in Microsoft Dynamics GP 45keys for 48learning about 45methods for 102multiuser processing 57opening 47properties for 105ranges 53removing rows 51resource reference 101retrieving rows 48saving rows 49updating rows 50working with 45

technical support, for Visual Studio Tools for Microsoft Dynamics GP 4

templatesfor Visual Studio 2005 5for Visual Studio 2008 5manually registering 6

text box controls 29third-party applications, application

assemblies for 31toolbar, button type 27toolbar with separator, button type 28try...catch, using with modified and

alternate forms 71

UUncheck(), command method 110Unlock()


unregistering events 42updating rows

in tables 50multiuser considerations 59

Upgrading an Integration, chapter 15-19upgrading integrations

C# integrations 15described 15from Release 10 19from Release 9 15Visual Basic integrations 17

user interface, for Visual Studio Tools projects 23

Using Lookups, chapter 77-80

VValidateAfterOriginal


ValidateBeforeOriginalcomposite field event 126window field event 100

Valuecomposite field property 125global property 112table field property 108window field property 99


I N D E X

variables, for dictionary resources 37Visual Basic

registering events 40setting assembly information 64unregistering events 43upgrading integrations 17

Visual Studioupgrading to Visual Studio 2008 7version required for Visual Studio

Tools 3Visual Studio Tools

accessing modified forms 69architecture 11capabilities 11components installed 7creating user interface 23development components 12prerequisites 3projects, creating 12runtime components 11SDK installation 5technical support 4what’s new 2

Wwarning symbol 3window fields

accessing through code 97chapter 97-100events for 100methods for 97properties for 99resource reference 97

windowsaccessing through code 87chapter 87-91events for 88local fields 97methods for 87properties for 87resource reference 87

WinFormsadding controls to 25adding to a project 23chapter 23-25properties for 24

Working with Tables, chapter 45-61

XXML files, for IntelliSense 12

visual studio tools for microsoft dynamics gp 2010 programmer’s guide€¦ · · 2011-09-09the...

Documents