Seamless Upgrade: Migrating Applications to GPConn.dll in Microsoft Dynamics GP

Table of Contents

This article provides a comprehensive guide on upgrading existing applications designed for Microsoft Dynamics GP to utilize the GPConn.dll or GPConnNet.dll components. These newer components are essential replacements for the legacy Crypto.dll file, which was used in earlier iterations of Microsoft Great Plains. Understanding this migration is critical for maintaining compatibility and functionality with modern versions of Microsoft Dynamics GP.

Applications that have been in use for some time, especially those developed for versions of Microsoft Great Plains prior to version 9.0, likely rely on the Crypto.dll file for specific functionalities, particularly related to secure operations like password handling or establishing database connections based on Dynamics GP user credentials. The architecture and security models of Microsoft Dynamics GP underwent significant changes starting with version 9.0, including modifications to password policies. These changes rendered the Crypto.dll file incompatible and potentially insecure for use with newer versions of the software.

The necessity for this migration stems directly from the enhancements introduced in Microsoft Dynamics GP 9.0 and subsequent versions, such as version 10.0. The updated password policy specifically impacts how Dexterity, the development environment for Dynamics GP, handles user authentication and security. Consequently, any external application or integration built using Dexterity or other development tools that previously interfaced with GP using Crypto.dll must be updated to align with the new security framework. Therefore, replacing code that references Crypto.dll with calls to either the GPConn.dll or GPConnNet.dll is a mandatory step for ensuring continued operation.

Understanding GPConn.dll and GPConnNet.dll¶

To facilitate integrating applications that require the ability to connect to the SQL database using the logon credentials of Microsoft Dynamics GP users, Microsoft introduced two new components: GPConn.dll and GPConnNet.dll. These libraries serve as secure gateways, allowing external applications to authenticate against the Dynamics GP security model and obtain a valid database connection without bypassing the standard Dynamics GP logon procedures. They abstract the complexities of the updated authentication mechanism.

The GPConn.dll component is designed to provide compatibility with traditional Windows development environments, offering both COM and Win32 interfaces. This makes it suitable for applications developed using languages or platforms that interact well with these technologies, such as older versions of Visual Basic, C++, or scripting languages that can utilize COM objects. Its primary function is to establish a database connection given the necessary GP user credentials and system information.

In parallel, the GPConnNet.dll component caters to modern development paradigms, specifically providing a Microsoft .NET interface. This library is the preferred choice for applications built using .NET languages like C#, VB.NET, or F#. It allows developers to leverage the power and features of the .NET framework while securely connecting to the Dynamics GP database. Both GPConn.dll and GPConnNet.dll require that specific registration keys be passed into them during initialization or connection attempts.

The requirement for registration keys is a crucial security measure. These keys are unique identifiers generated for your specific organization or implementation. They act as a license or validation token, ensuring that only authorized applications and installations can utilize these connection components. Because these keys are unique and tied to your organization’s licensing, they cannot be freely distributed or obtained without following a specific process. Obtaining these keys, along with the necessary DLL files and documentation, involves contacting Microsoft Support.

Microsoft has established a process for obtaining these essential components and their corresponding keys. You are required to open a Dexterity support incident specifically to request the keys for GPConn.dll or GPConnNet.dll, depending on your development needs. It is important to note that for the initial support incident opened solely for the purpose of requesting these keys, you will typically not be charged. However, any subsequent support incidents that involve detailed assistance on how to implement or troubleshoot your specific solution using these DLLs may incur standard support charges. Along with the keys, you will also receive the relevant documentation for the .dll file(s) you requested, which is invaluable for the migration process.

A Note on VBA and Integration Manager¶

For specific scenarios, particularly when you are working within Visual Basic for Applications (VBA) or using VBScript within Integration Manager, there is often a more direct and recommended path than implementing GPConn.dll or GPConnNet.dll from scratch. Microsoft provides an alternative component, RetrieveGlobals9.dll, which is specifically designed to handle obtaining global information, including connection details, within these environments.

If your application or script using Crypto.dll is primarily embedded within or interacts with VBA in Dynamics GP or VBScript in Integration Manager, the best integration option is often to utilize the RetrieveGlobals9.dll file. This file is typically available for download from Microsoft’s resources related to Mod/VBA samples. In these specific situations, it is strongly recommended that you download and implement the updated RetrieveGlobals9.dll file instead of going through the process of requesting keys and documentation for GPConn.dll or GPConnNet.dll. RetrieveGlobals9.dll is tailored for these scripting contexts and can simplify the process of obtaining necessary connection information derived from the currently logged-in GP user’s session.

The Migration Process: From Crypto.dll to GPConn/GPConnNet¶

Migrating an application from using the legacy Crypto.dll to the newer GPConn.dll or GPConnNet.dll is a technical process that requires careful planning and execution. It involves several key phases, from initial assessment to deployment and testing. This section outlines the typical steps involved in this transition.

Phase 1: Assessment and Planning¶

The first step in the migration process is to thoroughly assess the application(s) currently relying on Crypto.dll. Identify all instances where Crypto.dll is called or referenced in the code. Understand the specific functionalities that Crypto.dll was performing – was it for password encryption/decryption (less likely for database connection purposes in this context, but possible), or more likely, for obtaining database connection parameters or authenticating a user against GP credentials? Determine the development platform (e.g., .NET, COM-based language, scripting) used to build the application, as this will dictate whether you need GPConn.dll (COM/Win32) or GPConnNet.dll (.NET).

Based on this assessment, define the scope of the changes required. Plan which parts of the code need to be rewritten or modified. Estimate the effort involved and allocate resources. Crucially, determine which version of Dynamics GP the application needs to be compatible with (version 9.0 or later) and ensure your development environment is set up correctly for this target version.

Phase 2: Obtaining Necessary Components and Keys¶

As discussed earlier, the next critical step is to obtain the appropriate DLL file(s) (GPConn.dll or GPConnNet.dll) and the required registration keys from Microsoft. This involves opening a support incident with Microsoft Dynamics GP support, specifically requesting these components and keys for your organization. Be prepared to provide details about your Dynamics GP installation and licensing.

Ensure you receive the correct DLL file based on your development platform (.NET vs. COM/Win32) and the associated registration keys. Pay close attention to any instructions provided by Microsoft regarding the use and distribution of these keys, as they are sensitive and specific to your license. Also, request and review the documentation provided for the specific DLL you will be using; it will contain vital information on how to properly initialize the component, pass credentials, and handle the resulting database connection object.

Phase 3: Code Modification¶

This phase involves the actual rewriting of the code. You will need to locate the existing code that makes calls to functions within Crypto.dll and replace it with code that interacts with the chosen new DLL (GPConn.dll or GPConnNet.dll).

The process will generally involve:
1. Referencing the New DLL: Add a reference to GPConn.dll (for COM/Win32 projects) or GPConnNet.dll (for .NET projects) in your development project.
2. Initializing the Component: The new DLLs will likely require some form of initialization, potentially involving passing the registration keys obtained from Microsoft. Consult the documentation for the exact method signature and required parameters.
3. Establishing Connection: Replace the logic that previously used Crypto.dll to get connection information or authenticate. The new code will call a specific method within GPConn.dll or GPConnNet.dll, passing the Dynamics GP user ID, password, and potentially other parameters like server name or database name.
4. Handling the Connection Object: The new DLL method will typically return a database connection object or a string (like a standard ADO.NET connection string) that can be used by your application to interact with the SQL database. Update your code to use this new connection object or string format.
5. Implementing Error Handling: Add robust error handling around calls to the new DLLs. Connection failures, invalid credentials, or issues with registration keys should be caught and handled gracefully, providing informative feedback to the user or logging errors for debugging.
6. Removing Crypto.dll References: Ensure all original references to Crypto.dll in the code and project settings are removed to prevent conflicts or reliance on the deprecated component.

Phase 4: Testing¶

Thorough testing is paramount after code modification. Deploy the updated application to a non-production environment that mirrors your production setup (same Dynamics GP version, SQL Server version, operating system).

Test the application extensively under various scenarios:
* Successful Connections: Verify that users can successfully connect using valid Dynamics GP credentials.
* Failed Connections: Test with incorrect user IDs, passwords, or other invalid parameters to ensure the error handling works correctly.
* Different Users: Test with users having different security roles and permissions within Dynamics GP to ensure the application respects these permissions when interacting with the database via the new connection.
* High Load: If applicable, test the application under concurrent usage to assess performance and stability.
* All Functionality: Verify that all features of the application that rely on the database connection obtained via the new DLL are functioning as expected.

Phase 5: Deployment¶

Once testing is complete and successful, plan and execute the deployment of the updated application to your production environment. This may involve installing the new version of your application, ensuring the GPConn.dll or GPConnNet.dll file is present and correctly registered on the client machines or server where the application runs, and potentially configuring any necessary paths or settings.

Coordinate the deployment with your IT team and Dynamics GP administrators. Consider a phased rollout if possible, especially for mission-critical applications, to minimize disruption. Ensure rollback procedures are in place in case unforeseen issues arise during or after deployment.

Key Considerations and Best Practices¶

Migrating connection methods is a critical change. Keeping the following considerations and best practices in mind can help ensure a smoother transition:

• Security: While the GPConn.dll and GPConnNet.dll take credentials in plain text during the method call (as per the original text), they are designed to integrate with GP’s updated security model. Ensure that the credentials are handled securely before they are passed to the DLL methods. Avoid hardcoding credentials, use secure input methods, and manage user access to the application appropriately. The primary benefit of these DLLs is leveraging the GP user context, not necessarily encrypting the credentials passed into the DLL call itself.
• Performance: Monitor the performance of the updated application after migration. While the new DLLs are generally efficient, connection overhead or changes in how queries are executed via the new connection object could potentially impact performance. Optimize database interactions if necessary.
• Compatibility: Always ensure that the specific versions of GPConn.dll or GPConnNet.dll you obtain are compatible with the version of Microsoft Dynamics GP you are using. Also, for GPConnNet.dll, verify compatibility with the .NET Framework version your application targets.
• Error Handling: As mentioned in the migration steps, robust error handling is crucial. Log detailed error information to aid in troubleshooting. Provide clear, user-friendly messages when possible, but ensure technical details are captured for support.
• Documentation: Document all changes made during the migration. Record which DLL was implemented (GPConn.dll or GPConnNet.dll), how it is initialized, how connections are established, and any specific configuration or requirements. This documentation will be invaluable for future maintenance, updates, or troubleshooting.
• Environment Consistency: Maintain consistency between your development, testing, and production environments regarding Dynamics GP version, SQL Server, and any relevant system configurations. Discrepancies can lead to unexpected issues during testing or deployment.
• Leverage Documentation: The documentation provided by Microsoft with the DLLs is your primary resource. Spend time understanding the methods, parameters, and any specific requirements or limitations described.
• Community Resources: Engage with the Microsoft Dynamics GP community forums, blogs, and user groups. Other developers have likely gone through this migration and may share valuable insights, tips, or troubleshooting advice.

Support Resources¶

Microsoft provides support channels to assist with this migration. As detailed earlier, the process for obtaining the necessary DLL files and registration keys involves opening a Dexterity support incident. Remember that this initial request for keys is typically free of charge.

However, if you require assistance with the technical implementation of GPConn.dll or GPConnNet.dll within your specific application code, or if you encounter complex issues during development or testing, subsequent support incidents may be billable. Be prepared for this possibility and prioritize utilizing the provided documentation and planning your implementation carefully.

For general information regarding technical support options available to Microsoft Business Solutions partners, customers, and Independent Software Vendors (ISVs), you can refer to Microsoft’s official support channels and policies. These resources outline the different support plans, incident submission procedures, and available support levels.

By carefully following the steps outlined in this guide and leveraging the resources available, organizations can successfully migrate their applications to use the modern GPConn.dll or GPConnNet.dll components, ensuring continued compatibility and robust integration with Microsoft Dynamics GP version 9.0 and later.

```mermaid
graph TD
A[Application using Crypto.dll] → B{Affected by GP 9.0+ Password Policy?};
B – Yes → C[Crypto.dll is Deprecated];
C → D[Need New Connection Method];
D → E{Platform: .NET or COM/Win32?};
E – .NET → F[Choose GPConnNet.dll];
E – COM/Win32 → G[Choose GPConn.dll];
F → H[Obtain GPConnNet.dll & Keys via Support];
G → I[Obtain GPConn.dll & Keys via Support];
H → J[Modify Code: Replace Crypto Calls with GPConnNet];
I → K[Modify Code: Replace Crypto Calls with GPConn];
J → L[Test Updated Application];
K → L;
L → M[Deploy Updated Application];
M → N[Application using GPConn.dll/GPConnNet.dll];
B – No → O[Continue using Crypto.dll (Older GP Versions Only)];

click H "Open Support Incident for Keys" tooltip "Open a Dexterity Support Incident to request keys"
click I "Open Support Incident for Keys" tooltip "Open a Dexterity Support Incident to request keys"

```

This diagram illustrates the decision points and flow involved in the migration process, highlighting the transition from the legacy Crypto.dll based application to one using either GPConn.dll or GPConnNet.dll.

What challenges have you faced when migrating applications in Microsoft Dynamics GP? Share your experiences and tips in the comments below!