TM BlueDragon 7.1 Deploying CFML on ASP.NET and the Microsoft .
NEW ATLANTA COMMUNICATIONS, LLC BlueDragon™ 7.1 Deploying CFML on ASP.NET and the Microsoft .NET Framework May 12, 2009 Version 7.1 Copyright 1997-2009 New Atlanta Communications, LLC. All rights reserved. 100 Prospect Place • Alpharetta, Georgia 30005-5445 Phone 678.256.3011 • Fax 678.256.3012 http://www.newatlanta.com BlueDragon is a trademark of New Atlanta Communications, LLC (“New Atlanta”). ServletExec and JTurbo are registered trademarks of New Atlanta in the United States.
Contents 1 INTRODUCTION........................................................................................... 1 1.1 About This Document............................................................................................................................. 1 1.2 About CFML ........................................................................................................................................... 1 1.3 About BlueDragon ................................................................
.1 .NET Framework Features That CFML Pages Inherit..................................................................... 15 4.2 CFML-based Database Processing is ADO.NET under the Covers ................................................. 18 4.2.1 CFQUERY Results Are ADO.NET DataTables, and Vice-versa.............................................. 18 4.2.2 ADO.NET Connection Pooling ................................................................................................. 18 4.2.3 DSN-Less Connections..
7.2 Manually Configuring CFML Extension Mappings.......................................................................... 38 7.2.1 “Manual Configuration” Installation Option ............................................................................. 38 7.2.2 XCopy Deployment ................................................................................................................... 40 7.2.3 Hiding CFM Extensions ......................................................................................
1 Introduction BlueDragon 7.1 for the Microsoft .NET Framework (commonly referred to as BlueDragon.NET) allows CFML applications to be deployed on Windows servers running the Microsoft .NET Framework, the Microsoft IIS web server, and ASP.NET. The Microsoft .NET Framework is built-in to Windows 2008 Server, Windows Vista, and Windows 2003 Server; and, can be installed onto Windows 2000 and Windows XP. While most web applications on .NET are built with ASP.NET and other components of the .
1.3 About BlueDragon The core technology of BlueDragon is a CFML runtime and execution module that, in BlueDragon.NET, is implemented as a standard ASP.NET HTTPHandler. This allows the deployment of CFML pages onto the .NET framework and IIS without installing proprietary Allaire/Macromedia ColdFusion server software. BlueDragon is highly compatible with Macromedia’s ColdFusion MX 7.0 Server, with some limitations but also many enhancements. Beside those mentioned in this guide, see the BlueDragon 7.
• BlueDragon 7.1 CFML Compatibility Guide • BlueDragon 7.1 CFML Enhancements Guide • BlueDragon 7.1 User Guide Each of these documents offers useful information that may be relevant to developers, installers, and administrators using BlueDragon.NET. These are offered in PDF format in the docs directory where BlueDragon is installed (as discussed in section 2.1.4). All BlueDragon documents are available from New Atlanta’s web site: http://www.newatlanta.com/products/bluedragon/self_help/docs/index.
2 Getting Started with BlueDragon.NET This quick start chapter covers the minimum information needed to get started with deployment of CFML on Microsoft .NET, including Windows 2000, Windows XP, Windows Server 2003, Windows Vista, and Windows Server 2008. While the simplest approach will have you running your CFML on .
Figure 1. Installing IIS and ASP.NET on Windows Vista BlueDragon 7.1: Deploying CFML on ASP.NET and the Microsoft .
Figure 2. Installing IIS and ASP.NET on Windows Server 2008 2.1.3 Windows 2003 Security Settings Windows Server 2003 and IIS 6 are configured by default to not permit ASP.NET pages to execute, and you must enable this feature to allow processing of CFML pages. The configuration is discussed in the following resource: http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS /44f16c37-f727-4244-9813-2289e13dadba.mspx Briefly, to enable ASP.NET by using the IIS 6 version of IIS Manager: 1.
http://www.microsoft.com/windowsserver2003/technologies/security/configwiz /default.mspx 2.1.4 Windows “Data Execution Protection” Mechanism Editions of Windows XP SP 2 and Windows Server 2003 may enable a security feature called Data Execution Protection (or DEP). If enabled, this may prevent the BlueDragon installer from running. See the following for more information: http://support.microsoft.com/kb/875352 2.1.
2.2.1 Installation Alternatives You will next be offered a choice of four options for installing BlueDragon.NET, which will configure the Microsoft IIS web server and .NET framework to process files with the .cfm, .cfml, .cfc or .cfchart extension.
When you uninstall BlueDragon.NET, it will preserve your previous settings, including admin console configuration and more. If you are upgrading and are concerned about protecting your files, simply make a copy of the relevant configuration and work directories (as discussed in section 5.2) before upgrading. To uninstall BlueDragon.NET, use the Windows Control Panel feature, Add or Remove Programs. 2.3 Placing Your CFML within IIS Web Site(s) Once installed, BlueDragon is configured so that IIS and the .
that may be new to both CFML and ASP.NET developers. These are discussed in sections 6 and 7. Additional resources for understanding .NET are provided in section 9. If you have difficulty with anything related to BlueDragon, please note that we have several sources of free and paid support. See the discussion of technical support in section 1.5. BlueDragon 7.1: Deploying CFML on ASP.NET and the Microsoft .
3 Benefits of Deploying CFML on .NET BlueDragon for the Microsoft .NET Framework allows existing CFML applications to be redeployed onto any server that’s running the Microsoft .NET Framework 2.0 or higher, eliminating the need for proprietary Adobe ColdFusion servers. It’s also important to note that BlueDragon.NET is not a server or service but instead extends the .NET Framework in a standard way (via an HttpHandler) so that it can process CFML.
• .
Each of these integration features is discussed in further detail in the manual, Integrating CFML with ASP.NET and the Microsoft .NET Framework. 3.2.3 Benefits from Learning and Using ASP.NET Additional Features Still other benefits of ASP.NET are worth exploring, some of which can be leveraged by integrating CFML and ASP.
3.2.5 Benefits In Learning ASP.NET and .NET At Your Own Pace Most important to some, web developers can continue to enjoy the productivity and ease-of-use of CFML, but in a standard .NET environment. We make it easy for CFML developers to learn about and integrate with ASP.NET and the .NET Framework, at their own pace and without need to learn many of the details usually associated with such programming.
4 .NET Features Requiring No Change in CFML Code There are some features of the .NET Framework which provide benefit to CFML developers even if they don’t change any of their CFML code. New Atlanta believes that .NET simply provides a better platform for CFML execution. This section discusses some of the features. 4.1 .NET Framework Features That CFML Pages Inherit There are several features that the .NET framework enables which normally are discussed only with respect to processing ASP.NET pages.
service running on the same or another server). If BlueDragon is configured to use .NET sessions (in the BlueDragon Admin console), then CFML session variables also benefit from this feature. This gives session variables many of the benefits of client variables while also enabling clustering of sessions. For more information, see any discussion of the .NET sessionState directive, such as in: http://msdn2.microsoft.
has its own BlueDragon admin console and can be configured independently. Of course, each may also have its own .NET configuration settings (as enabled in the web.config file, discussed in 6.3). These multiple admin consoles all also inherit from a single, central bluedragon.xml file, as discussed in section 5.2.2. • Leveraging IIS Application Protection (Pooling) o In Windows 2003 using IIS 6, it’s possible to designate multiple .
• Leveraging .NET Tracing/Debugging Output o It is possible to configure web applications in the .NET framework so that you can enable tracing/debugging output to be created either on a given page or in an available trace monitoring page (trace.axd) that can track output from any page request from any user. For more information, see: http://www.dotnetjunkies.com/quickstart/aspplus/doc/tracelogapp.
4.2.3 DSN-Less Connections ColdFusion 5 had added support for a new DBTYPE=”dynamic” option on CFQUERY and related database processing tags. CFMX removed support for that feature, as did the Java editions of BlueDragon. But the .NET edition of BlueDragon now supports this feature. For more information, see the discussion of CFQUERY in the BlueDragon 7.1 CFML Enhancements Guide. 4.2.4 ASP.NET Connection Strings BlueDragon.NET also supports the use of ASP.
5 Accessing the BlueDragon Administration Console A unique feature of BlueDragon.NET is that every IIS web site and web application has its own separate configuration data and administration console. For BlueDragon.NET on IIS 7.0—on Windows Vista and Windows Server 2008—BlueDragon administration is integrated with the IIS Manager. For BlueDragon.NET on IIS 6.0 (Windows Server 2003) and IIS 5.1 (Windows XP), BlueDragon administration and configuration is done via a browser-based administration console. 5.
The following figure illustrates configuring CFML Application Settings for the Default Web Site. Again, changes made to these configuration options will apply only to the Default Web Site, and not to any web sites that may be subsequently added to IIS. BlueDragon.NET provides detailed help files that are integrated with the IIS Manager help system. Access the help files by clicking the “Help” link under the “Actions” menu in the right panel of any BlueDragon.NET configuration page.
5.1.1 Server Settings and Configuration Inheritance The IIS Manager for IIS 7.0 allows some settings to be configured at the server level. Other settings—such as the CFML Search Collections and CFML Web Services for BlueDragon—are only configurable for individual web sites and web applications, and may not be configured at the server level.
Now consider the following figure, which illustrates the BlueDragon datasources configured for the Default Web Site. The “Entry Type” for the “ows” datasource is listed as “Inherited” indicating that this configuration setting was inherited from the server level. If the “ows” datasource is not needed by the Default Web Site, it can be deleted at the Default Web Site level without affecting the server-level configuration or any other web sites that may be subsequently configured for IIS.
5.2 BlueDragon.NET on IIS 6.0 and 5.1 The browser-based BlueDragon admin console for a given web site can be accessed via the following URL, replacing "www.server.com" with the host name or IP address of the web site: http://www.server.com/bluedragon/admin.cfm Note, however, that a unique difference in BlueDragon.
application”. If you prefer to have setting apply globally to all web apps, see section 5.1.2. (Also, to reset a virtual directory so that it does not have its own admin console, see section 5.1.3.) To open the BlueDragon admin console for a given web site, virtual directory, or directory configured in IIS as an application (any of these three will be referred from here on as simply a “web app”), append /bluedragon/admin.cfm to the URL for browsing the root of that web app.
BlueDragon.NET offers a unique solution to this challenge. There is a single, global bluedragon.xml configuration file, but it’s stored in the config directory under the central BlueDragon installation location, which by default is C:\Program Files\New Atlanta\BlueDragon.NET\. So, to effect a change that would apply to all webapp’s on a server, apply the needed XML to: C:\Program Files\New Atlanta\BlueDragon.NET\config\bluedragon.xml. The XML schema for the bluedragon.
Note that if any requests were made against CFML templates in that virtual directory after BlueDragon.NET was installed, BlueDragon will have created a new subdirectory within the c:\ Program Files\New Atlanta\BlueDragon.NET\WebSiten\ directory (as discussed next in section 5.2.1). The work files created for that virtual directory will be ignored once you reset it to not be a .NET application. The files are not removed by BlueDragon upon resetting it this way.
When BlueDragon.NET is deployed on IIS 5.1 on Windows XP, or on IIS 6.0 on Windows Server 2003, all BlueDragon configuration changes made in the BlueDragon Admin console are stored in a bluedragon.xml file. The location of that file in BlueDragon.NET depends on which of the four installation options was chosen, and it will be stored in a \config directory which will be a sibling to the \work directory, as discussed in the previous section.
sources. These datasource connections use native ADO.NET drivers for optimal performance. See the User Guide for more details on configuring and managing datasources. For other information on advantageous differences regarding datasources in the .NET edition, see section 4.2. 5.4 Securing the BlueDragon Admin Console This section applies to BlueDragon.NET when deployed on IIS 5.1 on Windows XP or IIS 6.0 on Windows Server 2003; it does not apply to BlueDragon.NET when deployed on IIS 7.
See the online help for this screen in the Admin UI for more information. Support for IP address exclusion filtering (restricted IPs) is being considered for a future release. 5.4.4 Remove the Admin UI Completely Rather than rename or restrict the admin URL, some may prefer instead to entirely remove it. There are two ways to remove the Admin UI. First, you can edit the bluedragon.xml (for the web site or application, as discussed in section 5.2.
6 Understanding the Microsoft .NET Framework This section is an introduction to the Microsoft .NET framework for developers who are new to this subject. Experienced .NET developers may still want to follow along. Configuring the .NET framework to support CFML involves steps that ASP.NET developers wouldn’t normally need to perform. Fortunately, the installer for BlueDragon.NET will perform this configuration automatically.
If you prefer to avoid making such changes to the GAC, the fourth option in the BlueDragon installer will instead create a single virtual directory with all BlueDragon DLL files implemented in its own /bin directory. Note as well that there is a /bin directory may exist within the docroot for any web site, virtual directory root, or directory declared in IIS to be an application, and you may place your own application-specific DLL files there. 6.3 Web.
If you have properly configured IIS and .NET for ASP.NET support, you may notice that the extension mappings in IIS for ASP.NET files (such as ASPX, ASMX, and ASCX) are configured so that they are handed to the aspnet_isapi.dll file defined for the .NET framework such as: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll. With BlueDragon.NET, CFML files are also to be handed to this same aspnet_isapi.dll file (not to BlueDragon itself). This is yet another testament to how BlueDragon.
Figure 3. Configuring a Directory as an Application Once you select the Create button, the Application Name field changes from Default Application to the name of the directory or virtual directory. Note that you can revert the directory to not being an application by selecting the Remove button that would appear in place of Create in the figure above. As discussed in section 5.1.
7 Other Configuration Issues Following are discussions of various configuration issues related to deploying CFML on .NET. 7.1 Restarting .NET and .NET Web Applications As discussed in previous sections, your CFML applications become native .NET applications, at least from the perspective of IIS and .NET. It may be desirable to restart a given .NET web application, or the entire .NET Framework, such as after making certain kinds of coding changes or when trying to resolve a problem.
<%@ Page Language="c#" %> <% System.Web.HttpRuntime.UnloadAppDomain(); %> Restarted web app <%= System.Web.HttpRuntime.AppDomainAppVirtualPath %> at <%= System.DateTime.Now.ToShortTimeString() %> Save this code into a file, perhaps called restart-webapp.aspx, and call it whenever you want or need to restart the .NET web application. Note that in addition to unloading the .
Still another approach would be to leverage one of the many automatic means built into .NET for restarting a web application (discussed in section 7.1.2). For instance, if an application’s web.config file is edited, that will restart the application. 7.1.2 Automatic Stopping/Restarting of .NET Web Applications It’s important to be aware that the .NET Framework itself will stop (unload) web applications automatically under various conditions.
7.1.3 Implications on Sessions of Restarting .NET Web Applications One of the most important implications of restarting web applications is that, assuming session variables are stored in memory (which is the default in .NET) and you are using .NET sessions for your CFML, when the web application restarts, all session variables will be lost. As discussed in Section 4, it’s possible to declare that a .NET web application should use an alternative form of persistence, including a database or state server.
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll The exact path may vary on your installation. See the mapping for ASPX pages to find the precise executable path for your installation. The extension mappings can be configured for the default web site, any given web site, a virtual directory, or a directory configured in IIS to be an application.
extensions in a given application pointing to different editions of the .NET framework, which can cause problems. Additionally, if you select the 2.0 option (to configure files to be processed by .NET 2.0), another new option, the Edit Configuration button, is enabled on the ASP.NET tab. This option opens a useful visual editor for making web.config file changes. Even more powerful, it reflects any entries that are inherited from high-level web.config files or the global machine.
http://www.west-wind.com/Tools/WebSiteConfiguration.asp As you contemplate the steps in this section, be aware that you cannot install BlueDragon more than once on a given machine. If you already have implemented any of the other installation options, you cannot run the installer again to use the fourth option to create a single virtual directory deployment. Instead, you must either uninstall BlueDragon or run the installer on a machine (or virtual machine) that does not yet have BlueDragon installed. 7.
7.4 No Default Document Defined by BlueDragon.NET The BlueDragon installer does not declare index.cfm or any other filenames in the IIS list of “default documents” (to serve up such a file if the URL from a browser request has no file name). If your code relies on that feature, please add that yourself using the Documents tab in the Properties dialogue for the web site, virtual directory, or directory configured in IIS to be an application. 7.5 Invoking CFX Custom Tags in .NET BlueDragon.
8 Troubleshooting CFML Processing on .NET When having trouble with execution of CFML pages in BlueDragon.NET, the following tips regarding the processing of CFML on the .NET framework may help. Additionally, see a further discussion of general CFML troubleshooting tips in the BlueDragon 7.1 CFML Compatibility Guide. 8.1 CFML Pages Do Not Run at All When CFML pages do not run at all, the following may identify possible solutions. 8.1.
several ways to make it know how to process ASP.NET pages. If IIS is not installed when .NET is installed, these required changes are not made. A simple way to determine if this is the problem is if you observe the extension mappings for your web site or directory. If you find that CFM file extensions are mapped to the aspnet_isap.dll (see sections 6.4 and 7.2.1) but there are no file extension mappings for ASP.NET pages (such as aspx, asmx, and ascx files), .
You could use this information to find the appropriate admin console (by using the first value reported to help create the proper URL to request the admin console, as also discussed in 5.1.1). If it seems burdensome to have to declare some setting in multiple admin consoles, recall that all web applications do inherit from a single, central, bluedragon.xml file, discussed in section 5.1.2.) Finally, as explained in section 5.1.
In particular, the default value for the httpRuntime section’s executionTimeout and appRequestQueueLimit values may not be set appropriately for your application or environment. Similarly, the element in the machine.config (also discussed briefly in section 7.1.2) controls various settings that can impact your performance if not configured suitably for your environment.
that have been run since startup of the current instance of the .NET framework. There are nearly 50 counters produced that can give very compelling information. There is another category called ASP.NET v2.0.50727 and it tracks still other details about running applications. In.NET 2.0, the number and value of these Perfmon counters has increased considerably. 8.3.3.2 Using Perfmon to View, Log, Trace, and Alert About Performance Perfmon is very flexible.
port discussion in section 1.5 for contact information. We want to hear from you in order to evaluate and attempt to resolve your challenge. 8.4 .NET Security Issues that May Affect CFML Processing The .NET Framework has implemented tighter security mechanisms to avoid common problems in web application development. Some more global settings were discussed in section 2.1.2. There are also several more localized security mechanisms that are specific to .NET.
Again, the solution is to grant permissions, as discussed in section 8.4.1, to allow .NET to write to the parsed directory for the Fusebox application. 8.4.2 Problems Processing Access Databases For similar security reasons, when trying to update an Access database using BlueDragon.NET, you may receive the error: Operation must use an updateable query. This is not caused by BlueDragon but instead the .NET framework. Indeed, the problem is discussed in the Microsoft Knowledge Base article: http://support.
under the authenticated user for authenticated requests and under the anonymous user for unauthenticated requests. 2. If web.config doesn't contain an element with the attribute impersonate set to true but the machine.config file does, then BlueDragon.NET will run under the username specified in the element. If an empty string is specified for the username then BlueDragon.
9 Additional Useful Resources Following are some additional resources that may prove helpful while working with the .NET Framework using ASP.NET, IIS, and BlueDragon. ASP.NET Configuration http://msdn.microsoft.com/library/default.asp?url=/library/enus/cpguide/html/cpconaspnetconfiguration.asp ASP.NET Performance Monitoring, and When to Alert Administrators http://msdn.microsoft.com/library/default.asp?url=/library/enus/dnaspp/html/monitor_perf.asp Developing High-Performance ASP.
