Visual Studio Tools for Microsoft Dynamics GP

Programmers Guide
Release 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. Microsoft Corporation disclaims any warranty regarding the sample code contained in this documentation, including the warranties of merchantability and fitness for a particular purpose. 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. 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.

Warranty disclaimer

Limitation of liability

License agreement

Publication date

May 2006

Contents
Introduction ................................................................................................................................................. 2
Whats in this manual...................................................................................................................................2 Prerequisites...................................................................................................................................................2 Symbols and conventions ............................................................................................................................3 Product support ............................................................................................................................................3

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

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

Chapter 2: Integration Basics.................................................................................................... 9

What Visual Studio Tools provides ............................................................................................................9 Architecture ...................................................................................................................................................9 Creating a project ........................................................................................................................................10

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

Chapter 3: WinForms ...................................................................................................................... 15
Adding a Dynamics GP form to a project ...............................................................................................15 WinForm properties....................................................................................................................................16 Adding controls...........................................................................................................................................17

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

Buttons..........................................................................................................................................................19 TextBoxes......................................................................................................................................................21 Labels ............................................................................................................................................................22 ComboBoxes ................................................................................................................................................22 ListBoxes ......................................................................................................................................................22

Chapter 5: Dictionary Assembly Generator .............................................................. 23

Creating application assemblies ...............................................................................................................23 Output files ..................................................................................................................................................23 Using the Dictionary Assembly Generator .............................................................................................24 Optimizing the assembly generating process.........................................................................................26

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

Adding references.......................................................................................................................................27 Namespace...................................................................................................................................................28 Dictionary class ...........................................................................................................................................28 Accessing additional resources.................................................................................................................29 Variables for dictionary resources ............................................................................................................29

Chapter 7: Events .............................................................................................................................. 31

Registering events.......................................................................................................................................31 Responding to events .................................................................................................................................33

PROGRAMMERS

GUIDE

C O N T E N T S

Chapter 8: Building and Deploying ................................................................................... 35

Setting assembly information....................................................................................................................35 Building an integration ..............................................................................................................................36 Deploying an integration...........................................................................................................................37

Chapter 9: Debugging ................................................................................................................... 39

Preparing to debug .....................................................................................................................................39 Examining the application.........................................................................................................................40 Disabling events ..........................................................................................................................................40

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

Modified forms............................................................................................................................................41 Alternate forms ...........................................................................................................................................42 Guidelines ....................................................................................................................................................43

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

Chapter 11: Forms ............................................................................................................................. 47
Accessing forms ..........................................................................................................................................47 Form methods .............................................................................................................................................47 Form properties...........................................................................................................................................48 Form events .................................................................................................................................................49

Chapter 12: Windows ..................................................................................................................... 51

Accessing windows ....................................................................................................................................51 Window methods........................................................................................................................................51 Window properties .....................................................................................................................................51 Window events............................................................................................................................................52

Chapter 13: Scrolling Windows ............................................................................................ 53

Accessing scrolling windows ....................................................................................................................53 Scrolling window methods........................................................................................................................53 Scrolling window properties .....................................................................................................................53 Scrolling window events............................................................................................................................53

Chapter 14: Window Fields ....................................................................................................... 55

Accessing window fields ...........................................................................................................................55 Window field methods...............................................................................................................................55 Window field properties ............................................................................................................................56 Window field events...................................................................................................................................56

Chapter 15: Commands ............................................................................................................... 59

Command types ..........................................................................................................................................59 Accessing commands .................................................................................................................................59 Command methods ....................................................................................................................................59

Chapter 16: Globals ......................................................................................................................... 61

Accessing globals ........................................................................................................................................61 Global properties.........................................................................................................................................61

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 17: Procedures ............................................................................................................... 63

Accessing global procedures .....................................................................................................................63 Accessing form-level procedures..............................................................................................................63 Procedure methods.....................................................................................................................................63 Invokable procedures .................................................................................................................................64

Chapter 18: Functions ................................................................................................................... 65

Accessing global functions ........................................................................................................................65 Accessing form-level functions.................................................................................................................65 Function methods .......................................................................................................................................66 Invokable functions ....................................................................................................................................66

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

Chapter 19: Field Defaulter ...................................................................................................... 69
Overview......................................................................................................................................................69 Running the sample application...............................................................................................................69 How Visual Studio Tools was used ..........................................................................................................70

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

Overview......................................................................................................................................................71 Running the sample application...............................................................................................................71 How Visual Studio Tools was used ..........................................................................................................72

Glossary ......................................................................................................................................................... 75 Index ................................................................................................................................................................... 77

PROGRAMMERS

GUIDE

iii

iv

P R O G R A M M E R S

G U I D E

INTRODUCTION

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

Whats in this manual

The Visual Studio Tools for Microsoft Dynamics GP Programmers Guide is designed to give you an in-depth understanding of how to use these tools to create an application that integrates with Microsoft Dynamics GP. Even if you are familiar with using Visual Studio to develop applications, you will find it helpful to browse the material presented here. Information is divided into the following parts: Part 1, Getting Started, explains how to install Visual Studio Tools for Microsoft Dynamics GP and begin creating an integration. Part 2, Developing Integrations, provides detailed information about creating WinForms that match the Microsoft Dynamics GP appearance. Interacting with Microsoft Dynamics GP through events is discussed. Building, deploying, and debugging integrations are also addressed. Part 3, Resource Reference, provides detailed information about interacting with the various types of resources in Microsoft Dynamics GP. Part 4, Integration Examples, describes example integrations that use Visual Studio 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 the accounting system will be helpful. Consult the Microsoft Dynamics GP documentation resources to learn more about the product. You will also want to install the SDK for Microsoft Dynamics GP. The SDK is available on the Microsoft Dynamics GP Installation CD 2. It contains useful information about Microsoft Dynamics GP, such as lists of commonly-used procedures and functions. To use Visual Studio Tools for Microsoft Dynamics GP, Visual Studio 2005 is required. Earlier versions of Visual Studio cannot be used. It is assumed that you are familiar with programming in a managed language such as C#. This guide uses both 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

IN T RO D U C T IO N

Symbols and conventions

To help you use this documentation more effectively, weve used the following symbols and conventions within the text to make specific types of information stand out.
Symbol Description

The light bulb symbol indicates helpful tips, shortcuts, and suggestions. Warnings indicate situations you should be aware of when completing tasks.
Margin notes summarize important information.

Margin notes call attention to critical information and direct you to other areas of the documentation where a topic is explained.
Description

Convention

Part 1, Getting Started Adding controls

using System.IO;

Bold type indicates a part name. Italicized type indicates a section name. This font is used to indicate script examples. Acronyms are spelled out the first time theyre used. Small capital letters indicate a key or a key sequence.

Chapter 5, Web Methods Quotation marks indicate a chapter name.

Dictionary Assembly Generator (DAG)

TAB

or ALT+M

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

PROGRAMMERS

GUIDE

P R O G R A M M E R S

G U I D E

PART 1: GETTING STARTED

Part 1: Getting Started

This portion of the documentation describes how to get started creating an integration using Visual Studio Tools for Microsoft Dynamics GP. The following topics are discussed: Chapter 1, Installation, explains how to install Visual Studio Tools for Microsoft Dynamics GP. Chapter 2, Integration Basics, describes the architecture of a Visual Studio Tools for Microsoft Dynamics GP integration. It also explains how to create a project for a new integration.

P R O G R A M M E R S

G U I D E

Chapter 1:

Installation
The installation for Visual Studio Tools for Microsoft Dynamics GP is divided into two parts. The runtime contains the components needed to run an integration with the Microsoft Dynamics GP installation. The SDK contains the components needed to create and build integrations. Information about installing these is divided into the following sections: Runtime installation SDK installation

Runtime installation
Beginning with Release 9, Microsoft Dynamics GP supports multiple installations on a single computer. This release of Visual Studio Tools for Microsoft Dynamics GP can be installed into the default instance of Microsoft Dynamics GP only. To install the Visual Studio Tools for Microsoft Dynamics GP runtime, complete the following 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 be selected. The application assemblies allow Visual Studio Tools add-ins to access resources in each of the products listed. If you need to install additional application assemblies at a later time, you can do so using 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 Visual Studio 2005 to be installed. It also requires the Visual Studio Tools for Microsoft Dynamics GP runtime to be installed. To install the Visual Studio Tools for Microsoft Dynamics GP SDK, complete the following procedure:

PROGRAMMERS

GUIDE

PA RT

G E TT I N G

S T A R TE 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 the resources accessed through the application assemblies. If you need to install additional IntelliSense XML files at a later time, you can do so using 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 new templates being installed. This process may take a few minutes to complete. 6. Finish the installation. Click Finish to complete the installation.

P R O G R A M M E R S

G U I D E

Chapter 2:

Integration Basics
Before you create an integration using Visual Studio Tools for Microsoft Dynamics GP, it will be helpful to understand the basics of an integration. The following topics are discussed: 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 for an integrating application:

Customized WinForms
Any WinForms included in an integrating application can use capabilities provided by Visual Studio Tools for Microsoft Dynamics GP to match the appearance of the core application. The appearance of the window as well as the various controls in the window can be customized. You will learn about creating windows for your integration in Chapter 3, WinForms, and Chapter 4, Control Reference.

Access to dictionary resources

Integrating applications have access to the numerous resources available in the application dictionaries used for Microsoft Dynamics GP. An integrating application can access the forms, windows, and fields in each dictionary. They can also access global variables, commands, procedures, and functions defined in each dictionary. You will learn about accessing dictionary resources in Chapter 6, Accessing Dictionary Resources.

Access to events
Integrating applications can be notified of events that occur in Microsoft Dynamics GP, such as a window being opened, or the focus moving to a field. The applications can respond to the events, performing actions like verifying field values or opening additional windows. Chapter 7, Events, contains information about registering for and responding to events.

Architecture
Visual Studio Tools for Microsoft Dynamics GP consists of runtime components and development components.

Runtime components
The runtime components for Visual Studio Tools are installed with Microsoft Dynamics GP, and provide the functionality used by the integrations. These consist of the following: Dexterity Shell This assembly (Microsoft.Dexterity.Shell.UI.dll) provides the drawing capabilities that allow an integrating application to match the appearance of Microsoft Dynamics GP. Dexterity Bridge This assembly (Microsoft.Dexterity.Bridge.dll) provides the access to events in Microsoft Dynamics GP, as well as the resources in the application dictionaries.

PROGRAMMERS

GUIDE

PA RT

G E TT I N G

S T A R TE D

Application assemblies Each dictionary that will be accessed by a Visual Studio Tools for Microsoft Dynamics GP integration will have an application assembly. Each application assembly provides access to the resources in its corresponding dictionary. For example, the Application.Dynamics.dll assembly provides access to the resources in the Dynamics.dic dictionary. Visual Studio Tools for Microsoft Dynamics GP includes the application assemblies for all the modules that ship with Microsoft Dynamics GP. You can use the Dictionary Assembly Generator tool (DAG.exe) to create application assemblies for other third-party dictionaries for Microsoft Dynamics GP. You will learn more about this tool in Chapter 5, Dictionary Assembly Generator. AddIns folder The assemblies for the integrating applications created with Visual Studio Tools for Microsoft Dynamics GP are placed in this folder. When Microsoft Dynamics GP is launched, it automatically looks in this folder and attempts to launch the integrating applications it finds there.

Development components
The following components are installed in the Microsoft Dynamics GP folder: DAG.exe This is the Dictionary Assembly Generator tool, used to create application assemblies for dictionaries. You will use this to create application assemblies for third-party dictionaries that do not have them. You will also use it to create application assemblies for forms dictionaries in cases where your integration must interact with modified forms in Microsoft Dynamics GP. IntelliSense XML files The IntelliSense XML file contains the information about the application assembly that is displayed in the IntelliSense within Visual Studio. The name of the application XML file matches that of the application assembly it corresponds to. For example, the Application.Dynamics.xml file contains information about the Application.Dynamics.dll assembly. The following components are installed into the Visual Studio installation: Visual Basic project This is the template project for an add-in that is based in Visual Basic. Visual C# project This is the template project for an add-in that is based in Visual C#.

Creating a project
Use the following procedure to create a new Visual Studio project for a Microsoft Dynamics GP add-in. 1. Start Visual Studio. If it isnt 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 you have selected, choose Dynamics GP.

10

P R O G R A M M E R S

G U I D E

C H A P T E R

I N T E G R A T I O N

B AS I C S

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

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

PROGRAMMERS

GUIDE

11

12

P R O G R A M M E R S

G U I D E

PART 2: DEVELOPING INTEGRATIONS

Part 2: Developing Integrations

This portion of the documentation describes the various techniques you will use as you develop integrations using Visual Studio Tools for Microsoft Dynamics GP. The following topics are discussed: Chapter 3, WinForms, describes how to create WinForms that have the appearance of windows in Microsoft Dynamics GP. Chapter 4, Control Reference, provides details of the various controls that are modified 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 resources in dictionaries from your integrating application. Chapter 7, Events, describes how to register for and respond to events for Microsoft Dynamics GP. Chapter 8, Building and Deploying, explains how to build and deploy an integration you have created. Chapter 9, Debugging, explains how to debug an integration created with Visual Studio Tools for Microsoft Dynamics GP. Chapter 10, Modified and Alternate Forms, describes how to access resources on modified forms and alternate forms in Microsoft Dynamics GP.

14

P R O G R A M M E R S

G U I D E

Chapter 3:

WinForms
Standard WinForms are the basis for the user interface for add-ins created with Visual Studio Tools for Microsoft Dynamics GP. These WinForms and the controls placed on them are specially modified to match the appearance of Microsoft Dynamics GP. Information about WinForms is divided into the following sections: 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 following procedure: 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.

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.

PROGRAMMERS

GUIDE

15

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

WinForm properties
WinForms that are added to a Visual Studio Tools for Microsoft Dynamics GP project have several additional properties that control their appearance. Setting these properties correctly helps match the appearance of Microsoft Dynamics GP. These properties are: AutoSetDexColors ControlArea StatusArea

These WinForm properties are found in the Dexterity group in the Properties pane in Visual Studio.

AutoSetDexColors
The AutoSetDexColors property controls whether the colors used for the WinForm will automatically match the color scheme selected in the user preferences within Microsoft Dynamics GP. Set this property to True to match the Microsoft Dynamics GP appearance.

ControlArea
The ControlArea property specifies whether the band called the control area is drawn at the top of the WinForm. In standard Microsoft Dynamics GP windows, controls such as Save, Clear, and Delete buttons are placed in the control area. Set this property to True to display the control area for a WinForm.

This is the control area.

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

This is the status area.

16

P R O G R A M M E R S

G U I D E

C H A P T E R

W I N F O R M S

Adding controls
You can add controls to the forms for your Microsoft Dynamics GP integration the same way you add them to standard windows forms. Simply select the control in the Toolbox and drag it out onto the form.

To add a control, just select it in the Toolbox and drag it onto the form.

When you add the controls, additional properties will be available for some of them to match the Microsoft Dynamics GP appearance. For example, push buttons will have additional properties. Refer to Chapter 4, Control Reference, for more information about individual controls.

PROGRAMMERS

GUIDE

17

18

P R O G R A M M E R S

G U I D E

Chapter 4:

Control Reference
You can use any of the available controls on the WinForms for your Microsoft Dynamics GP integration. Some of the standard controls have been customized to better match the appearance of Microsoft Dynamics GP. This portion of the documentation describes the controls that have additional properties or updated characteristics when used on a WinForm in a Visual Studio Tools for Microsoft Dynamics GP project. The following controls are discussed: Buttons TextBoxes Labels ComboBoxes ListBoxes

Buttons
Button controls are used for each of the button types in a Microsoft Dynamics GP form. The button controls on a WinForm for a Microsoft Dynamics GP project get their additional characteristics from the dexButtonProvider you see on the WinForm layout. The ButtonType property is an additional property available for each button. It specifies how the button control is displayed and what characteristics it will have. You can set the AutoSetDexColors property to True so the button colors will match colors in Microsoft Dynamics GP. The following is a list of the settings for the ButtonType property, and a description of how each button type is used.

Standard
Standard buttons dont have their appearance modified changed when placed on a WinForm for a Dynamics GP project. The following illustration shows a standard button.

This is a standard button

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

PROGRAMMERS

GUIDE

19

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

ToolbarWithSeparator
The buttons with the type ToolbarWithSeparator buttons are typically placed in the control area, like buttons with the type Toolbar. However, they have an additional separator line drawn on the right side of the button to separate it from the other controls in the control area. The following illustration shows two buttons that have the type ToolbarWithSeparator. Notice the separator line drawn to the right of each button.
These are toolbar buttons with separators.

StatusArea
Buttons placed in the status area at the bottom of a window should have the type StatusArea. These buttons should display only graphics, and will have a special 3-D border drawn around them when the pointer is placed over them. These buttons should have the Tooltip property set so they will display a description of the action the button performs. A status area button is shown in the following illustration. It displays a tooltip that describes the purpose of the button.

Buttons in the status area typically have only pictures.

Field
Buttons that show only pictures, and are placed next to other controls in the form should have the ButtonType property set to Field. These buttons are used for things like lookups or expansions. Several buttons with this type are shown next to a text control in the following illustration.
These are field buttons.

Pictures for buttons

Each Visual Studio for Microsoft Dynamics GP project includes several standard images that are used for buttons in Microsoft Dynamics GP. These images (in PNG format) should be used with the buttons you create for your integrations. The following table lists the images and describes how they are used.
Image Name
Field_Delete.png Field_Edit.png Field_Expansion.png Field_Lookup.png Field_MapPoint.png

Description
Used for delete buttons in the window area placed next to fields. Used for edit buttons in the window area placed next to fields. Used for expansion buttons in the window area placed next to fields. Used for lookup buttons in the window area placed next to fields. Used for MapPoint buttons in the window area placed next to fields.

20

P R O G R A M M E R S

G U I D E

C H A P T E R

C O N T R O L

R E F E R E N C E

Image

Name
Field_NoteAbsent.png Field_NotePresent.png HelpImage.png Toolbar_Cancel.png Toolbar_Clear.png Toolbar_Copy.png Toolbar_Delete.png Toolbar_DeleteAll.png Toolbar_New.png Toolbar_Open.png Toolbar_Post.png Toolbar_Print.png Toolbar_Redisplay.png Toolbar_Save.png Toolbar_Void.png VCR_First.png VCR_Last.png VCR_Next.png VCR_Previous.png Window_NoteAbsent.png Window_NotePresent.png

Description
Used for note buttons in the window area placed next to fields. Used for note buttons in the window area placed next to fields. Used for the Help button placed in the status area of the window. Used for the Cancel button placed in the window control area. Used for the Clear button placed in the window control area. Used for the Copy button placed in the window control area. Used for the Delete button placed in the window control area. Used for the Delete All button placed in the window control area. Used for the New button placed in the window control area. Used for the Open button placed in the window control area. Used for the Post button placed in the window control area. Used for the Print button placed in the window control area. Used for the Redisplay button placed in the window control area. Used for the Save button placed in the window control area. Used for the Void button placed in the window control area. Used for the First browse control in the window status area. Used for the Last browse control in the window status area. Used for the Next browse control in the window status area. Used for the Previous browse control in the window status area. Used for the note button in the window status area. Used for the note button in the window status area.

TextBoxes
TextBox controls are used for the string, integer, currency, date, and time controls in a Microsoft Dynamics GP form. Text boxes have the AutoSetDexColors property that can be set to True so the control colors will match colors in Microsoft Dynamics GP.
A TextBox control is used for standard fields like currency values.

PROGRAMMERS

GUIDE

21

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

Unlike the standard controls in Microsoft Dynamics GP, the textbox controls have no built-in support to format data such as currency values. You will need to add additional code to your integration to match the behavior of the controls in Microsoft Dynamics GP. For instance, the following C# code sets the value of the textbox in the previous illustration. It uses the Format method for the String object to format the currency value.
// 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 the Microsoft Dynamics GP form. They correspond to the static text items that appear in standard Microsoft Dynamics GP windows.
A label control displays the text label that appears next to another control.

Label controls have the LinkField property that should be set when a specific field is being labeled. This property is set to the name of the control that the label applies to. When specified in the Microsoft Dynamics GP User Preferences, the label will be drawn with the single underline that is standard for prompts. To have the underlined label draw correctly, be sure the AutoSize property for the label is set to False.

ComboBoxes
Use the ComboBox control in cases where you would use a drop-down list or combo box in Microsoft Dynamics GP. ComboBox controls have the AutoSetDexColors property that can be set to True so the control colors will match colors in Microsoft Dynamics GP. The following illustration shows a ComboBox control being used as a drop-down list in a Microsoft Dynamics GP form.

ListBoxes
Use the ListBox control in cases where you would used a list box or multi-select list box in Microsoft Dynamics GP. ListBox controls have the AutoSetDexColors property that can be set to True so the control colors will match colors in Microsoft Dynamics GP.

22

P R O G R A M M E R S

G U I D E

Chapter 5:

Dictionary Assembly Generator

The Dictionary Assembly Generator (DAG.exe) is a utility included with Visual Studio Tools for Microsoft Dynamics GP that creates a managed code assembly that provides access to resources in an application dictionary. Information about this tool is divided into the following sections: 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 for Microsoft Dynamics GP runtime installation. These are the assemblies for the core application (Dynamics.dic) and the other applications that are delivered with Microsoft Dynamics GP. When developing integrations that use resources from these dictionaries, always use the application assemblies that are included with the runtime installation. These assemblies are digitally signed, indicating they were produced by Microsoft. Dont generate your own versions of application assemblies for dictionaries shipped with the Microsoft Dynamics GP product. You will create application assemblies for the following cases: A forms dictionary exists for a product, and you want your Microsoft Dynamics GP integration to access the modified resources in the forms dictionary. You have installed a third-party dictionary for which no application assembly exists, and you want to access resources in this dictionary from your Microsoft Dynamics GP integration. The third-party dictionary could contain new forms and other resources. It could contain alternate forms from the Dynamics.dic dictionary.

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

Application assembly
The most important is the application assembly. This is the managed code assembly that provides access to the resources in a dictionary. Each dictionary can have one corresponding application assembly. 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

PROGRAMMERS

GUIDE

23

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

ProductName is automatically derived from product name stored in the product information for the dictionary. Any spaces or special characters in the product name are removed. For example, the application assembly that provides access to resources in the Dynamics.dic application dictionary is named Application.Dynamics.dll. The application assembly that provides access to the resources in the forms dictionary (Forms.dic) is named Application.Dynamics.ModifiedForms.dll.

IntelliSense data file

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

Information from the application assembly XML file is displayed in IntelliSense.

Using the Dictionary Assembly Generator

The Dictionary Assembly Generator (DAG.exe) is installed into the Microsoft Dynamics 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 run from a command prompt. Open a command prompt and set the current location to the 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 dictionary for which you want to build the application assembly. Look in the launch file (typically Dynamics.set) for a list of the products installed.

24

P R O G R A M M E R S

G U I D E

C H A P T E R

D I C T I O N A R Y

A S S EM B L Y

G E N ER AT O R

Optionally, you can specify the launch file that the Dictionary Assembly Generator will look in to find the list of installed products and the corresponding dictionary locations. If you dont supply the name of the launch file, DAG.exe will look for the launch file named Dynamics.set. Important: For Visual Studio Tools for Microsoft Dynamics GP Release 9, you must use a launch file named Dynamics.set when you create application assemblies.

Building an application assembly

The Dictionary Assembly Generator will build an application assembly for the main dictionary for an application or for the forms dictionary for an application. When generating an assembly for an application dictionary, use the /M parameter. For example, the following command generates the application assembly for the main dictionary of the Sample Integrating Application. This application has the product ID 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 dictionary of 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 assembly

You 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 is being used. The Dictionary Assembly Generator can sign the assemblies that it creates. It can fully sign the assemblies, or delay sign them. You can use the SN.exe utility (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 use it every time you build or rebuild application assemblies. The following example shows how the application assembly for the sample integrating application is fully signed using the Sample.snk strong name key. The Sample.snk file was generated using the SN.exe utility.
dag.exe 3333 /M /S:Sample.snk

PROGRAMMERS

GUIDE

25

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

Optimizing the assembly generating process

Producing an application assembly for large dictionaries is a resource-intensive process. The Dictionary Assembly Generator will use a large amount of memory (often over 1 gigabyte) and substantial processor time when producing an application 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.

26

P R O G R A M M E R S

G U I D E

Chapter 6:

Accessing Dictionary Resources

To create an integration for Microsoft Dynamics GP or the additional applications that are installed with it, your code must access resources in the various application dictionaries. This portion of the documentation describes how to do this for your project. The following topics are discussed: Adding references Namespace Dictionary class Accessing additional resources Variables for dictionary resources

Adding references
To access the resources in a specific dictionary, a project must contain a reference to the application assembly for that dictionary. When you create a new Visual Studio Tools for Microsoft Dynamics GP project, it will automatically contain a reference to the Application.Dynamics.dll application assembly. This provides access to resources in the Dynamics.dic dictionary. To access resources in other dictionaries, add references to the application assemblies for them. If a dictionary doesnt 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 application installed with Microsoft Dynamics GP, the project should contain a reference to the Application.SampleIntegratingApp.dll application assembly. The following illustration shows this reference for a C# project.

This reference provides access to the resources in the corresponding dictionary.

PROGRAMMERS

GUIDE

27

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

Namespace
Resources for a dictionary are accessed through the following namespace: Microsoft.Dexterity.Applications 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, its included using the Imports statement. Referencing the namespace prevents you from having to fully-qualify references to dictionary resources.

Dictionary class
The resources in a dictionary are accessed through a single class that is available after you add the reference to the dictionarys application assembly. The class has the same name that appears in the application assembly. For instance, the class to access resources for the Dynamics dictionary is named Dynamics. Similarly, the class used to access resources for the Sample Integrating Application is named SampleIntegratingApp. This is the same name that appears in the application assembly, Application.SampleIntegratingApp.dll. The four primary resource types in a dictionary are accessed through properties of the 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 a list of the specific type of resources available in the dictionary. For example, the following illustration shows the forms resources in the Dynamics core application.
Type the dictionary class name and the resource type property. IntelliSense displays a list of resources.

When youve selected a resource of the specific type, you will see a list of the properties, methods, and events available for that resource. The following illustration shows some of the properties, methods, and events for the AboutBox form in the Dynamics dictionary.

28

P R O G R A M M E R S

G U I D E

C H A P T E R

A C C E S S I N G

D I C T I O N A R Y

R ES O U R C E S

Accessing additional resources

Several additional resource types are accessed through the Forms property of a dictionary class. These include: Windows Commands Form-level procedures Form-level functions

As an example, the following C# statement opens the Customer Maintenance window. 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 the Vendor Maintenance window.
Dynamics.Forms.PmVendorMaintenance.PmVendorMaintenance.Comment1.Value = "A preferred vendor";

You will learn more about the details about using each resource type in Part 3, Resource Reference.

Variables for dictionary resources

Within your code, it may be useful to create variables for specific resources in an application dictionary. The definitions for the various dictionary resources are found in an additional namespace available in the application assembly. This namespace has the same name that appears in the application assembly, but has Dictionary appended. For instance, to reference the definitions for resources in the Dynamics main dictionary, you would use this namespace: Microsoft.Dexterity.Applications.DynamicsDictionary To reference resources for the Sample Integrating Application, you would use this namespace: Microsoft.Dexterity.Applications.SampleIntegratingAppDictionary; After creating the variable, you can assign its value and then use it in your code. For example, the following C# code creates a variable for the Vendor Maintenance form in Microsoft Dynamics GP. It assigns the form to the variable, and then uses it to open the form.
PmVendorMaintenanceForm VendorMaintenanceForm; VendorMaintenanceForm = Dynamics.Forms.PmVendorMaintenance; VendorMaintenanceForm.Open();

PROGRAMMERS

GUIDE

29

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

Using a variable can simplify your code, especially when accessing dictionary resources that have long names. For example, the following C# code creates a variable for the Customer Maintenance window in Microsoft Dynamics GP. Then it sets the values of two fields in the window. Notice it take less code to set the field when the variable for the window is used.
// 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";

30

P R O G R A M M E R S

G U I D E

Chapter 7:

Events
Applications that integrate with Microsoft Dynamics GP often need to be notified when specific events occur in the system. This portion of the documentation describes how to register to be notified when events occur in the system. It also describes how to write event handlers that can respond to the events. Information is divided into the following sections: Registering events Responding to events

Registering events
Your integrating application must register every event that it should be notified of in the system. Event registrations are added to the Initialize() method, located in the template code that is automatically added when you created your Visual Studio Tools for Microsoft Dynamics GP project. The resources for which you can register events, such as forms, windows, or fields, each list the events they make available. For example, a form has the following events available: OpenBeforeOriginal OpenAfterOriginal CloseBeforeOriginal CloseAfterOriginal

Refer to each resource type described in Part 3, Resource Reference, for the list of events that are available for that resource. To register an event, find the resource for which you want to register the event. Pick the event you want, and then specify the event handler method. The event handler is the method that contains the code that runs in response to the event.

C#
Visual Studio will assist you when you register an event in C# code. Begin by referencing the resource for which you want to register an event. Add the += operator, and Visual Studio will display IntelliSense indicating it will complete the event handler. Simply press the TAB key to add the event handler registration.

PROGRAMMERS

GUIDE

31

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

After the event handler registration is added, Visual Studio will offer to add the event handler method for the new event. Press the TAB key again to add the event handler method. When youre finished, the completed event will look similar to the following:
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 Basic
Registering an event in a Visual Basic project requires two steps. First, in the Initialize() method of the project, the AddHandler statement registers the event. The AddHandler statement takes two parameters. The first specifies the resource and event, while the second specifies the event handler method that will be run. The following example registers the AfterOpen event for the Customer Maintenance form in Microsoft Dynamics GP.
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 this method must match those required by the event. The IntelliSense for the event displays the parameters the event handler must have.

The parameters required for the event handler method are displayed.

The following example shows the event handler method added for the event created in the previous example.
Public Sub RMCustMaintAfterOpen(ByVal sender As Object, ByVal e _ As System.EventArgs) MsgBox("Not Implemented") End Sub

32

P R O G R A M M E R S

G U I D E

C H A P T E R

E V E N T S

Responding to events
The event handler method contains the code that runs in response to the event. This code can perform whatever action is required for your integrating application. For example, the following C# code is the event handler that runs in response to the value of the Sales Document Number field being changed in the Sales Transaction Entry window. If the EstimateFreight form is open, the controls on the form are set.
void SopNumber_Change(object sender, EventArgs e) { // If the Estimate Freight form is open, update the document number // and clear the other controls so the new calculation can be performed. if (EstimateFreightForm.Created == true) { EstimateFreightForm.textBoxDocumentNumber.Text = SOPEntryWindow.SopNumber.Value; EstimateFreightForm.textBoxEstimatedFreight.Clear(); EstimateFreightForm.textBoxTotalWeight.Clear(); } }

Some events can be cancelled through the event handler. Typically, these are events that occur before the event in the core application, such as the OpenBeforeOriginal event for a form. The event argument parameter that is passed to the event handler for these events has a special type that allows the event to be cancelled. For example, the following Visual Basic example is the event handler for the BeforeOpen event of the Customer Maintenance form. The event handler method examines the current user logged into the system. If its the sa user, a message is displayed and the window isnt opened. Notice how the event arguments are used to 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

PROGRAMMERS

GUIDE

33

34

P R O G R A M M E R S

G U I D E

Chapter 8:

Building and Deploying

This portion of the documentation describes how to build and deploy an integration created with Visual Studio Tools for Microsoft Dynamics GP. Information is divided into the following sections: Setting assembly information Building an integration Deploying an integration

Setting assembly information

Its important to set the assembly information so the assembly you build for your Visual Studio Tools for Microsoft Dynamics GP integration is properly identified and versioned. Be sure you set the following items: Title Description Company Major, minor, and build numbers

C# application
For integrations written in C#, the assembly information is set in the AssemblyInfo.cs source file for the project. The following portion of this file shows the various name values that should be set.
// 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 numbers that should be set.
// Version information for an assembly consists of the following four values: // // // // // // // 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")] Major Version Minor Version Build Number Revision

PROGRAMMERS

GUIDE

35

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

Visual Basic application

For integrations written in Visual Basic, the assembly information is set in the Assembly Information window. Access this window. To view this windows, choose to display the properties for the Visual Basic project. Click the Application tab, and then click the Assembly Information button.

Building an integration
To build the integration, complete the following procedure: 1. Set the solution configuration. If youre building a test version of the integration, set the solution configuration to Debug. If you are building a final version of the integration, set the solution configuration to Release.
Set the solution configuration to either Debug or 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 folder for 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 GP starts. Verify that your integration is working properly.

36

P R O G R A M M E R S

G U I D E

C H A PT E R

B U I LD IN G

A N D

D EP LO Y IN G

Deploying an integration
When deploying your integration built with Visual Studio Tools for Microsoft Dynamics GP, be sure that you include the following: The assembly for your integration. The Visual Studio Tools for Microsoft Dynamics GP Runtime installer, along with instructions that state which application assemblies are required for your integration. Any additional application assemblies you generated that are specific to your integration. Instructions that explain how to install your integration.

PROGRAMMERS

GUIDE

37

38

P R O G R A M M E R S

G U I D E

Chapter 9:

Debugging
When developing an integrating application, you may find it necessary to examine the code with the Visual Studio debugger. Information about debugging your Microsoft Dynamics GP integration is divided into the following sections: Preparing to debug Examining the application Disabling events

Preparing to debug
To prepare your integrating application for debugging, complete the following procedure. 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 is loaded. 3. Set breakpoints in your code. Within Visual Studio, set breakpoints in your code to indicate where you want processing 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 Visual Studio, 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 it in the list.

Locate the Dynamics.exe process and select it in the list.

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

PROGRAMMERS

GUIDE

39

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

Examining the application

Once your integrating application has stopped at a breakpoint, you can use Visual Studios 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 code you want to examine. 3. Examine your code. When Visual Studio encounters a breakpoint, it will become the active application. Use the tools within Visual Studio to examine your code.
Examine your code while stopped at the breakpoints you set.

4. Finish debugging. When you have finished debugging your integrating application, choose Stop Debugging from the Debug menu in Visual Studio.

Disabling events
In some cases, you may want to disable the events for the Visual Studio Tools addins to confirm whether they are causing some specific behavior in the Microsoft Dynamics GP application. To disable events, use the Customization Status window in Microsoft Dynamics GP. To open this window, point to Customize in the Tools menu, and then choose Customization Status. Select the Microsoft Dynamics GP product, and then click Disable. Be sure to enable the events after you have completed your tests.

40

P R O G R A M M E R S

G U I D E

Chapter 10:

Modified and Alternate Forms

To access modified or alternate forms from a Visual Studio Tools for Microsoft Dynamics GP, a special process is used. This portion of the documentation describes the steps necessary. Information is divided into the following sections: Modified forms Alternate forms Guidelines

Modified forms
Modified forms contain modifications that have been made with the Modifier. To access these modifications from your Visual Studio Tools for Microsoft Dynamics GP project, complete the following procedure: 1. Create an application assembly for the forms dictionary. If the forms dictionary for the application that has been modified doesnt have an application assembly, create one using the process described in Chapter 5, Dictionary Assembly Generator. For example, the following command creates the application assembly for the forms dictionary of the core Dynamics GP 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 following illustration show the reference added for the application assembly that provides access to modified forms for the Dynamics GP core dictionary.

This reference to the application assembly provides access to the modified forms for the application.

3. Access the modified forms. Modified forms are accessed through an additional dictionary class that has the same name as the applications dictionary class, but with the additional phrase Modified. For instance, the dictionary class used to access modified forms for the Dynamics core application is: DynamicsModified

PROGRAMMERS

GUIDE

41

PA RT

D E V E L O PI N G

I N TE G R A T I O N S

The following C# code sets the value of a new field on the Credit Limit window of the Customer Maintenance form. The new field is a local field, added with the Modifier, and named Test.
DynamicsModified.Forms.RmCustomerMaintenance.RmCreditLimit.LocalTest.Value = "Modified Field";

When accessing resources that are defined in the main dictionary for an application, access them through the main dictionary class, rather than through the Modified class for the application.

Alternate forms
Alternate forms are forms from the core Dynamics dictionary that have been changed by a third-party developer, and are stored in a third-party dictionary. The new and changed resources for the alternate form are accessed through the thirdparty applications application assembly. To access alternate forms from you Visual Studio 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 doesnt already have an application assembly, create one using the process described in Chapter 5, Dictionary Assembly Generator. For example, the following command creates the application assembly 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 following illustration show the reference added for the application assembly that provides access to the alternate forms in the Sample Integrating App application.

This reference to the application assembly provides access to the alternate forms for the application.

3. Access the alternate forms. Alternate forms are accessed through the dictionary class for the assembly that contains them. For instance, the alternate forms in the Sample Integrating App application would be accessed through its dictionary class: SampleIntegratingApp

42

P R O G R A M M E R S

G U I D E

C H A P T E R

1 0

M O D IFI ED

A N D

AL T ER N AT E

F O R M S

The following C# code sets the value of a new field on the Vendor Maintenance window of the alternate version of the Vendor Maintenance form, which is part of the Sample Integrating App dictionary. The new field is a local field named Test.
SampleIntegratingApp.Forms.PmVendorMaintenance.PmVendorMaintenance. LocalTest.Value = "Alternate Field";

Guidelines
If you are planning to use Visual Studio Tools for Microsoft Dynamics GP to develop an integration for general distribution, we recommend that you limit the references to resources on modified or alternate forms. Because of security settings, a specific user may not have access to the modified or alternate version of a form, possibly causing errors in your integration. If you do distribute an integration which accesses modified or alternate forms, be sure that your code properly handles cases when these resources are not available. For instance, when you set or retrieve the value of a field, use a try...catch block to enclose the statements. This allows your code to catch any exceptions that are thrown because the field cannot be accessed. The following C# example shows how a field in window for an alternate version of the Vendor Maintenance form can be set within a try...catch block.
// 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); }

PROGRAMMERS

GUIDE

43

44

P R O G R A M M E R S

G U I D E

PART 3: RESOURCE REFERENCE

Part 3: Resource Reference

This portion of the documentation provides detailed information about each type of resource you can access with Visual Studio Tools for Microsoft Dynamics GP. Each resource has the following: 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.

46

P R O G R A M M E R S

G U I D E

Chapter 11:

Forms
Forms are the basic resource of the Microsoft Dynamics GP application. They provide the organization for the interface presented to the user. The following items for forms are discussed: Accessing forms Form methods Form properties Form events

Accessing forms
Forms for an application dictionary are accessed through the dictionary class. This class has a Forms property that provides access to the collection of forms in the dictionary. The dictionary class for the application dictionary is located in the following namespace: Microsoft.Dexterity.Applications For instance, to access the collection of forms in the Dynamics dictionary, use the following syntax: Microsoft.Dexterity.Applications.Dynamics.Forms To access a specific form, such as the Sales Transaction Entry form (SopEntry), use the following syntax: Microsoft.Dexterity.Applications.Dynamics.Forms.SopEntry

Form methods
Forms provide the following methods: AddMenuHandler() Close() Dispose() Open()

AddMenuHandler()
The AddMenuHandler() method adds a menu item to the Additional submenu that appears in the Extras menu in Microsoft Dynamics GP. The menu item will be available when the form is open. This method takes three parameters: EventHandler The function that will be run when the menu item is chosen in Microsoft Dynamics GP. MenuItemName A string containing the text that will be displayed for the menu item. AcceleratorKey A string containing a single character that will be used as the accelerator key for the menu item. Be sure this accelerator key does not conflict with any existing accelerator keys. If you dont want an accelerator key, use the empty string.

PROGRAMMERS

GUIDE

47

PA RT

R E S O U R C E

R E F E R E N C E

The following C# example shows how a menu handler for the Estimate Freight menu item is added to the SopEntry form in Microsoft Dynamics GP:
Dynamics.Forms.SOPEntry.AddMenuHandler(OpenEstimateFreight, "Estimate Freight", "F");

This code is the event handler for the menu item. Notice that it takes two arguments like standard event handlers.
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 longer needed.

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

Form properties
Forms provide the following properties: Commands Functions IsOpen Procedures

Commands
The Commands property provides access to the list of commands that are defined by the form. Refer to Chapter 15, Commands, to learn more about using commands in your application.

48

P R O G R A M M E R S

G U I D E

C H A PT E R

1 1

F O R M S

Functions
The Functions property provides access to the list of form-level functions that are defined by the form. Refer to Chapter 18, Functions, for more information about functions.

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

Procedures
The Procedures property provides access to the list for form-level procedures that are defined by the form. Refer to Chapter 17, Procedures, to learn more about using procedures.

Form events
Forms provide the following events: OpenBeforeOriginal OpenAfterOriginal CloseBeforeOriginal CloseAfterOriginal

OpenBeforeOriginal
This event occurs when the form is opened, but before the forms open event is run. This event can be canceled.

OpenAfterOriginal
This event occurs when the form is opened, but after the forms open event is run.

CloseBeforeOriginal
This event occurs when the form is closed, before the forms close event is run. This event can be canceled.

CloseAfterOriginal
This event occurs when the form is closed, after the forms close event is run.

PROGRAMMERS

GUIDE

49

50

P R O G R A M M E R S

G U I D E

Chapter 12:

Windows
Windows are a part of form in Microsoft Dynamics GP. They display the user interface for the application. The following items are discussed: Accessing windows Window methods Window properties Window events

Accessing windows
Windows for an application dictionary are accessed as properties of the form that they are contained in. For example, the Sales Transaction Entry window (SopEntry) is part of the SopEntry form. To access it, you would use the following syntax: Dynamics.Forms.SopEntry.SopEntry The IntelliSense in Visual Studio will tell you what form and window in Microsoft Dynamics GP are being referred to by the expression.

Window methods
Windows provide the following methods: Close() Open() PullFocus()

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

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

PullFocus()
The PullFocus() method will remove the focus from the current window. No item in the window will be focused. Any pending validate or leave events for the currently-focused field will be run. Use this method in situations where you want all of the pending actions to be run before your integrating application performs its processing.

Window properties
Windows provide the following property: IsOpen

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

PROGRAMMERS

GUIDE

51

PA RT

R E S O U R C E

R E F E R E N C E

Window events
Windows provide the following events: OpenBeforeOriginal OpenAfterOriginal ActivateBeforeOriginal ActivateAfterOriginal CloseBeforeOriginal CloseAfterOriginal PrintBeforeOriginal PrintAfterOriginal

OpenBeforeOriginal
This event occurs when the window is opened, but before the windows open event is run. This event can be canceled.

OpenAfterOriginal
This event occurs when the window is opened, but after the windows open event is run.

ActivateBeforeOriginal
This event occurs each time the window becomes active, before the windows activate event is run. The activate event occurs every time the window is opened or brought to the front by the user. It occurs after the Open event. The Activate event must be used cautiously. It shouldnt perform any actions that can cause dialogs to appear because the application can become suspended in an endless loop.

ActivateAfterOriginal
This event occurs each time the window becomes active, after the windows activate event is run.

CloseBeforeOriginal
This event occurs when the window is closed, but before the windows close event is run. This event can be canceled.

CloseAfterOriginal
This event occurs when the window is closed, but after the windows close event is run.

PrintBeforeOriginal
This event occurs when the print action for the window is chosen, but before the windows print event is run. The print action for a window occurs when the user chooses the Print menu item from the File menu, or clicks the Print button on the window. This event can be canceled.

PrintAfterOriginal
This event occurs when the print action for the window is chosen, but after the windows print event is run.

52

P R O G R A M M E R S

G U I D E

Chapter 13:

Scrolling Windows
Scrolling windows are a special type of window in Microsoft Dynamics GP that are used to display or access data directly from a database table. The following items are discussed: 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 the window that they are contained in. For example, the Line Scroll scrolling window in the Sales Transaction Entry window of Microsoft Dynamics GP is accessed using the following syntax: Dynamics.Forms.SopEntry.SopEntry.LineScroll The IntelliSense in Visual Studio will tell you what scrolling window in Microsoft Dynamics GP is being referred to by the expression.

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

LineEnterBeforeOriginal
This event occurs when the focus moves to a line in the scrolling window, but before the scrolling windows line enter event is run. This event can be canceled.

LineEnterAfterOriginal
This event occurs when the focus moves to a line in the scrolling window, but after the scrolling windows line enter event is run.

PROGRAMMERS

GUIDE

53

PA RT

R E S O U R C E

R E F E R E N C E

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

LineChangeAfterOriginal
This event occurs when the focus leaves a line in the scrolling window, and the contents of the line has been modified. The event runs after the scrolling windows line change event is run.

LineLeaveBeforeOriginal
This event occurs when the focus leaves a line in the scrolling window, but before the scrolling windows line leave event is run. This event can be canceled.

LineLeaveAfterOriginal
This event occurs when the focus leaves a line in the scrolling window, but after the scrolling windows line leave event is run.

LineInsertBeforeOriginal
This event occurs when a new line is added to the scrolling window, but before the scrolling windows line insert event is run. This event can be canceled.

LineInsertAfterOriginal
This event occurs when a new line is added to the scrolling window, but after the scrolling windows line insert event is run.

LineDeleteBeforeOriginal
This event occurs when a line is removed from the scrolling window, but before the scrolling windows line delete event is run. This event can be canceled.

LineDeleteAfterOriginal
This event occurs when a line is removed from the scrolling window, but after the scrolling windows line delete event is run.

54

P R O G R A M M E R S

G U I D E

Chapter 14:

Window Fields
Window fields display individual data items on a window. The following items are discussed: 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 the window or scrolling window that they are contained in. For example, the SOP Number (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 on the Line Scroll (LineScroll) scrolling window of the Sales Transaction Entry window(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 being referred to by the expression. Some fields in windows are called local fields, because they are used only within a specific form. For instance, the Sales Transaction Entry window (SopEntry) contains a local field named (L) BillTo Address 1. The (L) in the name is the standard way local fields are identified in Microsoft Dynamics GP. In a Visual Studio Tools for Microsoft Dynamics GP project, the names of these fields are prefixed with the Local to indicate they are local fields. For example, to access the BillTo Address 1 local field, you would use the following syntax: Dynamics.Forms.SopEntry.SopEntry.LocalBillToAddress1

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 the user from making changes to the field.

PROGRAMMERS

GUIDE

55

PA RT

R E S O U R C E

R E F E R E N C E

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 when the focus leaves the field. If the validate event occurs, any validation code for the field will be run. This method takes one boolean parameter. Supplying the value true forces the validate event to occur. Supplying the value false clears any previous call to force the validate event to occur.

Hide()
The Hide() method causes the field to become invisible and inaccessible to the user.

Lock()
The Lock() method causes a field to become inaccessible to the user. The fields appearance will not change.

RunValidate()
The RunValidate() method causes any validation code for the window field to be run.

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

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

Window field properties

Window fields have the following property: Value

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

Window field events

Window fields provide the following events: Change EnterBeforeOriginal EnterAfterOriginal LeaveBeforeOriginal LeaveAfterOriginal ValidateBeforeOriginal ValidateAfterOriginal

56

P R O G R A M M E R S

G U I D E

C H A P T E R

1 4

W I N D O W

F I E L D S

Change
This event occurs when the value of the field changes, such as being set by the user or changed by other code in Microsoft Dynamics GP.

EnterBeforeOriginal
This event occurs when the focus moves to the field, but before the fields enter event is run. This event can be canceled.

EnterAfterOriginal
This event occurs when the focus moves to the field, but after the fields enter event is run.

LeaveBeforeOriginal
This event occurs when the focus moves from the field, but before the fields leave event is run. This event can be canceled.

LeaveAfterOriginal
This event occurs when the focus moves from the field, but after the fields leave event is run.

ValidateBeforeOriginal
This event occurs when the focus is to move from the field, and the field has been set to be validated. A field will be validated when its value has been changed, or the validation has been forced, such as with the ForceValidate() method. This event occurs before the fields validate event. It can be canceled.

ValidateAfterOriginal
This event occurs when the focus is to move from the field, and the field has been set to be validated. This event occurs after the fields validate event.

PROGRAMMERS

GUIDE

57

58

P R O G R A M M E R S

G U I D E

Chapter 15:

Commands
In Microsoft Dynamics GP, commands are used to encapsulate a small piece of functionality for the application. They are typically used for navigation. Commands can appear in menus and also in toolbars in Microsoft Dynamics GP. The following items are discussed: Command types Accessing commands Command methods

Command types
A command can be one of the following types: 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. A command list can be used as a menu, submenu, or a toolbar.

Accessing commands
Commands for an application dictionary are accessed using the Commands property of the form that they are contained in. Most commands in Microsoft Dynamics GP are contained in forms that are used specifically for commands. The names of these forms begin with Command and include the module for which the commands are used. For example, to access the command used to open the SmartList window in Microsoft Dynamics GP, you would use the following syntax: Dynamics.Forms.CommandSystem.Commands.SmartList The IntelliSense in Visual Studio will tell you what command in Microsoft Dynamics GP is being referred to by the expression.

Command methods
Commands provide the following methods: Check() Disable() Enable() Hide() Run() Show() Uncheck()

Check()
The Check() method causes the command to appear checked if it is displayed in a menu or on a toolbar.

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

PROGRAMMERS

GUIDE

59

PA RT

R E S O U R C E

R E F E R E N C E

Enable()
The Enable() method causes a previously disabled command to become enabled. It will appear enabled if it is displayed in a menu or on a toolbar.

Hide()
The Hide() method causes a command to be hidden in any menu or toolbar in which it appears. The command can still be run.

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

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

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

60

P R O G R A M M E R S

G U I D E

Chapter 16:

Globals
Globals are used to hold values accessible to the entire Microsoft Dynamics GP application. The following items are discussed: Accessing globals Global properties

Accessing globals
Globals for an application dictionary are accessed through the dictionary class. This class has a Globals property that provides access to the collection of globals in the dictionary. The dictionary class for the application dictionary is located in the following namespace: Microsoft.Dexterity.Applications For instance, to access the collection of globals in the Dynamics dictionary, use the following syntax: Microsoft.Dexterity.Applications.Dynamics.Globals To access a specific global value, such as the current users ID (UserId), use the following syntax: Microsoft.Dexterity.Applications.Dynamics.Globals.UserId

Global properties
Globals have the following property available: Value

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

PROGRAMMERS

GUIDE

61

62

P R O G R A M M E R S

G U I D E

Chapter 17:

Procedures
There are two types of procedures in a Dynamics GP application dictionary. Global procedures are blocks of code that are accessed from various places throughout the application. Parameters are used to send values to a procedure and also to return values from it. Form-level procedures are like global procedures, with the exception that they are defined as part of a specific form. Typically, they perform some action specific to the form they are defined for. The following items are discussed: Accessing global procedures Accessing form-level procedures Procedure methods Invokable procedures

Accessing global procedures

Global procedures for an application dictionary are accessed through the dictionary class. This class has a Procedures property that provides access to the collection of global procedures in the dictionary. The dictionary class for the application dictionary is located in the following namespace: Microsoft.Dexterity.Applications For instance, to access the collection of global procedures in the Dynamics dictionary, use the following syntax: Microsoft.Dexterity.Applications.Dynamics.Procedures To access a specific global procedure, such as the Get_Next_Form_Note_To_Open procedure (GetNextFormNoteToOpen), use the syntax shown below. (This example assumes the namespace mentioned above has been referenced.) Dynamics.Procedures.GetNextFormNoteToOpen The IntelliSense in Visual Studio will tell you what global procedure in Microsoft Dynamics GP is being referred to by the expression.

Accessing form-level procedures

Form-level procedures for an application dictionary are accessed through the form they are contained in. The Procedures property for the form allows access to the form-level procedures. For example, to access the form-level procedures for Sales Transaction Entry Form (SopEntryForm) in Microsoft Dynamics GP, you would use the following syntax: Dynamics.Forms.SopEntry.Procedures The IntelliSense in Visual Studio will tell you what form-level procedure in Microsoft Dynamics GP is being referred to by the expression.

Procedure methods
Procedures provide the following method: Invoke()

PROGRAMMERS

GUIDE

63

PA RT

R E S O U R C E

R E F E R E N C E

Invoke()
The Invoke() method is used to run the specified procedure. The parameters for this method will depend on the procedure that is being run. The following table lists the types of parameters for procedures:
Type
in out inout

Description
Parameters of type in are used only to pass values into the procedure. Parameters of type out are used only to pass values out of the procedure. Parameters of type inout are used to pass values into the procedure, and to pass values out of the procedure.

The IntelliSense in Visual Studio will tell you the type of each parameter for a procedure. It will also tell you the datatype of each parameter, such as decimal or string. For example, the following C# code calls the CheckNoteIdString global procedure. This procedure has one in parameter and two out parameters. Notice that the out keyword is required for the parameters to which values are returned.
Dynamics.Procedures.CheckNoteIdString.Invoke("Estimate Freight", out isPresent, out formNumber);

Invokable procedures
With this release of Visual Studio Tools for Microsoft Dynamics GP, not all procedures can be invoked. Procedures with the following characteristics cannot be invoked: The procedure uses table buffers as parameters. Table buffers are a feature of the Dynamics GP runtime engine, and are used when accessing data in the database. The procedure uses anonymous parameters. These parameter types arent known at the time the application is compiled. The procedure uses reference parameters. These parameter types contain a link 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 be included in the procedure lists displayed by the IntelliSense in Visual Studio.

64

P R O G R A M M E R S

G U I D E

Chapter 18:

Functions
There are two types of functions in a Dynamics GP application dictionary. Global functions are blocks of code that are accessed from various places throughout the application. Parameters are used to send values to a function and also to return values from it. In addition, functions always return a value. Form-level functions are like global functions, with the exception that they are defined as part of a specific form. Typically, they perform some action specific to the form they are defined for. The following items are discussed: Accessing global functions Accessing form-level functions Function methods Invokable functions

Accessing global functions

Global functions for an application dictionary are accessed through the dictionary class. This class has a Functions property that provides access to the collection of global functions in the dictionary. The dictionary class for the application dictionary is located in the following namespace: Microsoft.Dexterity.Applications For instance, to access the collection of 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 example assumes the namespace mentioned above has been referenced.) Dynamics.Functions.GetCurrentDirectory The IntelliSense in Visual Studio will tell you what global function in Microsoft Dynamics GP is being referred to by the expression.

Accessing form-level functions

Form-level functions for an application dictionary are accessed through the form they are contained in. The Functions property for the form allows access to the form-level functions. For example, to access the form-level functions for Sales Transaction Entry Form (SopEntryForm) in Microsoft Dynamics GP, you would use the following syntax: Dynamics.Forms.SopEntry.Functions The IntelliSense in Visual Studio will tell you what form-level function in Microsoft Dynamics GP is being referred to by the expression.

PROGRAMMERS

GUIDE

65

PA RT

R E S O U R C E

R E F E R E N C E

Function methods
Functions provide the following method: Invoke()

Invoke()
The Invoke() method is used to run the specified function. The parameters for this method will depend on the procedure that is being run. The following table lists the types of parameters for functions:
Type
in out inout

Description
Parameters of type in are used only to pass values into the function. Parameters of type out are used only to pass values out of the function. Parameters of type inout are used to pass values into the function, and to pass values out of the function.

The Invoke() method will have a return value to which the return value of the function will be returned. The IntelliSense in Visual Studio will tell you the type of each parameter and the return value for a function. It will also tell you the datatype of each parameter and the return value, such as decimal or string. For example, the following C# code calls the GetCurrentDirectory global function. This procedure has no parameters and returns a string value.
string currentDirectory; currentDirectory = Dynamics.Functions.GetCurrentDirectory.Invoke();

Invokable functions
With this release of Visual Studio Tools for Microsoft Dynamics GP, not all functions can be invoked. Functions with the following characteristics cannot be invoked: The function uses table buffers as parameters. Table buffers are a feature of the Dynamics GP runtime engine, and are used when accessing data in the database. The function uses anonymous parameters. These parameter types arent known at the time the application is compiled. The function uses reference parameters. These parameter types contain a link to a specific resource in the application dictionary. If a composite field used as a function parameter contains a reference value, that function cannot be invoked.

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

66

P R O G R A M M E R S

G U I D E

PART 4: INTEGRATION EXAMPLES

Part 4: Integration Examples

This portion of the documentation describes integration examples that show how to use Visual Studio Tools for Microsoft Dynamics GP. The following examples are discussed: Chapter 19, Field Defaulter, describes an example that uses events to default field values in Microsoft Dynamics GP. Chapter 20, Estimate Freight, describes an example that estimates freight amounts for sales documents in Microsoft Dynamics GP.

68

P R O G R A M M E R S

G U I D E

Chapter 19:

Field Defaulter
This sample application, written in C#, demonstrates how events in Microsoft Dynamics GP can be used to default field values. The sample defaults the City and State fields when a user enters a value for the ZIP code field in the Customer Maintenance window. The following topics are discussed: Overview Running the sample application How Visual Studio Tools was used

Overview
This sample C# application integrates with the Customer Maintenance window in Microsoft Dynamics GP. It automatically defaults values for the City and State fields when the user supplies a known ZIP Code.

The City and State fields are set based on the ZIP Code value entered.

This sample uses a fixed set of ZIP Codes and correspond City and State values. An actual 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 located in the FieldDefaulter folder inside the Samples folder for Visual Studio Tools for Microsoft Dynamics GP. 2. Verify the references for the sample solution. Use the Solution Explorer to view the references for the project. The Estimate Freight 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 the application. 4. Build the application. From the Build menu, choose Build Solution. If there are no build errors, the assembly for the Field Defaulter application will be built.

PROGRAMMERS

GUIDE

69

PA RT

IN T E G R A TI O N

E XA M P LE S

5. Install the Field Defaulter assembly. Copy the FieldDefaulter.dll from the Release folder for the project to the AddIns folder 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 small number of ZIP codes. You can enter any of the follow ZIP codes and have the corresponding City and State filled in:
02109 53151 55111 56560 58078 58102 58103 58104 58474 60605 85012 95014 98052

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 Visual Studio Tools for Microsoft Dynamics GP.

Resources accessed
The Field Defaulter sample uses the following resources in the Dynamics dictionary:

Forms
RmCustomerMaintenance

Windows
RmCustomerMaintenance

Events
The Field Defaulter sample registers the following event in Microsoft Dynamics GP: A change event for the ZipCode field in the Customer Maintenance window, used to look up the value entered. If the city and state can be found for the ZIP code value entered, their value are automatically set in the window.

70

P R O G R A M M E R S

G U I D E

Chapter 20:

Estimate Freight
This sample application, written in C#, demonstrates several techniques useful when creating Microsoft Dynamics GP integrations. The sample integrates with the Sales Transaction Entry window. The following topics are discussed: Overview Running the sample application How Visual Studio Tools was used

Overview
This sample C# application integrates with the Sales Transaction Entry window in Microsoft Dynamics GP. It retrieves shipping weight information about the items in the current sales document, calculates an estimated shipping weight for all of the items, and then estimates the freight cost. The estimated freight value is placed into the Freight field of the Sales Transaction Entry window.

The Estimate Freight window estimates freight for the current sales document.

This sample uses a fixed set of shipping methods and shipping rates. An actual application would use a more extensive rate table, and possibly a web service to access freight rates. The Estimate Freight sample uses the GPConnNet.dll to establish a connection to the SQL database. It uses SQL statements to retrieve the data needed for the freight calculations.

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 is located in the EstimateFreight folder inside the Samples folder for Visual Studio Tools for Microsoft Dynamics GP. 2. Verify the references for the sample solution. Use the Solution Explorer to view the references for the project. The Estimate Freight 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.

PROGRAMMERS

GUIDE

71

PA RT

IN T E G R A TI O N

E XA M P LE S

3. Set the Solution Configuration. Set the Solution Configuration to Release to build the release version of the application. 4. Build the application. From the Build menu, choose Build Solution. If there are no build errors, the assembly 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 the AddIns 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 the Dynamics GP installation folder. The help file should be placed in the same folder 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 estimated shipping weight has been specified. 11. Display the Estimate Freight window. In the Extras menu, point to Additional, and choose Estimate Freight. The Estimate 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 Calculate to 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 the sales document.

How Visual Studio Tools was used

This sample application uses several features of Visual Studio Tools for Microsoft Dynamics GP to implement this integration.

User interface
The special WinForm available for Dynamics GP add-ins was used when creating the Estimate Freight window. The customized buttons and images were also used. The sample illustrates technique that can be used to implement window-level notes and the online help link.

72

P R O G R A M M E R S

G U I D E

C H A P T E R

2 0

E S T IM AT E

FR EI G HT

Resources accessed
The Estimate Freight sample uses many resources in the Dynamics dictionary:

Forms
SOPEntry FormNote1 FormNote2 FormNote3 FormNote4 FormNote5

Windows
SOPEntry

Globals
IntercompanyId SqlDataSourceName UserId SqlPassword

Global procedures
CheckForNote CheckNoteIdString GetNextFormNoteToOpen

Events
The Estimate Freight sample registers the following events in Microsoft Dynamics GP: A menu handler event for the Sales Transaction Entry form, used to open the Estimate Freight window. A form close event on the Sales Transaction Entry form, used to indicate when the Sales Transaction Entry window has been closed. A watch event for the SOP Number field in the Sales Transaction Entry window, used to keep the Estimate Freight window updated with the current sales document. An enter event for the Freight field in the Sales Transaction Entry window, used to ask the user whether they want to estimate the freight amount if a value hasnt been supplied. Several form close events for the various Note forms in Microsoft Dynamics GP, used to keep the Note button on the Estimate Freight window updated.

PROGRAMMERS

GUIDE

73

74

P R O G R A M M E R S

G U I D E

Glossary
Alternate forms
Forms from the core Dynamics dictionary that have been changed by a third-party developer, and are stored in a third-party dictionary.

Application assembly
A .NET assembly used by Visual Studio Tools to provide access to the resources in Microsoft Dynamics GP dictionary. Each application dictionary can have one corresponding application assembly.

Control area
A band drawn at the top of a Microsoft Dynamics GP window. Controls such as Save, Clear, and Delete buttons are placed in the control area.

Dictionary Assembly Generator

The tool (DAG.exe) used to build application assemblies for dictionaries.

Dexterity Bridge assembly

The assembly Microsoft.Dexterity.Bridge.dll that provides the access to events in Microsoft Dynamics GP, as well as the resources in the application dictionaries.

Dictionary class
A class used to reference the resources in an application dictionary. The class is available after a reference to the application assembly for a dictionary has been added to the Visual Studio project.

Dexterity Shell assembly

The assembly Microsoft.Dexterity.Shell. UI.dll that provides the drawing capabilities that allow an integrating application to match the appearance of Microsoft Dynamics GP

Forms dictionary
The dictionary in a Microsoft Dynamics GP installation that contains the modified forms for an application. Each application dictionary can have a forms dictionary.

Local fields
Special fields that are defined for and used only within a specific form in Microsoft Dynamics GP.

Modified forms
Forms in the Microsoft Dynamics GP application that contain modifications made with the Modifier.

Status area
An area at the bottom of a Microsoft Dynamics GP window created by a divider line drawn across the window. Controls like browse buttons, note buttons, and help buttons are placed in the status area.

PROGRAMMERS

GUIDE

75

76

P R O G R A M M E R S

G U I D E

Index
A
Accessing Dictionary Resources, chapter 27-30 ActivateAfterOriginal, window event 52 ActivateBeforeOriginal, window event 52 AddIns folder, described 10 AddMenuHandler(), form method 47 alternate forms accessing with code 42 creating application assembly for 42 defined 75 guidelines for accessing 43 using try...catch with 43 application assemblies creating 23 defined 75 described 10 naming convention 23 references to 27 shipped with Visual Studio Tools 10 signing 25 which to use 23 architecture, for Visual Studio Tools 9 assembly information, for integrations 35 AutoSetDexColors control property 19 WinForms property 16

combo box controls, described 22 command-line, for Dictionary Assembly Generator 24 Commands, form property 48 commands accessing through code 59 chapter 59-60 command list commands 59 form commands 59 methods for 59 resource reference 59 script commands 59 types of 59 control area defined 75 described 16 Control Reference, chapter 19-22 ControlArea, WinForms property 16 controls adding to forms 17 buttons 19 combo boxes 22 control reference 19 labels 22 list boxes 22 text boxes 21 conventions, in documentation 3 Customization Status window 40

dictionary class defined 75 examples 28 for alternate forms 42 for modified forms 41 resource types to access 28 using to access dictionary resources 28 dictionary resources accessing 27 accessing through dictionary class 28 additional resources 29 list of 46 lists in IntelliSense 28 namespace for accessing 28, 29 variable for 29 working with 46 Disable() command method 59 window field method 55 disabling events 40 Dispose(), form method 48 documentation, symbols and conventions 3 Dynamics.exe, application process when debugging 39

E
Enable() command method 60 window field method 56 EnterAfterOriginal, window field event 57 EnterBeforeOriginal, window field event 57 Estimate Freight overview 71 running 71 sample integration 71 use of Visual Studio Tools 72 events cancelling events 33 chapter 31-33 disabling 40 overview 31 registering 31 registering with C# code 31 registering with Visual Basic code 32 responding to 33 exceptions example 43 handling for modified and alternate forms 43 Extras menu, adding items to 47

D
DAG.exe, see Dictionary Assembly Generator Debug, solution configuration 36 debugging attaching to a process 39 chapter 39-40 examining application 40 integrations 39 preparations for 39 deploying integrations 37 Developing Integrations, part 14-43 Dexterity Bridge assembly defined 75 described 9 Dexterity Shell assembly defined 75 described 9 Dictionary Assembly Generator application assembly 23 chapter 23-26 commands for 24 creating application assemblies 23 defined 75 described 10, 23 IntelliSense data file 24 launch file used 25 optimizing processing 26 output from 23 using 24 when to use 23 where installed 24

B
Building and Deploying, chapter 35-37 building integrations 36 buttons field 20 pictures for 20 standard 19 status area 20 toolbar 19 toolbar with separator 20 types of 19 ButtonType property, for button controls 19

C
C# registering events 31 setting assembly information 35 cancelling events 33 Change, window field event 57 Check(), command method 59 Close() form method 48 window method 51 CloseAfterOriginal form event 49 window event 52 CloseBeforeOriginal form event 49 window event 52

F
field, buttons 20 Field Defaulter overview 69 sample integration 69 use of Visual Studio Tools 70 focus, removing from current window 51

PROGRAMMERS

GUIDE

77

IN DEX

Focus(), window field method 56 ForceValidate(), window field method 56 form-level functions accessing through code 65 described 65 form-level procedures accessing through code 63 described 63 forms accessing through code 47 chapter 47-49 events for 49 methods for 47 properties for 48 resource reference 47 forms dictionaries application assemblies for 23 application assembly for 41 defined 75 generating application assembly for 25 Functions, form property 49 functions chapter 65-66 invokable procedures 66 methods for 66 parameter types 66 resource reference 65 return value 66

integrations (continued) setting assembly information 35 IntelliSense XML files described 10 generating 24 installing 8 naming convention 24 Invoke() function method 66 procedure method 64 IsOpen form property 49 window property 51

menus, adding to Extras menu 47 Microsoft Dynamics GP, events in 31 Microsoft Dynamics GP SDK, installing 2 Modified and Alternate Forms, chapter 41-43 modified forms accessing with code 41 creating application assembly for 41 defined 75 guidelines for accessing 43 using try...catch with 43 using with Visual Studio Tools 41

L
label controls described 22 linked field 22 launch file, used by Dictionary Assembly Generator 25 LeaveAfterOriginal, window field event 57 LeaveBeforeOriginal, window field event 57 light bulb symbol 3 LineChangeAfterOriginal, scrolling window event 54 LineChangeBeforeOriginal, scrolling window event 54 LineDeleteAfterOriginal, scrolling window event 54 LineDeleteBeforeOriginal, scrolling window event 54 LineEnterAfterOriginal, scrolling window event 53 LineEnterBeforeOriginal, scrolling window event 53 LineInsertAfterOriginal, scrolling window event 54 LineInsertBeforeOriginal, scrolling window event 54 LineLeaveAfterOriginal, scrolling window event 54 LineLeaveBeforeOriginal, scrolling window event 54 LinkField property, for label controls 22 list box controls, described 22 local fields accessing 55 defined 75 described 55 naming convention for 55 Lock(), window field method 56

N
namespace, for accessing dictionary resources 28, 29

O
Open() form method 48 window method 51 OpenAfterOriginal form event 49 window event 52 OpenBeforeOriginal form event 49 window event 52 optimizing, application assembly generation 26

G
Getting Started, part 6-11 global functions accessing through code 65 described 65 global procedures accessing through code 63 described 63 globals accessing through code 61 chapter 61 properties for 61 resource reference 61

P
prerequisites, for using Visual Studio Tools for Microsoft Dynamics GP 2 PrintAfterOriginal, wndow event 52 PrintBeforeOriginal, window event 52 Procedures, form property 49 procedures chapter 63-64 invokable procedures 64 methods for 63 parameter types 64 resource reference 63 process, attaching to Dynamics.exe for debugging 39 product support, for Visual Studio Tools for Microsoft Dynamics GP 3 projects adding a Dynamics GP form to 15 creating for Visual Studio Tools 10 PullFocus(), window method 51

H
Hide() command method 60 window field method 56

I
Initialize() method, for registering events 31 installation chapter 7-8 Visual Studio Tools runtime 7 Visual Studio Tools SDK 7 Integration Basics, chapter 9-11 Integration Examples, part 68-73 integrations building 36 debugging 39 deploying 37

R
references, to application assemblies 27, 41, 42 registering events 31 Release, solution configuration 36 Resource Reference, part 46-66 resources, see dictionary resources responding to events 33 Run(), command method 60 runtime components, for Visual Studio Tools 9

M
main dictionary, generating application assembly for 25 maintenance mode to install application assemblies 7 to install IntelliSense XML files 8 margin notes 3

78

P R O G R A M M E R S

G U I D E

I N D E X

RunValidate(), window field method 56

S
sample integrations Estimate Freight 71 Field Defaulter 69 scrolling windows accessing through code 53 chapter 53-54 described 53 events for 53 resource reference 53 SDK, for Microsoft Dynamics GP 2 Show() command method 60 window field method 56 signing, application assemblies 25 SN.exe, described 25 solution configuration, for a Visual Studio project 36 standard buttons 19 status area buttons 20 defined 75 described 16 StatusArea, WinForms property 16 strong name key file, described 25 strong names, for application assemblies 25 support, for Visual Studio Tools for Microsoft Dynamics GP 3 symbols in documentation 3

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

W
warning symbol 3 window fields accessing through code 55 chapter 55-57 events for 56 methods for 55 properties for 56 resource reference 55 windows accessing through code 51 chapter 51-52 events for 52 local fields 55 methods for 51 properties for 51 resource reference 51 WinForms adding controls to 17 adding to a project 15 chapter 15-17 properties for 16

T
technical support, for Visual Studio Tools for Microsoft Dynamics GP 3 text box controls 21 third-party applications, application assemblies for 23 toolbar, button type 19 toolbar with separator, button type 20 try...catch, using with modified and alternate forms 43

X
XML files, for IntelliSense 10

U
Uncheck(), command method 60 Unlock(), window field method 56 user interface, for Visual Studio Tools projects 15

V
ValidateAfterOriginal, window field event 57 ValidateBeforeOriginal, window field event 57 Value global property 61 window field property 56 variables, for dictionary resources 29 Visual Basic registering events 32 setting assembly information 36

PROGRAMMERS

GUIDE

79