ASP #Include Upgrade Options

gmStudio supports three options for upgrading ASP #include files to ASP.NET:

1) Convert #include files Code Classes
2) Convert #include files to  web UserControls with associated code behind files
3) Convert some #include files to code classes and other to UserControls

Code Classes
The default ASP translation script template upgrades each #include file to a code class.  Converting a #include to a code classes makes sense if the #include files does not contain markup.  These "faceless" includes contain only declarations such as common constants, functions, and VBScript classes.  Note that when an #include containing markup is converted to a code class, gmStudio separates the markup and embedded code from the declarations and consolidates it into an AuthorMarkup function within the cod e class.  Calling the AuthorMarkup function renders the markup the HTTP response. The appropriate AuthorMarkup function is called wherever the #include file was referenced in the original ASP site.  

Web UserControls

If a #include file contains a lot of markup and possibly embedded code then it may be cleaner to upgrade it to a web UserControl.  This feature may be activated by adding few special instructions to the translation script; for example:

   <Select UseUserControls="on" />
   <LoadRuntime dllName="AspGlobalIncludes.dll" />

You must use a GlobalIncludes description file when you are using UseUserControls. 

1) Prepare a GlobalIncludes.xml script to generate a GlobalIncludes description file based on a global analysis the #include file usage throughout the site.
2) Place the GlobalIncludes description content in a GlobalSettings script to create a GlobalSettings file.
3) Reference the GlobalSettings file with the following: <Select GlobalSettings="%UserFolder%\GlobalSettings" />

When UseUserControls=on, gmStudio will declare a web UserControl with codebehind based on the content of each #include.  It will then Register a custom tag for each UserControl used a page and insert the customer tag #include file was referenced in the original ASP site.

Mixing Code Classes and Web UserControls

If you wish to selectively make some #includes into UserControls while others are done as code classes, you may add Registry commands to the default ASP script; for example: 

<Registry type="FixStatus" source="include_file_path" target="UserControl" />

Sample Translations
The sample is based on the fmStocks VB6/ASP upgrade sample and you shoudl review that documentation to get an overview of the upgrade feates. 

This project illustrates the upgrades being done three ways.  Specifically, the gmProj file has three different versions of the upgrade, each referencing a different site translation script:

tran.FMSWeb_Site_Cls.xml: produces an ASP.NET upgrade using Code Classes. The same as the upgrade done for the standard sample.
tran.FMSWeb_Site_Ctl.xml: produces an ASP.NET upgrade using UserControls.
tran.FMSWeb_Site_Mix.xml: produces an ASP.NET upgrade using UserControls for all the #includes except strings.asp.

Note: it is somewhat unusual to have different translation versions for the same source code, but it does make for a good demonstration.  And it makes it easy to compare the results by selecting any two upgrade tasks and clicking the compare button.  However, beware that all three of these tasks share the same deployment folder and when you deploy the results they will overwrite the content of the deploy folder.
Note: it is somewhat unusual to have different translation versions for the same source code, but it does make for a good demonstration.  And it makes it easy to compare the results by selecting any two upgrade tasks and clicking the compare button.  However, beware that all three of these tasks share the same deployment folder and when you deploy the results they will overwrite the content of the deploy folder.

The project also contains translation tasks to generate the GlobalIncludes and GlobalSettings files.

Please contact GreatMigrations if you have questions about this sample.


