VSTDGPProgrammersGuide.pdf

Visual Studio® Tools for Microsoft Dynamics™ GP

Programmer’s GuideRelease 9

Copyright Copyright © 2006 Microsoft Corporation. All rights reserved.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Notwithstanding the foregoing, the licensee of the software with which this document was provided may make a reasonable number of copies of this document solely for internal use.

Trademarks Microsoft, Dexterity, Microsoft Dynamics, Visual Basic, Visual Studio, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation or its affiliates in the United States and/or other countries.

The names of actual companies and products mentioned herein may be trademarks or registered marks - in the United States and/or other countries - of their respective owners.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred.

Intellectual property Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

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.

Limitation of liability The content of this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Microsoft Corporation. Microsoft Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this manual. Neither Microsoft Corporation nor anyone else who has been involved in the creation, production or delivery of this documentation shall be liable for any indirect, incidental, special, exemplary or consequential damages, including but not limited to any loss of anticipated profit or benefits, resulting from the use of this documentation or sample code.

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 May 2006

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

Prerequisites...................................................................................................................................................2

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

Product support ............................................................................................................................................3

Part 1: Getting Started .................................................................................................................6

Chapter 1: Installation ..................................................................................................................... 7Runtime installation .....................................................................................................................................7

SDK installation ............................................................................................................................................7

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

Architecture ...................................................................................................................................................9

Creating a project ........................................................................................................................................10

Part 2: Developing Integrations ................................................................................... 14

Chapter 3: WinForms ...................................................................................................................... 15Adding a Dynamics GP form to a project ...............................................................................................15

WinForm properties....................................................................................................................................16

Adding controls...........................................................................................................................................17

Chapter 4: Control Reference ................................................................................................ 19Buttons..........................................................................................................................................................19

TextBoxes......................................................................................................................................................21

Labels ............................................................................................................................................................22

ComboBoxes ................................................................................................................................................22

ListBoxes ......................................................................................................................................................22

Chapter 5: Dictionary Assembly Generator .............................................................. 23Creating application assemblies ...............................................................................................................23

Output files ..................................................................................................................................................23

Using the Dictionary Assembly Generator .............................................................................................24

Optimizing the assembly generating process.........................................................................................26

Chapter 6: Accessing Dictionary Resources ............................................................ 27Adding references.......................................................................................................................................27

Namespace...................................................................................................................................................28

Dictionary class ...........................................................................................................................................28

Accessing additional resources.................................................................................................................29

Variables for dictionary resources ............................................................................................................29

Chapter 7: Events .............................................................................................................................. 31Registering events.......................................................................................................................................31

Responding to events .................................................................................................................................33

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

Chapter 8: Building and Deploying ................................................................................... 35Setting assembly information....................................................................................................................35

Building an integration ..............................................................................................................................36

Deploying an integration...........................................................................................................................37

Chapter 9: Debugging ................................................................................................................... 39Preparing to debug .....................................................................................................................................39

Examining the application.........................................................................................................................40

Disabling events ..........................................................................................................................................40

Chapter 10: Modified and Alternate Forms............................................................... 41Modified forms............................................................................................................................................41

Alternate forms ...........................................................................................................................................42

Guidelines ....................................................................................................................................................43

Part 3: Resource Reference ................................................................................................46

Chapter 11: Forms ............................................................................................................................. 47Accessing forms ..........................................................................................................................................47

Form methods .............................................................................................................................................47

Form properties...........................................................................................................................................48

Form events .................................................................................................................................................49

Chapter 12: Windows ..................................................................................................................... 51Accessing windows ....................................................................................................................................51

Window methods........................................................................................................................................51

Window properties .....................................................................................................................................51

Window events............................................................................................................................................52

Chapter 13: Scrolling Windows ............................................................................................ 53Accessing scrolling windows ....................................................................................................................53

Scrolling window methods........................................................................................................................53

Scrolling window properties .....................................................................................................................53

Scrolling window events............................................................................................................................53

Chapter 14: Window Fields ....................................................................................................... 55Accessing window fields ...........................................................................................................................55

Window field methods...............................................................................................................................55

Window field properties ............................................................................................................................56

Window field events...................................................................................................................................56

Chapter 15: Commands ............................................................................................................... 59Command types ..........................................................................................................................................59

Accessing commands .................................................................................................................................59

Command methods ....................................................................................................................................59

Chapter 16: Globals ......................................................................................................................... 61Accessing globals ........................................................................................................................................61

Global properties.........................................................................................................................................61

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

Chapter 17: Procedures ............................................................................................................... 63Accessing global procedures .....................................................................................................................63

Accessing form-level procedures..............................................................................................................63

Procedure methods.....................................................................................................................................63

Invokable procedures .................................................................................................................................64

Chapter 18: Functions ................................................................................................................... 65Accessing global functions ........................................................................................................................65

Accessing form-level functions.................................................................................................................65

Function methods .......................................................................................................................................66

Invokable functions ....................................................................................................................................66

Part 4: Integration Examples ............................................................................................68

Chapter 19: Field Defaulter ...................................................................................................... 69Overview......................................................................................................................................................69

Running the sample application...............................................................................................................69

How Visual Studio Tools was used ..........................................................................................................70

Chapter 20: Estimate Freight.................................................................................................. 71Overview......................................................................................................................................................71

Running the sample application...............................................................................................................71

How Visual Studio Tools was used ..........................................................................................................72

Glossary .........................................................................................................................................................75

Index ...................................................................................................................................................................77

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

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.

Prerequisites

You must be using Microsoft Dynamics GP 9.0 with Service Pack 1, or a later release.Since you will be working with Microsoft Dynamics GP, knowledge of theaccounting system will be helpful. Consult the Microsoft Dynamics GPdocumentation resources to learn more about the product.

You will also want to install the SDK for Microsoft Dynamics GP. The SDK isavailable on the Microsoft Dynamics GP Installation CD 2. It contains usefulinformation about Microsoft Dynamics GP, such as lists of commonly-usedprocedures and functions.

To use Visual Studio Tools for Microsoft Dynamics GP, Visual Studio 2005 isrequired. Earlier versions of Visual Studio cannot be used. It is assumed that you arefamiliar with programming in a managed language such as C#. This guide usesboth C# and Visual Basic to demonstrate how to create integrations.

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

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.

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.

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.

http://www.microsoft.com/dynamics

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, “Installation,” explains how to install Visual Studio Tools forMicrosoft 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 1: InstallationThe installation for Visual Studio Tools for Microsoft Dynamics GP is divided intotwo parts. The runtime contains the components needed to run an integration withthe Microsoft Dynamics GP installation. The SDK contains the components neededto create and build integrations. Information about installing these is divided intothe following sections:

• Runtime installation• SDK installation

Runtime installation

Beginning with Release 9, Microsoft Dynamics GP supports multiple installationson a single computer. This release of Visual Studio Tools for Microsoft Dynamics GPcan be installed into the default instance of Microsoft Dynamics GP only.

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

1. Start the Visual Studio Tools runtime installer.

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 installation location and application assemblies to install.The location of the default installation of Microsoft Dynamics GP will beselected. The application assemblies allow Visual Studio Tools add-ins to accessresources in each of the products listed.

If you need to install additional application assemblies at a later time, you can do sousing the maintenance mode for the installer.

Click Next to continue.

5. Begin the installation.Click Install to begin installing the runtime components.

6. Finish the installation.Click Finish to complete the installation.

SDK installation

The Visual Studio Tools for Microsoft Dynamics GP SDK installer requires VisualStudio 2005 to be installed. It also requires the Visual Studio Tools for MicrosoftDynamics GP runtime to be installed.

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

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


1. Start the Visual Studio Tools SDK installer.

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 IntelliSense XML files to install.The IntelliSense XML files allow Visual Studio to display information about theresources accessed through the application assemblies.

If you need to install additional IntelliSense XML files at a later time, you can do sousing the maintenance mode for the installer.

Click next to continue.

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

6. Finish the installation.Click Finish to complete the installation.


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 3, “WinForms,” and Chapter 4, “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, and fields in each dictionary. They canalso access global variables, commands, procedures, and functions defined in eachdictionary. You will learn about accessing dictionary resources in Chapter 6,“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 7, “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.UI.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.

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


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 5, “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 components are installed in the Microsoft Dynamics GP folder:

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.

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

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 3, “WinForms,” describes how to create WinForms that have theappearance of windows in Microsoft Dynamics GP.

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

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

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

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

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

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

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


Chapter 3: 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 3 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 4, “Control Reference,” for moreinformation about individual controls.

To add a control, justselect it in the Toolbox

and drag it onto the form.


Chapter 4: 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 4 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. ListBox controls have the AutoSetDexColorsproperty that can be set to True so the control colors will match colors in MicrosoftDynamics GP.

A label control displaysthe text label that appears

next to another control.


Chapter 5: 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 runtime installation. These are the assemblies for the coreapplication (Dynamics.dic) and the other applications that are delivered withMicrosoft Dynamics GP.

When developing integrations that use resources from these dictionaries, alwaysuse the application assemblies that are included with the runtime installation. Theseassemblies are digitally signed, indicating they were produced by Microsoft. Don’tgenerate your own versions of application assemblies for dictionaries shipped withthe 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 is the application assembly. This is the managed code assemblythat provides access to the resources in a dictionary. Each dictionary can have onecorresponding 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 stored in the productinformation for the dictionary. Any spaces or special characters in the product nameare removed.

For example, the application assembly that provides access to resources in theDynamics.dic application dictionary is named Application.Dynamics.dll. Theapplication assembly that provides access to the resources in the forms dictionary(Forms.dic) is named Application.Dynamics.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 into the MicrosoftDynamics GP application folder. Typically this will be the following location:

C:\Program Files\Microsoft Dynamics\GP

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

Important: For Visual Studio Tools for Microsoft Dynamics GP Release 9, you must use alaunch file named Dynamics.set when you create application assemblies.

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 default launch file (Dynamics.set) is assumed.

dag.exe 3333 /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 main Dynamics GP product.

dag.exe 0 /F

This command produces two files:

• Application.Dynamics.ModifiedForms.dll• Application.Dynamics.ModifiedForms.xml

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.

dag.exe 3333 /M /S:Sample.snk



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 6: 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 5,“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 four primary resource types in a dictionary are accessed through properties ofthe class. These resource types are:

• Forms• Globals• Procedures• Functions

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 6 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

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 7: 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

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 7 E V E N T S

Responding to events

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

}

}

Some 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


Chapter 8: 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 2006")]

[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. 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 8 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.

• The Visual Studio Tools for Microsoft Dynamics GP Runtime installer, alongwith instructions that state which application assemblies are required for yourintegration.

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

• Instructions that explain how to install your integration.


Chapter 9: 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 10: 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 5,“Dictionary Assembly Generator.” For example, the following commandcreates the application assembly for the forms dictionary of the core DynamicsGP product:

dag.exe 0 /F

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 5, “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:

dag.exe 3333 /M

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

}

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 11, “Forms,” describes form resources.

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

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

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

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

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

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

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


Chapter 11: 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” submenuthat appears in the “Extras” menu in Microsoft Dynamics GP. The menu item willbe available when 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();

}

}

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• Procedures

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


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

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

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 17, “Procedures,” to learn more aboutusing procedures.

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 12: 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 windows

Windows 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 property:

• IsOpen

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

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.


Chapter 13: 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:

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

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.



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 14: 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:

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

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.

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.

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 property:

• Value

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.

Window field events

Window fields provide the following events:

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


C H A P T E R 1 4 W I N D O W F I E L D S

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.

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 15: 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 16: 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 property available:

• Value

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.


Chapter 17: 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• Invokable procedures

Accessing global procedures

Global 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 procedures

Form-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 methods

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

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 table buffers as parameters. Table buffers are a feature of theDynamics GP runtime engine, and are used when accessing data in thedatabase.

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

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.


Chapter 18: 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• 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 methods

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

Invokable functions

With 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 table buffers as parameters. Table buffers are a feature of theDynamics GP runtime engine, and are used when accessing data in thedatabase.

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

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.

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 19, “Field Defaulter,” describes an example that uses events to defaultfield values in Microsoft Dynamics GP.

• Chapter 20, “Estimate Freight,” describes an example that estimates freightamounts for sales documents in Microsoft Dynamics GP.


Chapter 19: Field DefaulterThis sample application, written in C#, demonstrates how events in MicrosoftDynamics GP can be used to default field values. The sample defaults the City andState fields when a user enters a value for the ZIP code field in the CustomerMaintenance window. The following topics are discussed:

• Overview• Running the sample application• How Visual Studio Tools was used

Overview

This sample C# 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. Open the Field Defaulter sample solution.Using Visual Studio, open the solution file FieldDefaulter.sln. This file is locatedin the FieldDefaulter folder inside the Samples folder for Visual Studio Tools forMicrosoft Dynamics GP.

2. Verify the references for the sample solution.Use the Solution Explorer to view the references for the project. The EstimateFreight sample 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.

3. Set the Solution Configuration.Set the Solution Configuration to Release to build the release version of theapplication.

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

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

6. Start Microsoft Dynamics GP.The Field Defaulter sample application will loaded.

7. Open the Customer Maintenance window.In Microsoft Dynamics GP, open the Customer Maintenance window.

8. 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 20: Estimate FreightThis sample application, written in C#, demonstrates several techniques usefulwhen creating Microsoft Dynamics GP integrations. The sample integrates with theSales Transaction Entry window. The following topics are discussed:

• Overview• Running the sample application• How Visual Studio Tools was used

Overview

This sample C# 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 GPConnNet.dll to establish a connection tothe SQL database. It uses SQL statements to retrieve the data needed for the freightcalculations.

Running the sample application

To run this sample application, perform the following steps:

1. Open the Estimate Freight sample solution.Using Visual Studio, open the solution file EstimateFreight.sln. This file islocated in the EstimateFreight folder inside the Samples folder for Visual StudioTools for Microsoft Dynamics GP.

2. Verify the references for the sample solution.Use the Solution Explorer to view the references for the project. The EstimateFreight sample should include references to the following assemblies:

• Application.Dynamics• GPConnNet• Microsoft.Dexterity.Bridge• Microsoft.Dexterity.Shell.UI

If any of these references for the project are not valid, re-add them to the project.

The Estimate Freightwindow estimates freight

for the current salesdocument.

P A R T 4 I N T E G R A T I O N E X A M P L E S


3. Set the Solution Configuration.Set the Solution Configuration to Release to build the release version of theapplication.

4. Build the application.From the Build menu, choose Build Solution. If there are no build errors, theassembly the for the Estimate Freight application will be built.

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

6. 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 Dynamics.chm help file.

7. Start Microsoft Dynamics GP.The Estimate Freight sample application will loaded.

8. Open the Sales Transaction Entry window.In Microsoft Dynamics GP, open the Sales Transaction Entry window.

9. Display a sales document.You can display an existing sales document or create a new sales document.

10. Add items to the sales document.Be sure the sales document has inventory items for which the estimatedshipping weight has been specified.

11. Display the Estimate Freight window.In the Extras menu, point to Additional, and choose Estimate Freight. TheEstimate Freight window will appear.

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

13. Return the Freight amount to the sales document.Click Save to return the estimated freight amount to the Freight field for thesales document.

How Visual Studio Tools was used

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 0 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

Globals• IntercompanyId• SqlDataSourceName• UserId• SqlPassword

Global procedures• CheckForNote• CheckNoteIdString• GetNextFormNoteToOpen

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.


GlossaryAlternate forms

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

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.

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.

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.


IndexAAccessing Dictionary Resources, chapter

27-30ActivateAfterOriginal, window event 52ActivateBeforeOriginal, window event 52AddIns folder, described 10AddMenuHandler(), form method 47alternate forms

accessing with code 42creating application assembly for 42defined 75guidelines for accessing 43using try...catch with 43

application assembliescreating 23defined 75described 10naming convention 23references to 27shipped with Visual Studio Tools 10signing 25which to use 23

architecture, for Visual Studio Tools 9assembly information, for integrations 35AutoSetDexColors

control property 19WinForms property 16

BBuilding and Deploying, chapter 35-37building integrations 36buttons

field 20pictures for 20standard 19status area 20toolbar 19toolbar with separator 20types of 19

ButtonType property, for button controls 19

CC#

registering events 31setting assembly information 35

cancelling events 33Change, window field event 57Check(), command method 59Close()

form method 48window method 51

CloseAfterOriginalform event 49window event 52

CloseBeforeOriginalform event 49window event 52

combo box controls, described 22command-line, for Dictionary Assembly

Generator 24Commands, form property 48commands

accessing through code 59chapter 59-60command list commands 59form commands 59methods for 59resource reference 59script commands 59types of 59

control areadefined 75described 16

Control Reference, chapter 19-22ControlArea, WinForms property 16controls

adding to forms 17buttons 19combo boxes 22control reference 19labels 22list boxes 22text boxes 21

conventions, in documentation 3Customization Status window 40

DDAG.exe, see Dictionary Assembly

GeneratorDebug, solution configuration 36debugging

attaching to a process 39chapter 39-40examining application 40integrations 39preparations for 39

deploying integrations 37Developing Integrations, part 14-43Dexterity Bridge assembly

defined 75described 9

Dexterity Shell assemblydefined 75described 9

Dictionary Assembly Generatorapplication assembly 23chapter 23-26commands for 24creating application assemblies 23defined 75described 10, 23IntelliSense data file 24launch file used 25optimizing processing 26output from 23using 24when to use 23where installed 24

dictionary classdefined 75examples 28for alternate forms 42for modified forms 41resource types to access 28using to access dictionary resources

28dictionary resources

accessing 27accessing through dictionary class 28additional resources 29list of 46lists in IntelliSense 28namespace for accessing 28, 29variable for 29working with 46

Disable()command method 59window field method 55

disabling events 40Dispose(), form method 48documentation, symbols and conventions

3Dynamics.exe, application process when

debugging 39

EEnable()

command method 60window field method 56

EnterAfterOriginal, window field event 57EnterBeforeOriginal, window field event

57Estimate Freight

overview 71running 71sample integration 71use of Visual Studio Tools 72

eventscancelling events 33chapter 31-33disabling 40overview 31registering 31registering with C# code 31registering with Visual Basic code 32responding to 33

exceptionsexample 43handling for modified and alternate

forms 43Extras menu, adding items to 47

Ffield, buttons 20Field Defaulter

overview 69sample integration 69use of Visual Studio Tools 70

focus, removing from current window 51

I N D E X


Focus(), window field method 56ForceValidate(), window field method 56form-level functions

accessing through code 65described 65

form-level proceduresaccessing through code 63described 63

formsaccessing through code 47chapter 47-49events for 49methods for 47properties for 48resource reference 47

forms dictionariesapplication assemblies for 23application assembly for 41defined 75generating application assembly for

25Functions, form property 49functions

chapter 65-66invokable procedures 66methods for 66parameter types 66resource reference 65return value 66

GGetting Started, part 6-11global functions

accessing through code 65described 65

global proceduresaccessing through code 63described 63

globalsaccessing through code 61chapter 61properties for 61resource reference 61

HHide()


IInitialize() method, for registering events

31installation

chapter 7-8Visual Studio Tools runtime 7Visual Studio Tools SDK 7

Integration Basics, chapter 9-11Integration Examples, part 68-73integrations

building 36debugging 39deploying 37

integrations (continued)setting assembly information 35

IntelliSense XML filesdescribed 10generating 24installing 8naming convention 24

Invoke()function method 66procedure method 64

IsOpenform property 49window property 51

Llabel controls

described 22linked field 22

launch file, used by Dictionary Assembly Generator 25

LeaveAfterOriginal, window field event 57

LeaveBeforeOriginal, window field event 57

light bulb symbol 3LineChangeAfterOriginal, scrolling

window event 54LineChangeBeforeOriginal, scrolling

window event 54LineDeleteAfterOriginal, scrolling

window event 54LineDeleteBeforeOriginal, scrolling

window event 54LineEnterAfterOriginal, scrolling window

event 53LineEnterBeforeOriginal, scrolling

window event 53LineInsertAfterOriginal, scrolling

window event 54LineInsertBeforeOriginal, scrolling

window event 54LineLeaveAfterOriginal, scrolling

window event 54LineLeaveBeforeOriginal, scrolling

window event 54LinkField property, for label controls 22list box controls, described 22local fields

accessing 55defined 75described 55naming convention for 55

Lock(), window field method 56

Mmain dictionary, generating application

assembly for 25maintenance mode

to install application assemblies 7to install IntelliSense XML files 8

margin notes 3

menus, adding to Extras menu 47Microsoft Dynamics GP, events in 31Microsoft Dynamics GP SDK, installing 2Modified and Alternate Forms, chapter

41-43modified forms

accessing with code 41creating application assembly for 41defined 75guidelines for accessing 43using try...catch with 43using with Visual Studio Tools 41

Nnamespace, for accessing dictionary

resources 28, 29

OOpen()

form method 48window method 51

OpenAfterOriginalform event 49window event 52

OpenBeforeOriginalform event 49window event 52

optimizing, application assembly generation 26

Pprerequisites, for using Visual Studio

Tools for Microsoft Dynamics GP 2PrintAfterOriginal, wndow event 52PrintBeforeOriginal, window event 52Procedures, form property 49procedures

chapter 63-64invokable procedures 64methods for 63parameter types 64resource reference 63

process, attaching to Dynamics.exe for debugging 39

product support, for Visual Studio Tools for Microsoft Dynamics GP 3

projectsadding a Dynamics GP form to 15creating for Visual Studio Tools 10

PullFocus(), window method 51

Rreferences, to application assemblies 27,

41, 42registering events 31Release, solution configuration 36Resource Reference, part 46-66resources, see dictionary resourcesresponding to events 33Run(), command method 60runtime components, for Visual Studio

Tools 9


I N D E X

RunValidate(), window field method 56

Ssample integrations

Estimate Freight 71Field Defaulter 69

scrolling windowsaccessing through code 53chapter 53-54described 53events for 53resource reference 53

SDK, for Microsoft Dynamics GP 2Show()


signing, application assemblies 25SN.exe, described 25solution configuration, for a Visual Studio

project 36standard buttons 19status area

buttons 20defined 75described 16

StatusArea, WinForms property 16strong name key file, described 25strong names, for application assemblies

25support, for Visual Studio Tools for

Microsoft Dynamics GP 3symbols in documentation 3

Ttechnical support, for Visual Studio Tools

for Microsoft Dynamics GP 3text box controls 21third-party applications, application

assemblies for 23toolbar, button type 19toolbar with separator, button type 20try...catch, using with modified and

alternate forms 43

UUncheck(), command method 60Unlock(), window field method 56user interface, for Visual Studio Tools

projects 15

VValidateAfterOriginal, window field event

57ValidateBeforeOriginal, window field

event 57Value

global property 61window field property 56

variables, for dictionary resources 29Visual Basic

registering events 32setting assembly information 36

Visual Studio, version required for Visual Studio Tools 2

Visual Studio Toolsaccessing modified forms 41architecture 9capabilities 9creating user interface 15development components 10prerequisites 2projects, creating 10runtime components 9runtime installation 7SDK installation 7technical support 3

Wwarning symbol 3window fields

accessing through code 55chapter 55-57events for 56methods for 55properties for 56resource reference 55

windowsaccessing through code 51chapter 51-52events for 52local fields 55methods for 51properties for 51resource reference 51

WinFormsadding controls to 17adding to a project 15chapter 15-17properties for 16

XXML files, for IntelliSense 10

VSTDGPProgrammersGuide.pdf

Documents

Transcript of VSTDGPProgrammersGuide.pdf