Stingray Studio : Getting Started Guide : Chapter 4 Guidance on Migration Issues : Generalized Procedure for Migrating Stingray Studio Projects
Generalized Procedure for Migrating Stingray Studio Projects
Despite the many changes over the years, the Stingray Studio product has made a great effort to keep changes backward compatible. Because of this, migrating Stingray Studio projects to newer versions of Stingray Studio is generally straightforward. This procedure, which uses Objective Grid as the model, is adaptable to the other Stingray components. Notes at the end of the procedure address a few component-specific issues.
NOTE >> If your project was developed before the introduction of Stingray Studio in 2000, you first need to look at Chapter 5, “Migrating Applications to Stingray Studio”.
This procedure assumes you have Stingray Studio installed and a project called Workbook that you want to migrate from an earlier version of Stingray Studio. Parts of this procedure are shown as using Stingray Studio Assistant, but they could also be accomplished manually. To use the Assistant, your old project must have a solutions file (.sln). If instead you have a .dsw project, it must be converted manually in Visual Studio to the current compiler version, which creates a solution (.sln) file. You can then use Assistant for further migration steps.
1. Run the executable for Stingray Studio Assistant that corresponds to you compiler version. The executables are located in version-specific subdirectories of <stingray-install>\bin\UtilityTool and are also accessible through the Start menu entry for Stingray Studio.
2. If necessary, run the Build Wizard. For Grid, this is needed only if your project uses ExcelReadWrite or XMLLibrary, or if you are targeting the XP platform. If that is the case, select the needed components and continue on through the wizard to generate the needed files.
For more information on what the Build Wizard is doing, see “Build Wizard” on page 11.
3. In the Assistant, go to the Libraries tab, select the product to build (Grid), make sure the compiler setting is correct, and click Run. This starts up Visual Studio and loads the Grid solution.
4. From the configuration dropdown menu select the configuration to build -- e.g., All or Stingray DLL MFC DLL Debug (asd) -- and from the platform dropdown the bitness -- Win32 or x64, then select Build | Build Solution. You do not have to build the Stingray Foundation Library separately as it is built automatically as a dependency for Grid.
NOTE >> If you want to use any of the group configurations containing ‘All’, you must first build all the same configurations of the RWUXThemes library. You can do this through the Assistant or as a batch build in Visual Studio.
5. Once the build is complete, go back to the Stingray Studio Assistant and verify, in the Lookup tab, that the libraries show up as built. For MSVC <ver>|x64 and the asd configuration, these would be og<ver>asd and sfl<ver>asd.
6. If you want to be sure the libraries were built successfully, you can go to the Samples tab and run some sample solutions.
Once you are satisfied, it is time to convert your old project. We are assuming you have a project called Workbook.
7. In the Custom App tab of Assistant, add the path to the solution file to the Path text box. Then below the Path text box, click Convert under VC Version to update your solution to the current compiler version.
8. Again in the Assistant, click Set under Property Sheets to add a property sheet to your project that defines Stingray Studio paths.
The property sheets are located in <stingray-install>\src with names that use the pattern SS-[Win32|X64]-PropSheet<VC++-version>.props. For this procedure that would become SS-Win32-PropSheet12.props. You can set the property sheet manually in Visual Studio with the Property Manager. For more information on the use of property sheets, see “Property Sheets” on page 54.
9. In the Assistant, on the right side, click Open: Sln to open the updated solution in Visual Studio.
10. In Visual Studio, open the Configuration Manager (Build|Configuration Manager) to verify that the Build checkbox is selected for each configuration.
11. In Visual Studio, open the project properties by right-clicking on the project name and selecting Properties. Verify that Target Name in the General section matches the Output File name in Linker|General.
12. Still in Properties, in C/C++|Language, verify that Treat WChar_t As Built in Type is set to Yes.
This is important because the Stingray libraries are built with this option, and link errors may result if this option is set to No.
If your project needs to be built with this property set to No because of dependencies on 3rd-party libraries built that way, you must modify the project makefiles manually to add /Zc:wchar_t-, which will override the default compiler option.
13. In the project directory, open stdafx.h and add:
#include <SupportedPlatforms.h>
#include "ManifestDefs.h"
See one of these files in the samples for guidance on placement.
14. Macro names need to be changed, by adding the preface GRID_. For example, DECLARE_CONTROL needs to change to GRID_DECLARE_CONTROL. You can use the file <stingray‑install>\Include\Grid\GridExportDefs.h to verify the macro names used for Grid.
Here are other issues that may affect your efforts to migrate your project:
*The following functionality has been dropped from the current product: DAO, DBTools, and Grid for Active X. If you need help with these, please contact technical support. Be aware that larger projects may require help through our consulting team.
*If Objective Grid Layout files .ogl are used in the project and they were created with a very old version of Grid, they will likely first need to be redeveloped with the help of the Grid Designer, which you can access through Stingray Studio Assistant (see figure below).
The following issues are not truly migration issues. They are functionality that may have been added to Stingray Studio after you developed your older application and that you might be interested in taking advantage of.
*If your application was developed before the availability of the MFC Feature Pack and you would like to use these features in your migrated application, please see Chapter 6, “Support for the MFC Feature Pack,” on page 66. Stingray Studio Assistant also has a Feature Pack Convert function that may be of help. Use of the MFC Feature Pack applies not just to Objective Grid but to all of Stingray Studio.
*The export-import mechanism of classes and APIs in extension DLLs has changed in Stingray Studio. It is important to understand this change if Grid is used in a custom extension DLL. For information on extension DLLs, please see the section “Extending Stingray Libraries” on page 31 of the Getting Started Guide.
*Stingray-based applications can be built with the /clr option that allows the use of C++ /CLI code and .NET libraries. It is also possible to use Stingray components on a WinForm. See the samples in <stingray-install>\Samples\Grid\Integration with .Net. See also the Knowledge Base articles Stingray Studio MFC Projects Integration with .NET and Using Objective Grid with C++/CLI.
*You can also choose to port your project to C# using the Grid for .NET product. This product is not included in Stingray Studio but can be obtained separately.